Azure AD

Integrating Azure AD Single Sign On (SSO) is a quick and easy process. Before we get started, take note of five pieces of data that you'll be using to setup a proper SAML2 integration.

• The Frame SAML2 Integration Name. This is an arbitrary name value that you'll need to come up with. This value is used to uniquely identifies your integration with Frame and used to craft the SAML2 URIs, as well as used as a search vector for troubleshooting and logs.
• The Azure AD Federation Metadata Document URL. This is the Azure AD-provided URL where Azure AD keeps the SAML metadata for your Azure application. The metadata URL must be publicly accessible to Frame Platform on the Internet.
• The Application ID from your Azure application.
• The Redirect URI. This is the Frame destination URL that will process the Azure AD-generated assertions/claims after users authenticate through Azure AD.
• The Entity URL that you will use as your landing page. Please see the Entitys and URLs section to help you decide/find the right URL.

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.

Integration Name examples for Azure AD

Your SAML2 Integration Name is a case-sensitive, URL-friendly, unique, and descriptive value that represents the integration between your Azure AD and Frame. This value can have only letters, numbers, and the dash symbol; no spaces or punctuation are allowed.

We recommend using something that includes descriptive information, such as your company and identity provider's names. This integration name is tied to your SAML2 endpoints on Frame and using descriptive names can be useful for debugging.

Optionally, fill out the information below to get a recommendation of what you could use.

1. Enter your company name:

2. Customize your IdP Name:

3. Pick a style:
Bobs-Burgers-Frame-AzureAdgreat
bobs-burgers-frame-azuread
Bobs-Burgers-AzureAdgood
bobs-burgers-azuread
BobsBurgersAzureAd
Bobs-Burgersnot very descriptive

4. Copy values

Integration Name:

Bobs-Burgers-Frame-AzureAd

Copy your Redirect URI:

https://img.console.nutanix.com/saml2/done/Bobs-Burgers-Frame-AzureAd/

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

Configure Azure AD

Azure AD allows administrators to create Azure AD Enterprise Applications or App Registrations in Azure AD. As a best practice, we recommend you create an Azure AD Enterprise Application. With an Enterprise Application, you benefit from being able to:

1. Have Frame automatically logout your users from Azure AD when they log out of Frame.
2. Enable Azure AD to redirect your users to a specific URL after the users are logged out of Frame and Azure AD.
3. Explicitly specify the users and groups who can access Frame.

To create an Enterprise Application, you will need to have at least one of the following Azure AD permissions:

1. Global Administrator: This role has the highest level of access to an Azure AD tenant and can perform any action in Azure AD, including creating enterprise applications.
2. Cloud Application Administrator: This role can create and manage enterprise applications in Azure AD, but cannot manage the Azure AD tenant itself.
3. Application Administrator: This role can create and manage enterprise applications in Azure AD, but only for a specific set of applications assigned to them by a Global Administrator or Cloud Application Administrator.

In case you do not have any of above Azure AD Roles, you can create an Azure AD App Registration; however, you will not have the Enterprise Application benefits described above.

note

If you are registering your own Azure subscriptions, you might have already created app registration by following our BYO Azure Subscription process. For integrating Azure AD to Frame as a SAML2 identity provider, please create a new Enterprise Application for user authentication purposes.

note

If you want Frame to redirect your users to log out of Azure AD and be redirected to a specific web page after they log out of Frame, please submit a Support ticket describing where your SAML2 IdP Provider is registered (e.g., the Frame Customer or Organization entity), the SAML2 Integration Name, and the URL you wish Azure AD to redirect the users to after they are logged out of Azure AD.

Enterprise Application

First, we'll start by registering a new Azure Enterprise Application. This will provide us with a few data points mentioned earlier that we'll use in later steps.

1. First, go to your Azure portal. Search for "Enterprise Registrations" in the top search bar. Click on it in the results list.

   

2. Click on New Application.

   

