Skip to Content

Configuring Active Directory Federation Services using SAML single sign on

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

Actor Role
Vinyl Service Provider (SP)
AD FS Identity Provider (IdP) / Security Token Service (STS)
User Browser

Configuration involves the following procedures:

  1. Create a Vinyl security provider for AD FS
  2. Create an AD FS Relying Party Trust for Vinyl


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:

Example Notes
Vinyl URL Vinyl must be accessible via HTTPS. The URL must include the trailing slash. The path is case-sensitive.
Provider Name ADFS Each Vinyl security provider is given a logical name. Since the provider name will appear in the Assertion Consumer Service URL (see below), avoid spaces, punctuation and special characters.
Assertion Consumer Service URL Vinyl automatically provisions an Assertion Consumer Service (ACS) endpoint for SAML Single Sign-On (SSO) security providers. AD FS refers to the ACS URL as the "Relying party SAML 2.0 SSO service URL". Note that the Provider Name appears in the URL.
Audience URI Although the audience URI is arbitrary, AD FS and Vinyl must use the same value. Consider using the Vinyl URL.
Federation Metadata Document URL The Federation Metadata Document URL can be retrieved from AD FS. To do so, launch the AD FS Management console. Select AD FS → Service → Endpoints. Locate the endpoint of Type Federation Metadata.

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: 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).\


  8. Click the Save icon (Check)

  9. In the Properties panel, click + Property
  10. Provide the following:

    • Parameter: Audience
    • Value: Audience URI (see above).


  11. 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 Claim panel, click + Claim
  2. Provide the following:

    • Identifier: Claim type name.


    • 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 a AD FS relying party trust, see the following TechNet article:

Creating a relying party trust requires the following information:

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


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


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

Commonly mapped claims include:

  • Email Address -
  • Group Membership -

See Claims for additional information regarding claims.


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

> Get-ADFSRelyingPartyTrust -Identifier

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 "Vinyl"):

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

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.