General SAML2 Integration

The administrative workflow for setting up a SAML2 identity provider (IdP) consists of the following steps:

1. Enable SAML2 Providers at the desired entity level (Customer, Organization, or Account).
2. Create a SAML2 identity provider in Frame.
3. Enter the necessary configuration information for your new SAML2 identity provider in Frame.
4. Enter the configuration information in your actual SAML2 identity provider.
5. Verify that both sides of the IdP integration are properly configured by attempting to login using your identity provider.
6. Add SAML2 Permissions (authorization rules) at the Customer, Organization, or Account entity level to authorize users to specific roles.

Depending on the specific SAML2 identity provider, you may need to perform Step 4 before Step 3.

Frame supports both IdP-initiated and SP-initiated authentication workflows. In general, most customers implement SP-initiated authentication workflows by directing users to a Frame URL and letting Frame redirect the user to the SAML2 identity provider.

Getting started

To begin, let's create a URL-friendly SAML2 Integration Name that we'll use in a few places throughout our setup. Continue below for help and examples that you can use in your SAML integration.

<IntegrationNameHelper idpName="SAML2 Identity Providers" idpUrlName="YourIdPName" />

Using the values copied from above and following the steps below, we'll create and gather these details to configure proper communication between your IdP and Frame.

1. Before a SAML2 identity provider can be added, the administrator must enable SAML2 Providers at a given level by navigating to the Admin Console. From there, navigate to the Customer or Organization page (depending on where you wish to add the IdP). Select Users from the left-hand menu.

Unless there is a specific reason to do otherwise, adding the SAML2 Provider at the Customer or Organization level is best practice.

:::

2. Enable the SAML2 toggle under the Authentication tab and click Save.

   

3. You'll see a new "SAML2 Providers" tab appear; click it and you'll see a Add SAML2 provider button.

   

Creating a SAML2 Provider

1. In the SAML2 Providers tab, click Add SAML2 Provider at the top right. A dialog to add a SAML2 provider will appear.

   

   • Application Id: This field is sometimes referred to as Service Provider (SP) "Entity ID" or "Audience URI". It can technically be any text but is usually in the form of a URL and is often simply https://frame.nutanix.com. For successful authentication, it is important that value entered in this field matches at least one of the values within "Audience Restriction" list that is part of the SAML2 assertion created by Identity Provider (IdP).
   • Auth provider metadata: Check the "URL" option and paste the Identity Provider metadata URL from your SAML2 IdP. The metadata URL must be publicly accessible to Frame Platform on the Internet.
   • Integration Name: Enter your unique SAML2 Integration name here. This is defined in the Getting Started section at the beginning of this page.
   • Custom Label: When specified, this value will be used in the login page as Sign in with <Custom Label>.
   • Authentication token expiration: Set the desired expiration time for the authentication token. This can range from 5 minutes to 7 days. If the user is inactive for the configured amount of time, Nutanix Console will logout the user from Nutanix Console. If the user is active within the console (e.g., clicks on hyperlinks, moves the mouse/cursor, scrolls, or presses keys), the token will be renewed just before the user token expires. If the user is in a Frame session, the token is automatically renewed so the user is not disconnected while in session.
   • Signed response: Disable or enable based on your SAML2 identity provider.
   • Signed assertion: Disable or enable based on your SAML2 identity provider.

   :::note

   The SAML2 identity provider is typically configured to sign the SAML2 Authentication Response message or the SAML2 Assertion embedded within the Authentication Response message (and not both). The choice of what is signed by the SAML2 IdP must be the same choice in the Frame SAML2 IdP configuration. Otherwise, Frame will return a identity provider misconfiguration error when Frame processes the SAML2 Authentication Response from the SAML2 IdP.

   :::

2. Click Add when ready to create the SAML2 Provider definition.

Configure your SAML2 IdP