3. Click on Create your own application, enter the name of your app (e.g., "Dizzion Frame"), select the option “Integrate any other application you don’t find in the gallery (Non-gallery)” and click on Create.

   

4. Once the new application has been created, open the Properties configuration page.

a. If you want anyone from your Azure AD tenant to be able to authenticate to this application, make sure that the Assignment required? slider is set to No. Click on Save.

b. If you only want specific users or groups to be able to authenticate to this application, make sure that the Assignment required? slider is set to Yes. Click on Save. Then go to Users and groups, click Add user/group and select desired users/groups who will be able to access Frame.

5. Go to App Registration. Search for "App Registrations" in the top search bar. Click on it in the results list.

   

6. Select All Applications tab and click on your newly created App.

   

7. Open the Branding & Properties configuration page and configure Home page URL. When users navigate to Frame from their Azure Portal, this URL is where the users will initially land. This URL could point to a Launchpad but if you have admins using this same app registration, you may want to direct all users to the Customer or Organization URL and let Frame redirect the user based on their SAML2 Permissions. For help deciding on a URL to use, see our Entities and URLs documentation page.

8. Open the Authentication configuration page and under Platform configurations click + Add a platform.

9. In the Configure platforms selection pane, under "Web applications", select Web.

10. In the Redirect URIs text field, please enter your Redirect URI in the form:

https://img.frame.nutanix.com/saml2/done/YOUR-UNIQUE-SAML-INTEGRATION-NAME/

and click on Configure.

note

Be sure to replace YOUR-UNIQUE-SAML-INTEGRATION-NAME in the URL with your own SAML Integration Name. Slash (“/”) after your unique SAML Integration Name is mandatory!

11. Next, we're going to assign certain claims/assertions to be sent to Frame. This ensures we'll get email addresses in the correct format, and we can optionally pass Azure Group memberships as claims. Click on Token configuration from the side menu on the left. Click Add optional claim button, then select SAML. Check email in the Claim list and click Add at the bottom.

info

When adding the email claim, you'll see a confirmation dialog to turn on required permissions for OpenID Connect scopes. Leave this box checked and click "Add".

12. If you'd like to pass group claims to Frame for roles/permission assignment, click the Add groups claim button near the top of the page. If you don't need to pass Group memberships as claims/assertions, you can skip this step.

Under Edit groups claim, select the groups type(s) you'd like to include in the assertions to Frame. In our screenshot, We selected “Security groups” and “Groups assigned to this application”. Later, we can match against these groups (via group IDs) for assigning roles and permissions from the Frame Console. Additional information regarding groups can be found in Microsoft's official documentation.

For enterprise customers who have more than 150 security groups in their Azure AD tenant, you should only check "Groups assigned to this application", leaving all other checkboxes unchecked.

Next, expand the SAML section and choose Group ID, then click Add. This will instruct Azure AD to reference each Azure AD group by its Group ID in the SAML2 assertion.

note

If a user is a member of Group B, and Group B is a member of Group A, then the group claims for the user will contain both Group A and Group B. When an organization's users have large numbers of group memberships, the number of groups listed in the token can grow the token size. Azure AD limits the number of groups that it will include in a token up to a maximum of 150 for SAML assertions and 200 for a JWT. If a user has more than 150 groups, the groups are omitted in the SAML assertion. A link to the Microsoft Graph endpoint to obtain group information is included instead. Further details are at Microsoft's Azure AD documentation.

13. Now that your Enterprise Application and App Registration is configured, you will need to obtain the Application ID for this App Registration. Click on Overview in the lefthand side of the page. Copy the Application ID and save it for later use.

14. Click on Endpoints and copy your Federation Metadata URL for later use.

15. Finally, click on Authentication under Manage and note your SAML2 Integration Name which is embedded in the Redirect URI. In the example screenshot below, the SAML2 Integration Name is NutanixFrame.

Next, we'll use the Application ID, Federation Metadata URL, and Integration Name to set up Azure AD as a SAML2 Provider in the Frame Console.

