Active Directory Federation Services - OAuth#

Active Directory Federation Services OAuth (ADFS OAuth) is a method of allowing your users to use their Active Directory accounts to sign in. It allows users to use a username and password they already know without the need to remember another set.

Once the setup is complete you’ll be able to assign an Active Directory username to user accounts when you create them and the user will then be able to sign in using their school account.


You can easily enable the ADFS OAuth functionality by contacting your account manager.


You need to have an ADFS Server that supports OAuth in order for this to be possible.


If an account already has the AD users sub claim assigned this will need to be manually removed before the login can be assigned to a new user.

First Time Login#

You will need to link the Active Directory accounts to the user accounts. You can do this when creating the users using a batch, updating the users using a batch or by editing the user manually.

When a user signs in with your ADFS server a value is passed that represents the user, called a “Subject” (sub) claim. This value is what is stored and links the users accounts.

The first time a user signs in with an AD account this sub value needs to be linked to the users account. The system checks to see if the username is assigned to a user and auto linking is enabled. If the username isn’t assigned or auto linking is disabled the user won’t be able to access the system using their AD account.

If auto linking is enabled the local account will be updated to link the sub claims value, allowing future logins to be processed. (The auto link will then be disabled for this user)


If auto linking is disabled then users will have to manually link their AD and local accounts. They must sign into their local account and then go to their account settings and complete the link account process.


The username is only checked on the first login, subsequent logins use the sub claims value (which is never made public).


Your ADFS server must be hosted on a secure connection (https).

Signing in#

The first time a user signs in, the First Time Login process is completed. Subsequent logins are handled in following way.

When the user signs in using your ADFS server the system expects certain parameters and content to be formatted in a way that is known only to the servers completing the sign in. The system expects the following claims are present on the OAuth response:

  • sub - The sub or Subject claim should contain a unique identifier for the user being authenticated.

  • samaccountname - The SAM Account Name claim should contain the active directory username for the user being authenticated. This is used to perform the auto linking procedure and must therefore match the ADFS OAuth username provided in account setup.


The sub claims value is usually a unique identifier that isn’t publicly known to users. This makes the sign in more secure as only the servers know these values.

Signing Out#

When the user signs out they will be redirected to your ADFS sign out page to ensure they are also signed out of their AD account.