WorkOS Docs Homepage
Integrations
DashboardSign In

Microsoft AD FS SAML

Configure a connection to Microsoft Active Directory Federation Services.

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 two pieces of information: an SP Metadata file and an IDP Metadata URL.

Open the AD FS Management console.

A screenshot showing the AD FS Management Console.

Click “Relying Party Trusts” on the left sidebar. Click “Add Relying Party Trust...” on the right sidebar to open the “AD FS Relying Party Trust Wizard”.

A screenshot showing where to add the AD FS Relying Party Trust.

Select “Claims aware” and then “Start”.

A screenshot showing where to select claims in the AD FS Relying Party Trust Wizard.

Download the provided Metadata file from WorkOS by heading to the SP Metadata link in the Dashboard. Select “Import data about the relying party from a file” then select the SP Metadata file you downloaded, and click “Next”.

A screenshot showing where to import the WorkOS Metadata File.

Select “Permit everyone” and then “Next”.

A screenshot showing where to configure access control permissions in the AD FS Relying Party Trust Wizard.

Click the “Endpoints” tab and confirm that the “SAML Assertion Consumer Endpoints” matches the SAML Assertion Consumer Endpoint https://auth.workos.com/sso/saml/acs/:id and click “Next”.

A screenshot showing where to check the ACS URL in AD FS.

Select “Configure claims issuance policy for this application” and “Close”.

A screenshot showing where to configure the AD FS claims.

Click “Add Rule” in the “Edit Claims Issuance Policy” window.

A screenshot showing where to add a rule in the Edit Claims Issuance Policy window.

Select “Send LDAP Attributes as Claims” and then “Next”.

A screenshot showing where to select a rule template in the Transform Claim Rule Wizard.

Submit “Attributes” as “Claim rule name”, then select “Active Directory” as “Attribute Store”, and configure the following attribute mappings. Then click “OK”.

  • E-Mail-AddressesE-Mail Address
  • Given-NameGiven Name
  • SurnameSurname
  • User-Principal-NameUPN
A screenshot showing where to map attributes in the Transform Claim Rule Wizard.

Users can automatically be assigned roles within your application by sending their group memberships. To enable this, set up a group attribute statement following the guidance below.

This feature is currently in beta, contact customer support for more information.

Select "Group" as the "Outgoing Claim Type" and map an LDAP Attribute to send groups. For example, to send all groups, map the "Token-Groups - Unqualified Names" attribute.

A screenshot showing how to map the Group claim.

Next you will want to obtain the Metadata URL from your AD FS server. AD FS publishes its metadata to a standard URL by default: https://SERVER/federationmetadata/2007-06/federationmetadata.xml where “SERVER” is your federation service FQDN. You can also find your ADFS Federation Metadata URL through the AD FS Management in “AD FS → Service → Endpoints” and navigate to the Metadata section.

A screenshot showing where to find the AD FS Metadata URL.

Once you have obtained the Metadata URL you will then navigate to the connection settings in WorkOS, click “Edit Metadata configuration”, and upload the Metadata URL.

A screenshot showing where to upload the AD FS Metadata URL in the WorkOS Dashboard.

Once uploaded the connection will be verified and linked!