Configuring Active Directory Federation Services using SAML single sign on¶

App Builder can integrate with Active Directory Federation Services (AD FS) using the SAML Single Sign-On (SSO) protocol. The SAML SSO protocol defines the following operational roles:

Configuration involves the following procedures:

1. Create an App Builder security provider for AD FS
2. Create an AD FS Relying Party Trust for App Builder

Requirements¶

To proceed, you will need the following:

• Administrator access to AD FS.
• Administrator access to App Builder.
• App Builder will need to connect to AD FS via HTTPS to retrieve the metadata document. AD FS must use a TLS certificate with a trusted root: App Builder will not be able to retrieve the metadata document if the certificate is untrusted or otherwise invalid.
• App Builder will need to be available via HTTPS. The Require HTTPS security provider should be enabled (or other measures taken to ensure that App Builder is only accessible via HTTPS).
• Client machines will need to be configured to trust AD FS. Otherwise, AD FS will prompt the user to sign in.

The instructions below will refer to the following properties:

Create an App Builder security provider for AD FS¶

To create the security provider, start by signing into App Builder as an administrator:

1. Navigate to the IDE
2. Select the Security Providers button
3. In the User Authentication panel, click the + User Authentication button

4. Provide the following:

   • Name: Security Provider Name (see above) Example: ADFS
   • Type: SAML
   • Enabled: Check
   • User Provisioning: Check to enable Just-in-Time (JIT) user provisioning
   • Supplies Group Membership: Check if AD FS has been configured to pass user group membership
   • Show On Login Form: Check

5. Click the Save button

6. In the Properties panel, click + Property

7. Provide the following:

   • Parameter: MetadataEndpoint

   • Value: Federation Metadata Document URL (see above).\

     Example: https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

8. Click the Save icon (Check)

9. In the Properties panel, click + Property

10. Provide the following:

    • Parameter: Audience

    • Value: Audience URI (see above).

      Example: https://example.com/App Builder/

11. Click the Save icon (Check)

In addition, any claims mapped in AD FS will need to be mapped in App Builder. For example, to map the email claim:

1. In the Claim panel, click + Claim

2. Provide the following:

   • Identifier: Claim type name.

     Example: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

   • Usage: Claim type usage.

     Example: Email Address

3. Click the Save icon (Check)

Create an AD FS relying party trust for App Builder¶

Each instance of App Builder must be registered within AD FS as a relying party trust. The full details of creating, configuring and maintaining relying party trusts falls outside the scope of this document. For additional information describing how to create a AD FS relying party trust, see the following TechNet article:

https://technet.microsoft.com/en-ca/library/dd807108.aspx

Creating a relying party trust requires the following information:

• Relying party SAML 2.0 SSO service URL: Corresponds to the Assertion Consumer Service URL.

  Example: https://example.com/App Builder/signin-ADFS

• Relying party trust identifier: Corresponds to the Audience URI property.

  Example: https://example.com/App Builder/

You may also supply optional claim mappings. The following TechNet article describes how to create AD FS relying party trust claim rules:

https://technet.microsoft.com/en-us/library/dd807115.aspx

Commonly mapped claims include:

• Email Address - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
• Group Membership - http://schemas.xmlsoap.org/claims/Group

See Claims for additional information regarding claims.

Troubleshooting¶

Print AD FS relying party trust settings¶

Execute the following PowerShell command from the AD FS server to print the relying party trust settings:

> Get-ADFSRelyingPartyTrust -Identifier https://example.com/App Builder/signin-ADFS

The Identifier argument corresponds to the Assertion Consumer Service URL (as described above).

Missing group membership¶

By default, ADFS does not include group claims in SAML assertions. Administrators must create one or more claim rules to include group membership. It is possible to create a single claim rule that includes all group membership. However, using the built-in ADFS "Group Claim" rule, a separate rule is required for each group.

The following article describes how to include group membership matching a regular expression (e.g. groups starting with "App Builder"):

http://social.technet.microsoft.com/wiki/contents/articles/8008.ad-fs-2-0-selectively-send-group-membership-s-as-a-claim.aspx

The following article describes how to use regular expressions in claim transformation rules:

http://social.technet.microsoft.com/wiki/contents/articles/16161.ad-fs-2-0-using-regex-in-the-claims-rule-language.aspx

Error "The AudienceRestrictionCondition was not valid because the specified Audience is not present in AudienceUris."¶

This error indicates that the audience URI does not match. Ensure that the Audience property has been explicitly set. If not set, it will default to the current URL, which may vary by user. The value is case-sensitive.