Skip to Content

Configuring Active Directory Federation Services using WS-Federation in Jitterbit App Builder

App Builder 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:

Actor Role
App Builder Relying party
AD FS Identity Provider (IdP) / Security Token Service (STS)
User Passive requestor

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:

Example Notes
App Builder URL https://example.com/App Builder/ App Builder must be accessible via HTTPS. The URL must include the trailing slash. The path is case-sensitive.
Provider Name ExampleADFS Each App Builder security provider is given a logical name. Since the provider name will appear in the Passive Protocol URL (see below), avoid spaces, punctuation and special characters.
Passive Protocol URL https://example.com/App Builder/signin-ExampleADFS App Builder automatically provisions a Passive Protocol endpoint for WS-Federation security providers. Note that the Provider Name appears in the URL.
Federation Metadata Document URL https://fs.example.com/FederationMetadata/2007-06/FederationMetadata.xml 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.
Audience https://example.com/App Builder/signin-ExampleADFS An Audience value is highly recommended to limit the scope of authentication. Consider using the Passive Protocol URL.
Wtrealm https://example.com/App Builder/signin-ExampleADFS Although the Wtrealm is arbitrary, AD FS and App Builder must use the same value. Consider using the Passive Protocol URL.

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: 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/App Builder/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/App Builder/signin-ExampleADFS

  14. 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 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 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 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/App Builder/signin-ExampleADFS

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

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

Create an AD FS endpoint URL for App Builder

Each instance of App Builder 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/App Builder/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

Note

Your configuration settings may vary from examples provided in this article, depending on your exact environment. For example, depending on how your App Pool is configured, you may be using demo.zudy.com/signin-AD or demo.zudy.com/vinyl/signin-AD.

The URL may read: http://example.com/App Builder/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 App Builder was unable to retrieve the Federation Metadata Document. Ensure that the App Builder 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/App Builder/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/App Builder'. Did not match:  validationParameters.ValidAudience: 'https://example.com/App Builder/' 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.

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 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 "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

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 App Builder from ADFS (ensure Store Claims is checked) to make sure that the correct claims are being passed (group memberships, custom attributes) to App Builder and these can then be mapped in the Security Provider Claims configuration.