Single Sign-On

Connect AD FS

Learn how to configure a connection to Microsoft Active Directory Federation Services (AD FS)

Each SSO Identity Provider requires specific information to create and configure a new Connection. Often, the information required to create a Connection will differ by Identity Provider.

To create an AD FS SAML Connection, you'll need four pieces of information: an ACS URL, an Identity Provider Issuer (also known as an Entity ID), an Identity Provider SSO URL, and an X.509 Certificate.

WorkOS provides:

  • ACS URL

You provide:

  • Identity Provider SSO URL
  • Relying Party Trust ID
  • Relying Party Trust Certificate
  • X.509 Certificate

WorkOS Provides:

WorkOS provides the ACS URL for AD FS Connections. This is readily available in your Connection's Settings in the Developer Dashboard.

You Provide:

And then, you provide the Identity Provider SSO URL, as well as the Relying Party Trust ID, Relying Party Trust Certificate, and the X.509 Certificate.

The Identity Provider SSO URL is your application's login endpoint. When your customer's users follow this URL, we redirect them to the appropriate AD FS instance for authentication and sign in.

For AD FS SAML, the Identity Provider SSO URL usually takes the standard form:

https://adfs.example.com/adfs/ls

Next comes the Relying Party Trust ID. This will be your applications domain.

The Relying Party Trust ID communicates to the AD FS instance where it can expect valid SAML claims to come from. The instance will trust this listed relying party so that when a user is authenticated, they can be redirected back to that trusted application.

And then comes the Relying Party Trust and X.509 Certificates. You'll generate these in Step 1 below.

Step 1. Generate Certificates

Begin by creating a local directory to store your keys and certificates. Then, clone and run mellon_create_metadata.sh:

  1. touch mellon_create_metadata.sh && vi mellon_create_metadata.sh

  2. chmod +x mellon_create_metadata.sh

  3. ./mellon_create_metadata.sh example.com https://example.com/auth/adfs/

Note: replace example.com in the commands above with your application's authorization domain.

You'll receive output similar to:

Step 2. Configure AD FS

  1. Navigate to the AD FS Management Console.

  2. Select "Add Relying Party Trust" to launch the "Add Relying Party Trust Wizard."

  3. During the "Select Data Source" step, select "Import data about the relying party trust from a file" and then select the .xml metadata file generated earlier. Select "Open" and then "Next"

  4. Specify a Display Name for your application's Relying Party and click "Next."

  5. Confirm "Permit Everyone" is selected for your Access Control Policy, and click "Next".

  6. Confirm the URLs in the "Endpoints" tab match those in the certificate generation output from above.

  7. Check the "Configure claims issuance policy for this application" and then click "Close."

  8. You'll see an empty list of Claim Issuange Policy Rules. Click "Add Rule".

  9. Select "Send LDAP Attributes as Claims" as a Claim rule template and click "Next".

  10. Enter "Attributes" for the Claim rule name. Select "Active Directory" as the Attribute store. Finally, map the claim types as they appear in the example above. Then, this Enterprise's AD FS instance is configured to begin authorizing users for your application via SSO!

Step 3. Upload Certificates

Finally, upload the Certificate in your WorkOS Connection Settings. Your Connection will then be verified and good to go!

Next Steps

Check out a demo of how quick and easy it is to integrate AD FS SSO into your application after configuring your Connection!