Configuring Active Directory Federation Services Using WS-Federation¶

Vinyl can integrate with Active Directory Federation Services (AD FS) using the WS-Federation Passive protocol. The WS-Federation Passive protocol defines the following operational roles:

Configuration involves the following procedures:

1. Create a Vinyl Security Provider for AD FS
2. Create an AD FS Relying Party Trust for Vinyl

Requirements¶

In order to proceed, you will need the following:

• Administrator access to AD FS.
• Administrator access to Vinyl.
• Vinyl 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: Vinyl will not be able to retrieve the metadata document if the certificate is untrusted or otherwise invalid.
• Vinyl will need to be available via HTTPS. The Require HTTPS security provider should be enabled (or other measures taken to ensure that Vinyl 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 a Vinyl Security Provider for AD FS¶

To create the Security Provider, start by signing into Vinyl 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: ExampleADFS

   • Type: WS-Federation

   • 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 the + Property button

7. Provide the following:

   • Parameter: MetadataAddress

   • 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 the + Property button

10. Provide the following:

    • Parameter: Wtrealm

    • Value: Wtrealm (see above).

      Example: https://example.com/Vinyl/signin-ExampleADFS

11. Click the Save icon (Check)

12. In the Properties panel, click the + Property button

13. Provide the following:

    • Parameter: Audience

    • Value: Audience (see above).

      Example: https://example.com/Vinyl/signin-ExampleADFS

14. Click the Save icon (Check)

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

1. In the Claims panel, click the + Claim button

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 Vinyl¶

Each instance of Vinyl 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 an 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:

• Protocol: WS-Federation Passive

• Relying party WS-Federation Passive protocol URL: Corresponds to the Passive Protocol URL (see above).\

  Example: https://example.com/Vinyl/signin-ExampleADFS

• Relying party trust identifier: Corresponds to the Wtrealm property (see above).\

  Example: https://example.com/Vinyl/signin-ExampleADFS

Create an AD FS Endpoint URL for Vinyl¶

Each instance of Vinyl must be registered within AD FS as an endpoint. Create an endpoint on the Endpoints tab in AD FS as follows:

1. Click Add WS-Federation button.
2. Set the endpoint as the default (checkbox).

3. Trusted URL: Corresponds to the Wtrealm property (see above).

   Example: https://example.com/Vinyl/signin-ExampleADFS

Claim Mappings (Optional)¶

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¶

Configuration Settings¶

"Runtime Error" when clicking the "Sign in with..." link¶

The URL may read: http://example.com/Vinyl/service/authentication/external?returnUrl=...

Review the Windows Event Log. Specifically, check the Application log for ASP.Net warnings with an event ID of 1309. You may find an entry with following exception message:

Unable to get document from: https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml

This indicates that Vinyl was unable to retrieve the Federation Metadata Document. Ensure that the Vinyl web server is able to make an HTTPS connection to the AD FS Metadata Document endpoint. Also ensure that the TLS certificate is valid. If the certificate is not signed by a trusted root, you may manually register it.

"Runtime Error" after signing into AD FS¶

The URL may read: http://example.com/Vinyl/signin-ADFS

Review the Windows Event Log. Specifically, check the Application log for ASP.Net warnings with an event ID of 1309. You may find an entry with one of the following exception messages.

Missing Claim¶

The identity does not contain a claim matching the given type.

This indicates that the SAML assertion is missing one or more required claims. Review the claim rule configuration.

Invalid Audience¶

IDX10214: Audience validation failed. Audiences: 'https://example.com/Vinyl'. Did not match:  validationParameters.ValidAudience: 'https://example.com/Vinyl/' or validationParameters.ValidAudiences: 'null'

This indicates that the SAML assertion has an invalid audience restriction. In this particular example, the audience is missing the trailing slash. Make sure the relying party trust identifier is correct.

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/Vinyl/signin-ADFS`

The Identifier argument corresponds to the Passive Protocol 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 "Vinyl"):

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

Missing or incorrect Claims configuration¶

The following error message may be seen after authenticating:

The user account (`<username>`) has successfully signed in, but no available landing page has been configured for their applications.

This indicates successful configuration of the security provider and the AD FS end, but means that claims have not yet been configured or need correcting.

Review claims passed back to Vinyl from ADFS (ensure Store Claims is checked) to make sure that the correct claims are being passed (group memberships, custom attributes) to Vinyl and these can then be mapped in the Security Provider Claims configuration.