Integrate with Microsoft ADFS

Overview

Integrating Microsoft Active Directory Federation Services (ADFS) is straightforward. In addition to configuring your Super Admin account on Frame, you will need your organization’s assistance in adding Relying Party Trust information to your ADFS configurations.

There are a few pieces of information we are going to cut and paste between Frame and ADFS.

  • 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.

    Note

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

  • The ADFS Federation Metadata Document URL. This is a URL where ADFS keeps the SAML Metadata for your account.

Following the steps below, you can find these values and copy them from ADFS to Frame and from Frame to ADFS. You should read this guide all the way through before you begin so that you will be able to gather the necessary info for each step beforehand. Once you have the required info, this integration should take less than fifteen minutes. The screenshots below will help guide you.

Preparation

For these steps you will need to determine the authentication name that you will use for this configuration. 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.

Create the SAML2 Authentication Integration Provider in Frame

  1. From the Admin view, navigate to the desired entity where you wish to set up your ADFS integration. Click on the ellipsis listed next to the entity name and select “Users.”

../../_images/generic_usersnav11.png
  1. Navigate to the “Authentication” tab. Enable the “SAML2” toggle and click “Save” in the upper right corner.

../../_images/oktar_1b.png
  1. The “SAML2 Providers” tab will appear. Navigate to this tab and then click “Add SAML2 Provider.”

../../_images/oktar_1c.png
  1. The “Add a SAML2 identity provider” dialog will appear. Once you have entered all information as described below, click “Add.”

../../_images/adfs1.png
  • Application ID: The Application ID identifies a partner across federation interactions and can be set to any DNS-compliant string such as urn:companyframe:adfs.

  • Auth provider metadata: Typically, all Microsoft ADFS metadata URLs will be in the following format:

    https://[your-ADFS-domain]/FederationMetadata/2007-06/FederationMetadata.xml
    

    Note

    If you would like to verify your metadata URL, navigate back to the ADFS management console and open the “Service” folder. Click “Endpoints.” On the “Endpoints” page, scroll down to the “Metadata” section. Find the URL with the “Federation Metadata” type listed next to it.

  • Integration Name: Enter your unique SAML Integration name here. The name is unique across Frame Platform and should have only letters, numbers, and the dash symbol; no spaces or punctuation are allowed. It is also case-sensitive and will be embedded in URLs. We’ll use the SAML integration name docs-auth-adfs for the rest of the instructions. Please do not use this name for your own integration.

  • 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.

  • 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.

Add Relying Party and Trusts to ADFS

Next you must perform some setup tasks in your Microsoft ADFS environment to integrate with your new Custom Authentication setup on Frame. The instructions below were created from a Microsoft Windows Server 2016 running ADFS, but should also work well for a Windows Server 2012 R2 infrastructure. You will need to ensure that your ADFS infrastructure is using a valid SSL certificate that can be verified.

  1. First, navigate to your AD FS Management Console. We will start by adding a new Relying Party Trust.

../../_images/image38.png

6. Let’s walk through the “Add Relying Party Trust Wizard.” On the “Welcome” screen, select “Claims aware”, then click “Start.”

../../_images/image32.png

7. Select “Import data about the relying party published online or on a local network.” Enter the SAML2 Integration Name you created above in the format shown below. Remember that this URL is case sensitive.

https://img.frame.nutanix.com/saml2/metadata/[SAML2_INTEGRATION_NAME]/

For example:

../../_images/adfs3.png

Note

If ADFS has no access to the Internet or the specific ADFS deployment does not support TLS 1.2, ADFS will not be able to directly use the Frame metadata URL for its configuration. In this case, you will need to download the XML file in from the Frame metadata URL and manually upload the metadata XML file when creating the relying party in ADFS.

  1. Ensure there are no errors, and then click “Next.”

  2. Enter a display name on the next screen and click “Next.”

../../_images/adfs4.png

10. Now choose which Access Control Policy is appropriate for your organization. For example, to ensure that Frame works for all users in your organization, regardless of their location on your network or the Internet, you should choose “Permit everyone.” Click “Next.”

Note

Xi Frame recommends starting with “Permit Everyone” and testing authentication with your new SAML2 authentication integration. If your configuration works successfully, you can move on to a more restrictive Access Control Policy.

../../_images/image33.png

11. Now review the details in the various tabs of the summary portion of the wizard titled “Ready to Add Trust”. Click “Next”, when ready to finalize your Relying Party Trust configuration.

../../_images/adfs5.png

12. The “Finish” screen should confirm that you have added the Relying Party Trust successfully. Leave the checkbox checked for “Configure claims issuance policy for this application,” so that we can easily proceed to the next steps.

Edit Claim Issuance Policy

13. The Edit Claims window will appear. If you don’t see it, it may be hidden behind other windows on your screen. Click “Add Rule…” toward the bottom of the window.

../../_images/image41.png
  1. On the “Choose Rule Type” screen, select “Send LDAP Attributes as Claims,” then click “Next.”

../../_images/image42.png
  1. Name your “Claim rule name” and then select “Active Directory” from the drop-down menu listed under “Attribute Store.” Add three LDAP attributes to outgoing claim types as shown below. Click “Finish” once completed.

../../_images/image40.png

LDAP Attribute

Outgoing Claim Type

User-Principal-Name

mail

Surname

sn

Given-Name

givenName

16. You’ll see your new Rule added to the Issuance Transform Rules screen. We’re going to add one more Rule, so click Add Rule again.

image14

Select Transform an Incoming Claim for this Claim rule template.

image15

On the Configure Claim Rule screen, enter a Claim rule name and enter the following info.

Incoming claim type

mail

Outgoing claim type

Name ID

Outgoing name ID format

Persistent Identifier

Select Pass through all claim values, then click Finish.

image16

You’ll see both of your Rules listed. Optionally, you can choose to send group membership as part of the claim. To do this, continue to the next step, otherwise, click OK to complete your ADFS configuration and continue to the Configure Authorization Rules section.

image17

To send group membership as a claim, click Add Rule again.

Configure Group Claims

Select Send Group Membership as a Claim for this Claim rule template

adfs_10

On the Configure Claim Rule screen, enter a Claim rule name and enter the following info, then click Finish when done.

User’s group

Browse to and select the desired Active Directory group

Outgoing claim type

Group

Outgoing claim value

Value of your choice to send when a user is a member of the selected group

adfs_11

Configure SAML2 Permissions

Once the IdP is successfully configured on Frame, administrators will need to configure the authorization rules for the account from the “SAML2 Permissions” tab listed to the right of the SAML2 Provider tab. To learn more about Frame user roles and how to configure SAML2 permissions, go to “Roles” and “Specifying Permissions for SAML2 Users” sections, respectively, under “Manage User Permissions.”

../../_images/saml2permissions.png

Note

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.

Using Microsoft ADFS 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/[customer_URL]/

Organizational level:

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

Account level:

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