Integrating Azure AD Single Sign On (SSO) is a quick and easy process. Before we get started, take note of four 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 Nutanix 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 a URL where Azure AD keeps the SAML Metadata for your Azure application.
- The Application ID from your Azure application.
- The Redirect URI. This is the destination URL for all of your assertions/claims after users authenticate through Azure AD.
- The Nutanix 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. Here's an example Frame Launchpad URL format:
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.
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
First, we'll start by registering a new Azure Application. This will provide us with a few data points mentioned earlier that we'll use in later steps.
First, go to your Azure portal. Search for “App Registrations” in the top search bar. Click on it in the results list.
At the top-left, click New registration.
Enter the following information into the corresponding fields:
- Name: Enter
Nutanix Framefor 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.
- Name: Enter
Click the Register button at the bottom of the section to proceed. This requires you to agree to Microsoft Platform Policies.
Your app information will appear immediately. Let's copy the Application ID and save it for later.
Next, click on the Endpoints button at the top of this section. Copy the Federation metadata document URL and save that, too.
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 "Nutanix Frame".
- Upload new logo: Download our logo and upload it.
- Home page URL: When users navigate to Nutanix 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 Nutanix 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.
Next, we're going to assign certain claims/assertions to be sent to Nutanix. 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
Wen 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".
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 Nutanix Console. Additional information regarding groups can be found in Microsoft's official documentation.
Next, expand the SAML section and choose Group ID, then click Add.
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.console.nutanix.com. In other words, we're simply replacing the console subdomain with frame to support legacy Frame-related auth-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. Next, we'll use the Application ID, Federation Metadata URL, and Integration Name to set up Azure AD as a SAML2 Provider in the Nutanix Console.
Create the SAML2 Authentication Integration Provider in Frame
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.
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.
Click Add SAML2 Provider.
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
- 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. If you wish to use Signed SAML2 Responses, please contact Frame Support or your Account Manager for further instructions.
- 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 step 9.
- Application ID: Paste the Application ID from step 5, prepended with the prefix
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
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:
From here, navigate to the Users > SAML2 Permissions section of your Nutanix 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.
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:
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:
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/Nutanix 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 Nutanix Entity URL's sign in page. Reference the above Nutanix 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: