Integrate with Microsoft Azure AD

Overview

Integrating Azure AD Single Sign On (SSO) is a quick and easy process. There are only four pieces of information we are going to copy and paste from one system to the other.

  • The Frame SAML2 Integration Name. This is a name you pick when you create the SAML authentication integration. The name should be something no one else has used across the platform. It should have only letters, numbers, and the dash symbol; no spaces or punctuation are allowed. It is also case-sensitive in that you will need to use this name exactly as it appears in later steps in this guide; upper and lower case matter. This is first defined in Step 4 and will be used in later steps as well.

Note

The SAML2 integration name you choose will be displayed on the SSO login button used by anyone attempting to log in to the platform.

  • The Azure AD Federation Metadata Document URL. This is a URL where Azure AD keeps the SAML Metadata for your Azure tenant.

  • The Application ID from your Azure AD application.

  • The Xi Frame URL that you will use as your sign-in page. These are formatted in the following manner:

    https://frame.nutanix.com/frame/[customer_URL]/[organization_URL]/[account_URL]/
    

    Where you intend to attach the SAML2 integration to your Frame environment determines if you need only the Customer URL, the Customer and Organization URL, or all three. You should make this decision before proceeding and get this URL ready. You’ll need it for later steps.

Following the steps below, you can find these values and copy them from Azure AD to Frame and from Frame to Azure AD. This process should take less than fifteen minutes.

Configure Azure AD

To connect Frame to Azure AD for Single Sign On (SSO) we will need to register an Azure Application and collect three pieces of information about that Azure Application.

  1. First, go to your Azure portal. Search for “Active Directory” in the top search bar. Click on the “Azure Active Directory” service.
../../_images/azuread1.png
  1. On the “Default Directory Overview” page, click “App registrations.”
../../_images/azuread2.png
  1. Click “New registration.”
../../_images/azuread3.png
  1. Enter the following information into the corresponding fields:

    ../../_images/azuread4.png
    • Name: Enter the application name. We will call this application Xi Frame.

    • Supported Account Type: Select “Accounts in this organizational directory only (Default).”

    • Redirect URI (Optional): Select “Web” from the drop-down menu. Enter your Redirect URI in the following format:

      https://img.frame.nutanix.com/saml2/done/[SAML_INTEGRATION_NAME]/
      

      See the image above for our example. Please use your own SAML2 integration name for your own SAML2 integration.

      Note

      The SAML2 integration name is the name that you pick for your SAML2 integration with Frame. It is defined for the first time in this step. While it is an arbitrary name, once it is defined it becomes important and permanent. It is case sensitive and will be used later in steps 9 and 12. It will also be displayed to your users when they’re logging in, so it should be simple and descriptive.

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

  1. Your app information will appear immediately. Copy the Application ID and save it. You will need to use this information later.
../../_images/azuread5.png
  1. Next, click on the “Endpoints” button at the top of this section. Copy the “Federation metadata document” URL and save it. You will need this information later.
../../_images/azuread6.png
  1. Click “Branding” listed under the “Manage” section in the menu on the left. Review the fields listed below. Leave any remaining fields at their default values.

    ../../_images/azuread6two.png
    • Name: This should be set to the name you provided above in step 4.
    • Upload new logo: You can use this image if desired.
    • Home page URL: Enter your Xi Frame account URL here. See the example above.

    Click the “Save” icon at the top of this panel when you have finished editing the required fields.

  2. Select “Authentication” listed under the “Manage” section in the menu on the left. You will see the redirect URI you entered earlier. Under the “Web” section enter the Logout URL in the following format:

    https://img.frame.nutanix.com/saml2/slo/[SAML_INTEGRATION_NAME]/
    

    Warning

    The forward slash at the end of the URL is required for the integration to work correctly.

    ../../_images/azuread7.png

    Click the “Save” icon at the top of this panel when you have finished editing the required fields.

  3. Click “Manifest” listed under the “Manage” section in the menu on the left. Editing the manifest XML is required, and any mistakes made here will cause SAML2 claims to be improperly formatted or missing important information. Please read the instructions carefully and verify that your manifest looks identical (except for documentation example names and URLs; replace those with your own) to the screenshots provided. The Azure Portal will not allow you to save the manifest.xml file if there are XML formatting errors.

