Integrate with Microsoft ADFS¶
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.
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.
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¶
- Start the authentication setup by navigating to your Dashboard and clicking on the “Users” page. From the “Authentication” panel, enable the “SAML2” toggle. Click “Save” in the upper right corner.
A SAML2 authentication integration can also be configured at the customer or organizational level. Navigate to the admin page by clicking on the profile icon and selecting “Go to Admin.” From the “Organizations” or “Accounts” page listed on the left, click on the organization/customer you wish to configure. Select the “Security” tab and enable the “SAML2” toggle. Click “Save” in the upper right corner. Continue following the steps listed below.
- Once the setting is saved, the “SAML2 Providers” tab will appear. Navigate to this tab and then click “Add Provider.”
- The “Add SAML Identity Provider” dialog will appear.
Application ID: The Application ID identifies a partner across federation interactions and can be set to any DNS-compliant string.
Auth provider metadata: Typically, all Microsoft ADFS metadata URLs will be in the following format:https://[your-ADFS-domain]/FederationMetadata/2007-06/FederationMetadata.xml
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.
Name: Enter your unique SAML Integration name here. The name should have only letters, numbers, and the dash symbol; no spaces or punctuation are allowed. It is also case-sensitive. We’ll use the SAML integration name
docs-auth-adfsfor 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.
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.
- First, navigate to your AD FS Management Console. We will start by adding a new Relying Party Trust.
6. Let’s walk through the “Add Relying Party Trust Wizard.” On the “Welcome” screen, select “Claims aware”, then click “Start.”
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.
Occasionally ADFS will not be able to directly use the metadata URL for its configuration. In this case, you can download the XML file in from the Frame metadata URL and manually upload it when creating the relying party in ADFS.
- Ensure there are no errors, and then click “Next.”
- Enter a display name on the next screen and click “Next.”
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.”
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.
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.
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.
- On the “Choose Rule Type” screen, select “Send LDAP Attributes as Claims,” then click “Next.”
- 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.
|LDAP Attribute||Outgoing Claim Type|
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.
Select Transform an Incoming Claim for this Claim rule template.
On the Configure Claim Rule screen, enter a Claim rule name and enter the following info.
|Incoming claim type|
|Outgoing claim type||Name ID|
|Outgoing name ID format||Persistent Identifier|
Select Pass through all claim values, then click Finish.
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.
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
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|
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 current tab. Read more about user roles and permissions on our “Roles” section under “Manage User Permissions.”
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.