Docs

Refresh Tokens

Versioncurrent

Connect Your Application to ADFS

To connect your application to Microsoft's Active Directory Federation Services (ADFS), you will need to provide the following information to your ADFS administrator:

  • Realm Identifier: urn:auth0:YOUR_TENANT
  • Endpoint: https://YOUR_DOMAIN/login/callback or https://<YOUR CUSTOM DOMAIN>/login/callback, if you are using a custom domain.

Federated Metadata

The Federation Metadata file contains information about the ADFS server's certificates. If the Federation Metadata endpoint (/FederationMetadata/2007-06/FederationMetadata.xml) is enabled in ADFS, Auth0 can periodically (once a day) look for changes in the configuration, like a new signing certificate added to prepare for a rollover. Because of this, enabling the Federation Metadata endpoint is preferred to providing a standalone metadata file. If you provide a standalone metadata file, we will notify you via email when the certificates are close to their expiration date.

You can use a script to to setup the connection or set it up manually.

Overview

Scripted setup

Run the following two commands in the Windows PowerShell window.

You must run this script as an administrator of your system.

For automated integration, this script uses the ADFS PowerShell SnapIn to create and configure a Relying Party that will issue, for the authenticated user, the following claims: email, upn, given name and surname.

If you are using the custom domains feature, you will need to replace the $webAppEndpoint value with https://<YOUR CUSTOM DOMAIN>/login/callback.

The script creates the Relying Party Trust on ADFS, as follows:

The script also creates rules to output the most common attributes, such as email, UPN, given name, or surname:

Restrictions on Refresh Token Usage

Manual setup

  1. Open the ADFS Management Console.

  2. Click Add Relying Party Trust.

  3. Click Start.

  4. Select Enter data about the relying party manually and click Next.

  5. Enter a name (such as YOUR_APP_NAME) and click Next.

  6. Use the default (ADFS 2.0 profile) and click Next.

  7. Use the default (no encryption certificate) and click Next.

  8. Check Enable support for the WS-Federation... and enter the following value in the textbox:

    https://YOUR_DOMAIN/login/callback or if you are using a custom domain, use https://<YOUR CUSTOM DOMAIN>/login/callback

  9. Click Next.

  10. Add a Relying Party Trust identifier with the following value:

    urn:auth0:YOUR_TENANT

  11. Click Add and then Next.

  12. Leave the default Permit all users... and click Next.

  13. Click Next and then Close.

  14. In the Claim Rules window, click Add Rule....

  15. Leave the default Send LDAP Attributes as Claims.

  16. Give the rule a name that describes what it does.

  17. Select the following mappings under Mapping of LDAP attributes to outgoing claim types and click Finish.

    LDAP Attribute Outgoing Claim Type
    E-Mail-Addresses E-Mail Address
    Display-Name Name
    User-Principal-Name Name ID
    Given-Name Given Name
    Surname Surname

Get a Refresh Token

Add additional LDAP attributes

The mappings in the previous steps are the most commonly used, but if you need additional LDAP attributes with information about the user, you can add more claim mappings.

  1. If you closed the window on the previous step, select Edit Claim Rules on the context menu for the Relying Party Trust you created, and edit the rule.

  2. Create an additional row for every LDAP attribute you need, choosing the attribute name in the left column and desired claim type in the right column.

  3. If the claim type you are looking for doesn't exist, you have two options:

    • Type a namespace-qualified name for the new claim (for example http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department).
    • Register a new claim type (under ADFS > Services > Claim Descriptions) on the ADFS admin console), and use the claim name in the mapping.

    Auth0 uses the name part of the claim type (for example department in http://schemas.xmlsoap.org/ws/2005/05/identity/claims/department) as the attribute name for the user profile.

Use a Refresh Token

Next Steps

Now that you have a working connection, the next step is to configure your application to use it. You can follow our step-by-step quickstarts or use our libraries and API.