../../_images/azuread8.png
  1. Navigate to the "optionalClaims": null, attribute in the manifest. In place of null, you will want to add the following JSON:
{
    "idToken": [],
    "accessToken": [],
    "saml2Token": [
        {
            "name": "email",
            "source": null,
            "essential": true,
            "additionalProperties": []
        }
    ]
},

It should look like this:

../../_images/manifest1.png
  1. Next, scroll down until you find the "replyUrlsWithType": attribute in the manifest.

    ../../_images/manifest2.png

    Under the object highlighted above, enter JSON in the following format. This uses a combination of your Xi Frame URL and your SAML2 Integration Name.

{
    "url": "https://img.frame.nutanix.com/login?return_url=https://frame.nutanix.com/frame/[customer_URL]/[organization_URL]/[account_URL]&account_type=[SAML_INTEGRATION_NAME]",
    "type": "Web"
}

When you have finished editing "replyUrlsWithType":, it should look like this:

../../_images/manifest3.png

Note

The manifest will not allow you to save if there are any JSON formatting issues.

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.
../../_images/generic_usersnav11.png
  1. Navigate to the “Authentication” tab and enable the “SAML2” toggle under “Authentication.” Click “Save” in the upper right corner.
../../_images/oktar_1b.png
  1. Once the setting is saved, the “SAML2 Providers” tab will appear. Navigate to this tab and then click “Add a SAML2 Provider.”
../../_images/oktar_1c.png
  1. A new window will appear prompting you to enter some of the information you obtained earlier.

    ../../_images/addazureAD.png
    • Application ID: Paste the Application ID from step 6.
    • Auth provider metadata: Check the “URL” option and paste the Federation Metadata Document URL you copied in step 12 into this field.
    • Name: Enter the SAML2 Integration name, first defined in Step 4, here. The name should have only letters, numbers, and the dash symbol; no spaces or punctuation are allowed. It is also case-sensitive. As mentioned above, we will use the SAML2 integration name docs-auth-azureAD for this example. Please do not use this name for your own integration.
    • 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.
  2. Click “Add.”

Configure SAML2 Permissions

Once the IdP is successfully configured, administrators will need to configure the authorization rules for the account from the “SAML2 Permissions” tab listed to the right of the current tab. Read more about user roles and permissions on our “User Permissions” section.

../../_images/saml2permissions.png

Configure Group Attributes on Azure AD

Azure AD handles SAML2 a bit differently than other identity providers. Group assertions are sent as a “Group ID,” which is a long string of characters separated by hyphens. As of right now, legible names are not in the SAML assertion that Azure AD sends. Additional information regarding groups can be found in Microsoft’s official documentation. This section is optional, you can move on to the next section if you would prefer not to set up groups through Azure AD.

  1. First, navigate to the “Manifest” section for the Frame SAML2 integration in your Azure AD portal.
../../_images/azuread_groups1.png
  1. Edit the line groupMembershipClaims – change it from “null” to “All.”

Note

If you have more than 150 groups assigned to your users, editing the line above will not work properly. You will need to use either a SecurityGroup, DistributionList, or DirectoryRole instead of “All.”

  1. Find the "optionalClaims" section and add the following lines underneath the "saml2Token" parameter.
{
"name": "groups",
"source": null,
"essential": false,
"additionalProperties": []
}

It should look like this once edited:

../../_images/azuread_groups2.png
  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:
../../_images/azuread_groups3.png
  1. From here, navigate to the Users > SAML2 Permissions section of your Xi Frame console, either through the account Dashboard or by clicking on the ellipsis next entity you’re configuring and selecting “Users.” Click “Add Permission.”
../../_images/azuread_groups4.png
  1. Select your Azure AD integration from the drop-down menu under “For provider.” Click “When any condition is satisfied” under the “Allow access” section. 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. Paste the Object ID of the group as the textual value. It should look something like this:

../../_images/azuread_groups5.png
  1. Grant whichever role you would like the specified group to have. Click “Save” once you’ve completed all the fields as described above.

Using Azure AD as a SAML2 Authentication Integration

Your new SAML2 auth integration will appear as button on your Xi Frame login page. The URL for navigating to your Xi Frame login page will vary depending on which level the SAML2 integration was configured.

Customer level:

https://frame.nutanix.com/frame/[customer_URL]/

Organizational level:

https://frame.nutanix.com/frame/[customer_URL]/[organization_URL]/

Account level:

https://frame.nutanix.com/frame/[customer_URL]/[organization_URL]/[account_URL]/
../../_images/finalazureAD.png