App Registration

If you chose to create an Azure Applicaton Registration instead of an Enterprise Application, you can follow the following procedure, instead of the Enterprise Application creation process discussed in the prior section.

1. First, go to your Azure portal. Search for “App Registrations” in the top search bar. Click on it in the results list.

2. At the top-left, click New registration.

3. Enter the following information into the corresponding fields:

   • Name: Enter Nutanix Frame for the application name
   • Supported account types: Select “Accounts in this organizational directory only”
   • Redirect URI (optional): Select “Web” from the drop-down menu. Paste the Redirect URI after filling out the Getting Started section from the very beginning of this page.

4. Click the Register button at the bottom of the section to proceed. This requires you to agree to Microsoft Platform Policies.

5. Your app information will appear immediately. Let's copy the Application ID and save it for later.

6. Next, click on the Endpoints button at the top of this section. Copy the Federation metadata document URL and save that, too.

7. Next, Click Branding and properties from the main menu on the left. Here, we'll fill out the Name, logo, and Homepage URL fields as detailed below. Feel free to leave the rest of the fields blank/default.

• Name: Enter "Dizzion Frame".
• Upload new logo: Download our logo and upload it.
• Home page URL: When users navigate to Frame from their Azure Portal, this URL is where they'll initially land. This URL could point to an Account/Launchpad, but if you have Admins signing in, it may direct them to the Frame Console for their customer/organization. For help deciding on a URL to use, see our Entitys and URLs section.

Wrapping up the Branding and properties form, double-check the name, logo, and Home page URL. If everything looks good, click Save at the bottom of the page.

1. Next, we're going to assign certain claims/assertions to be sent to Frame. This ensures we'll get email addresses in the correct format, and we can optionally pass Azure Group memberships as claims. Click on Token configuration from the side menu on the left. Click Add optional claim button, then select SAML. Check email in the Claim list and click Add at the bottom.

info

When adding the email claim, you'll see a confirmation dialog to turn on required permissions for OpenID Connect scopes. Leave this box checked and click "Add".

9. If you'd like to pass group claims to Frame for roles/permission assignment, click the Add groups claim button near the top of the page. If you don't need to pass Group memberships as claims/assertions, you can skip this step.

   

   Under Edit groups claim, select the groups type(s) you'd like to include in the assertions to Frame. In our screenshot, We selected “Security groups” and “Groups assigned to this application”. Later, we can match against these groups (via group IDs) for assigning roles and permissions from the Frame Console. Additional information regarding groups can be found in Microsoft's official documentation.

   For enterprise customers who have more than 150 security groups in their Azure AD tenant, you should only check "Groups assigned to this application", leaving all other checkboxes unchecked.

   Next, expand the SAML section and choose Group ID, then click Add. This will instruct Azure AD to reference each Azure AD group by its Group ID in the SAML2 assertion.

   note

   If a user is a member of Group B, and Group B is a member of Group A, then the group claims for the user will contain both Group A and Group B. When an organization's users have large numbers of group memberships, the number of groups listed in the token can grow the token size. Azure AD limits the number of groups that it will include in a token up to a maximum of 150 for SAML assertions and 200 for a JWT. If a user has more than 150 groups, the groups are omitted in the SAML assertion. A link to the Microsoft Graph endpoint to obtain group information is included instead. Further details are at Microsoft's Azure AD documentation.

10. Next, click on the “Authentication” tab on the left side-menu. Here, we're going to add an additional Reply URI that users can be end up visiting to log in. Click the “Add URI” button to create a new text field. Next, copy the first URL that's present and paste it into our new URI field. Next, change the text so that our new URI starts with https://img.frame.nutanix.com instead of https://img.console.nutanix.com. In other words, we're simply replacing the console.nutanix.com subdomain with frame.nutanix.com to support legacy Frame-related authentication flows. After that's done and you've confirmed the URIs are the same aside from the subdomain, click Save at the bottom to continue.

    