3. Each SAML2-compliant identity provider will have its own configuration requirements. However, there are some common configuration parameters used by SAML2 identity providers:

   • Frame Metadata URL: This URL is in the form: https://img.frame.nutanix.com/saml2/metadata/[SAML2_INTEGRATION_NAME]/.

   • Single Sign-on URL or Assertion Consumer Service (ACS) URL: This URL is in the form: https://img.frame.nutanix.com/saml2/done/[SAML2_INTEGRATION_NAME]/. The SAML2 IdP will send the SAML2 Authentication Response to this URL.

   :::caution

   Administrators choosing to cache or store the Frame public key certificates in their SAML2 IdP will need to update those public key certificates when Dizzion renews them.

   :::

   :::note

   Frame does not support the SAML2 Single Logout Request.

   :::

Mandatory SAML2 Attributes

1. In order for Frame to display properly the user's first name, last name, and email address in the Dashboard and Launchpad, your SAML2 identity provider configuration must provide these four mandatory user attributes/values using the specified SAML2 attribute names, as described in the following table:

   User attribute	SAML2 attribute name
   First name	Use givenName, /urn:mace:dir:attribute-def:givenName/, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname SAML2 nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:basic
   Last name	Use sn, /urn:mace:dir:attribute-def:sn/, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname SAML2 nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:basic
   Email address	Use mail, /urn:mace:dir:attribute-def:mail/, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, or http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name SAML2 nameFormat: urn:oasis:names:tc:SAML:2.0:attrname-format:basic
   Name ID	NameID SAML2 nameFormat: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

Optional SAML2 Attributes

Customers can configure their SAML2 IdP to include additional SAML2 attributes in the SAML2 Authentication Response messages to Frame Console. These SAML2 attributes and their user-specific values can then be referenced when configuring Frame SAML2 Permissions to enforce role-based access control (RBAC).

The most common SAML2 attribute included by administrators in SAML2 Authentication Response messages would be a SAML2 attribute that is associated with a list of groups, such as a list of Active Directory groups, that the user is a member of. This allows the administrator to the SAML2 Permissions based on groups (and not individual user email addresses) and then associate the users to those groups in their IdP (or Active Directory, if their SAML2 IdP is connected to their Active Directory).

Frame also supports two Frame-specific SAML2 attributes to customize the logout/login workflow:

• frame_logout_url: user is directed to this URL when the user logs out of the Launchpad or if they decide to leave Frame after being logged out due to inactivity.

• frame_login_url: user is directed to this URL when the user wants to log back into Frame after being logged out due to inactivity.

When adding additional SAML2 attributes, make sure to record the optional attribute name(s) to be used (and possible values). For example:

• groups
• Department
• http://schemas.xmlsoap.org/claims/Group
• http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

as the exact attribute name must be referenced in the condition section with the appropriate values of a SAML2 Permissions authorization rule.

Configuring SAML2 Permissions

Role Permissions

