Acquire Tokens through SSO (SAML2)

Through SAML2 integrations with Xi Frame, you can leverage existing SSO workflows to retrieve tokens for your users. Here’s a general overview of what that process looks like:

../../_images/session_api_sso_workflow_diagram.png

To get started, there are three key items needed when using SSO workflows to authenticate your users:

  1. You need to build a SSO URL for your SAML2 integrations. This URL is used to kick-off the authentication process to retrieve a token for your users.

  2. To use the token with our Session API, your web application should expect and grab the token search query parameter to be present in the URL.

  3. A SAML2 relying party is required for each domain name (e.g. example.com) you wish provide authenticated redirects to (e.g. acme.com or localhost:3000). This process is currently manual. Please create a support ticket in your My Nutanix portal for assistance.

Building a SSO URL

Using an existing SAML2 integration with Frame, you can construct an SSO link to authenticate your users and return them to the URI that is hosting your Xi Frame Session API.

For example, if you would like to return your users to https://example.com/xiframe-tutorial with a token after they authenticate using a SAML2 integration named saml2-tutorial-example, you can construct a Sign-on URL by specifying account_type and return_url params like so:

https://img.frame.nutanix.com/login?account_type=saml2-tutorial-example&return_url=https://example.com/xiframe-tutorial

Here’s a breakdown of the SSO URL:

../../_images/sso_breakdown.png

These three URL components tell us where to send users to login, and where to redirect their browser to (with a token) after they’ve successfully signed in.

URL Search Query Terms

URL Search Query Param

Description

Base Login URL

This URL points to the Frame environment you’d like to authenticate with. For most Xi Frame customers, this will be https://img.frame.nutanix.com/login?

account_type

This represents your SAML2 integration name. This tells our system where to redirect the user to login. This value is case-sensitive and must match the exact name of your SAML2 provider.

return_url

The URL you’d like to redirect your users back to after authenticating. When redirecting after a successful login, this URL is accompanied by a JWT in the URL as a search query parameter.

Capturing the token from the Return URL

When successfully authenticating with a SSO workflow, the browser will be redirected to the return_url with a token search query parameter.

For example, if a user successfully logs in using this SSO URL:

https://img.frame.nutanix.com/login?account_type=acme-saml2&return_url=https://example.com/frame-example

Frame will redirect the user’s browser back to the return_url with a token (JWT) appended as a search query parameter:

https://example.com/frame-example?token=xyz

Using Javascript, you can easily capture the value for use with the Session API:

// assign URL Search params to `params`
const params = new URLSearchParams(document.location.search);

// At this point, you can use the token with the Xi Frame Session API
const token = params.get('token');

// Session API Parameters
const terminalOptions = {
  serviceUrl: "https://cpanel-backend-prod.frame.nutanix.com/api/graphql",
  terminalConfigId: "38cb4f1c-a019-4163-9f1d-168b59fb5062.0f3a542b-884e-4edc-aa5f-65380597061",
  token: token
};

let terminal = await createInstance(terminalOptions);

// Optional: you can store the token somewhere for re-use, such as localStorage.
localStorage.token = token

// Optional: Clear the token from the URL
params.delete('token');
window.history.replaceState({}, document.title, document.location.pathname + params.toString());