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

  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://use.difr.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.
     
   • 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.
     
     
     

     Service Provider URLs 

     Upon creating a new Integration, your Service Provider is assigned two important URLs: 

     
     
   • Assertion Consumer Service (ACS) URL:  The endpoint where the Identity Provider (IdP) delivers SAML authentication responses after a successful login. 
   • Metadata URL:  A publicly accessible URL providing your Service Provider's SAML metadata, used by Identity Providers to configure and establish trust.
     
     Optional
     
   • 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.
     
     
   • 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. 

  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. 

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://api.use.difr.com/iam/<ID>/metadata.

   • Single Sign-on URL or Assertion Consumer Service (ACS) URL: This URL is in the form: https://api.use.difr.com/iam/<ID>/login/done.
      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

Once Permissions

the SAML2ProviderissuccessfullyconfiguredintheNutanix roles/permissionsfor Permissionswith

Hierarchy	Role	Permissions
Customer	Customer Administrator	Highest level of access. CustomerConsole, administrators arewill ableneed to createadd andauthorization managerules multiplefrom organizationsthe andSAML2 accounts.Permissions Customertab administratorslisted canto alsothe modify permissions for anyright of the userSAML2 rolesProvider listedtab. Add below.
Customer	Customer Analytics	Customer Analyticsyour users canby onlyfollowing accessour the Analytics graphs at the customer level.
Customer	Customer Auditor	Customer Auditor users have read only access to functionality at the customer, organizations,Roles and accountUser 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), configuresa SAML2 providers,IdP manageguides. 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.