Hierarchy	Role	Permissions
Customer	Customer Administrator	Highest level of access. Customer administrators are able to create and manage multiple organizations and accounts. Customer administrators can also modify permissions for any of the user roles listed below.
Customer	Customer Analytics	Customer Analytics users can only access the Analytics graphs at the customer level.
Customer	Customer Auditor	Customer Auditor users have read only access to functionality at the customer, organizations, and account levels.
Customer	Customer Security Administrator	Customer Security Administrator users can only access Audit Trail and Users functions at the customer level to manage all auth providers (Basic (username/password), Google, SAML2, API, SAT), configures SAML2 providers, manage SAML2 permissions, and manages users (if Frame IdP is enabled) for all organizations and accounts.
Customer	Customer Support	Customer Support users can only access the Summary, Analytics, Audit Trail, and Status pages for Accounts under the customer level to review activity and research user sessions. They can reboot, terminate VMs, and close sessions. They can detach personal drives and enterprise profile disks (if the disks do not detach after session closing) and backup, restore, and delete personal drive and profile disk volumes.
Customer	Limited Customer Administrator	Limited Customer administrators possess the same permissions as Customer administrators for managing organizations and accounts. However, they do not have the ability to create organizations or accounts, manage users, or start sessions.
Organization	Organization Administrator	Organization administrators can manage any organizations assigned to them by the Customer or Limited Customer administrator and those organizations' accounts. Organization administrators can only be created by Customer or Limited Customer administrators.
Organization	Limited Organization Administrator	Limited Organization administrators can manage organizations assigned to them by Customer or Organization administrators and those organizations' accounts. However, they do not have the ability to create accounts, manage users, or start sessions.
Organization	Organization Analytics	Organization Analytics users can only access the Analytics graphs at the specified organization level.
Organization	Organization Auditor	Organization Auditor users have read only access to the organization and accounts under the organization.
Organization	Organization Security Administrator	Organization Security Administrator users can only access Audit Trail and Users functions at the specified organization level to manage all auth providers (Basic (username/password), Google, SAML2, API, SAT), configures SAML2 providers, manage SAML2 permissions, and add users (if Frame IdP is enabled) for all accounts under the specified organization.
Organization	Organization Support	Organization Support users can only access the Summary, Analytics, Audit Trail, and Status pages for Accounts under the specified organization level to review activity and research user sessions. They can reboot, terminate VMs, and close sessions. They can detach personal drives and enterprise profile disks (if the disks do not detach after session closing) and backup, restore, and delete personal drive and profile disk volumes.
Account	Account Administrator	Account administrators can access and manage any accounts assigned to them by the Organization, Limited Organization, Customer, or Limited Customer administrators.
Account	Limited Account Administrator	Limited Account administrators possess the same permissions as Account administrators for managing accounts. However, they do not have the ability to manage users or start sessions.
Account	Account Analytics	Account Analytics users can only access the Analytics page in the account Dashboard.
Account	Account Auditor	Account Auditor users have read only access to the account Dashboard.
Account	Account Security Administrator	Account Security Administrator users can only access the Users and Audit Trail pages in the account Dashboard to manage all auth providers (Basic (username/password), Google, SAML2, API, SAT), configures SAML2 providers, manage SAML2 permissions, and manage users (if Frame IdP is enabled) for the specified account. They are also able to access Audit Trail and Session Trail for the specified account.
Account	Account Support	Account Support users can only access, at the Account level, the Summary, Analytics, Audit Trail, and Status pages to review activity and research user sessions. They can reboot, terminate VMs, shadow sessions, and close sessions. They can detach personal drives and enterprise profile disks (if the disks do not detach after session closing) and backup, restore, and delete personal drive and profile disk volumes.
Account	Sandbox Administrator	Sandbox Administrator can only access the Sandbox page in the account Dashboard to manage the Sandbox (e.g., schedule a publish, power on/off VM, install and update applications, update the OS, backup Sandbox, restore from backup, change instance type, and clone to another Sandbox, if authorized).
Account	Utility Server Administrator	Utility Server Administrator can only access the Utility Server page in the account Dashboard to add, manage, and terminate utility servers.
Account	Launchpad Administrator	This account-level role can only add, delete, and change Launchpad definitions.
End User	Launchpad User	End users or "Launchpad users" can only access Launchpads that are configured by the administrators. A Launchpad user can access multiple Launchpads from multiple accounts if configured this way by administrators.
API	API - Generate Anonymous Customer Token	Authorizes the API requestor to obtain Secure Anonymous Tokens from Frame Admin API for starting Frame sessions in all Frame accounts under the specified Customer entity.
API	API - Generate Anonymous Organization Token	Authorizes the API requestor to obtain Secure Anonymous Tokens from Frame Admin API for starting Frame sessions in all Frame accounts under the specified Organization entity.
API	API - Generate Anonymous Account Token	Authorizes the API requestor to obtain Secure Anonymous Tokens from Frame Admin API for starting Frame sessions in the specified Frame account.

The Group claim, created in the prior section, must be referenced as http://schemas.xmlsoap.org/claims/Group when creating the SAML2 Permission authorization rule.

SAML2 Configuration Lock

Customer Administrators have the option to lock SAML2 IdP configurations at the Customer level of the Frame tenant. When the toggle pictured below is enabled, SAML2 IdP integrations cannot be added from the Organization or Account levels of the Frame tenant.

Signing into Frame with your SAML integration

Your SAML integration will now appear to your users as a sign in button on your specific Frame Sign in Page.