That wraps up the steps we need to perform from the Azure Portal for an App Registration. Next, we'll use the Application ID, Federation Metadata URL, and Integration Name to set up Azure AD as a SAML2 Provider in the Frame Console.

Create the SAML2 Authentication Integration Provider in Frame

1. Open up a new tab and navigate to your Frame account. A SAML2 authentication integration can be configured at any level (depending on administrative access) by navigating to the Admin page and clicking on the ellipsis listed next to the desired entity name. Select Users from the menu that appears.

   

2. Under Authentication, enable the SAML2 toggle and click Save in the upper right corner.

   

   More options will appear next to the Authentication tab, click on the SAML2 Providers tab.

3. Click Add SAML2 Provider.

   

4. A new window will appear prompting you to enter some of the information you obtained earlier.

   

   • Application ID: Paste the Application ID from step 5, prepended with the prefix spn: as pictured.
   • Auth provider metadata: Check the URL option and paste the Federation Metadata Document URL you copied in step 6 into this field.
   • Integration Name: Enter the SAML2 Integration name defined in the Getting Started section of this page.
   • Custom Label: When specified, this value will be used in the login page as Sign in with <Custom Label>. Enter “Azure AD” or customize it however you like.
   • Authentication token expiration: Set the desired expiration time for the authentication token. This can range from 5 minutes to 7 days.
   • Signed response: Leave this toggle disabled.
   • Signed assertion: Enable this toggle.

   After filling out the required fields, click Add. Next, it's time to set up permissions for our users based on their email address or passed group claims if you configured groups in your Azure AD App Registration.

Configuring SAML2 Permissions

Once the SAML2 Provider is successfully configured in the Nutanix Console, administrators will need to add authorization rules from the SAML2 Permissions tab listed to the right of the SAML2 Provider tab.

Add roles/permissions for your users by following our Roles and User Permissions with a SAML2 IdP guides.

Once you've configured permissions for your users, that's it! You're ready to test signing into Frame at your Entity URLs (Launchpad, Account Dashboard, etc.)!

Configuring SAML2 Group Permissions

1. Next, get the Object ID of the group or groups you would like to use for assigning user permissions. You can obtain this from the Groups console in Azure Active Directory. Find the group you would like to use, click on it, and copy the Object ID as shown below:

   

2. From here, navigate to the Users > SAML2 Permissions section of your Frame Console, either through the account Dashboard or by clicking on the ellipsis next to the entity you're configuring and selecting “Users.” Click Add Permission at the top-right.

   

3. Select your Azure AD integration from the drop-down menu under For provider. Next, choose how you'd like to allow access under the Allow access section. If you're doing some simple testing, “Always” is great. For more granular controls, you can apply roles when ALL or ANY conditions are matched. For simplicity, we chose Click When any condition is satisfied. Under the Conditions section, enter the URL to Microsoft's claims translation schema as the attribute type:

   http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

   You must use contains as the logical operator since group attributes are sent in a list. Keep the value type as Text, then paste the your Azure AD group's object ID in the text value field. It should look something like this:

   

4. Grant whichever role you would like the specified group to have. For us, we assigned a simple role of Launchpad User for one of our account Launchpads. Click “Save” once you've completed all the fields as described above. The next time someone tries to sign into Frame Console, they'll be assigned permissions as configured here if there's a match.

Accessing Frame with Azure AD

Your Azure AD integration will now appear to your users as a sign in button on the Frame Entity URL's sign in page. Reference the above Frame Entity URLs section to provide the right URLs to your users.

If the SAML2 Provider was configured for a Customer, Organization, or Account entity URLs, you should now see a new sign in button when viewing the entity's URL as shown below:

Troubleshooting

Azure AD caches the user's claims in the user's browser after the user has authenticated to Azure AD. If you are testing claims or assertion changes in Azure AD, be sure to log out of Azure AD and reauthenticate to Azure AD, even if you test in a private browser or in incognito mode.