Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Introduction to Active Directory Federation Services Integration

Introduction to Active Directory Federation Services Integration

Telerik Platform provides a mechanism for registration and authentication of users using Active Directory Federation Services (AD FS) 2.0 as Identity Provider. You can use it to tap into the single-sign on (SSO) infrastructure of your enterprise.

Authentication Pattern

After your AD FS administrator has set up AD FS as laid out in Enabling Active Directory Federation Services Integration, you can start implementing AD FS brokered authentication in your application. Similarly to social login, it features three participants:

  • Client app Your app plays the role of the AD FS client.
  • Telerik Platform Your app's backend plays the role of the Service Provider (SP).
  • AD FS 2.0 Security Token Service (STS) AD FS is the Identity Provider (IDP).

The authentication workflow depends on whether you are implementing active or passive federation.

Passive Federation

With passive federation, your application plays the role of the so called passive requestor. It requires the presence of a Web browser supporting cookies and JavaScript on the client. In this case most work is done by the browser.

The following diagram illustrates the authentication flow when using passive federation.

AD FS passive federation diagram

  1. The mobile app checks if the user is logged in to Telerik Platform.
  2. If not, the app opens a web browser and points it to the AD FS STS for user authentication.
  3. The AD FS STS presents a login page to the user in the web browser.
  4. The user enters their username and password and sends them to the AD FS STS.
  5. The AD FS STS validates the user credentials and issues a security token (also known as an assertion) back to the web browser.
  6. The web browser makes an HTTP request to the Telerik Platform Reply URL, appending the security token to it.
  7. Telerik Platform contacts the AD FS STS to validate the content of the token. On success, Telerik Platform does one of the following:
    • Registers the user in case of first-time users.
    • Authenticates the user in case of returning users.
  8. Telerik Platform issues a Telerik Platform access token and returns it to your app. The Telerik Platform access token is used for subsequent communication until the user logs off or the token expires or is invalidated.

Active Federation

With active federation, your application plays the role of the so called active requestor. It provides transparent authentication that does not require user intervention nor does it require a Web browser.

The following diagram illustrates the authentication flow when using active federation.

AD FS active federation diagram

  1. The client app sends a user authentication request known as Request Security Token (RST) to the AD FS STS that features username and password.
  2. The AD FS STS validates the client credentials and issues a security token (also known as an assertion) to the client.
  3. The client app sends the security token to Telerik Platform.
  4. Telerik Platform contacts the AD FS STS to validate the content of the token. On success, Telerik Platform does one of the following:
    • Registers the user in case of first-time users.
    • Authenticates the user in case of returning users.
  5. Telerik Platform issues a Telerik Platform access token and returns it to your app which concludes the authentication flow. The Telerik Platform access token is used for subsequent communication until the user logs off or the token expires or is invalidated.

Important Notes

These are a few important notes that you need to know about when using AD FS authentication in Telerik Platform:

  • Telerik Platform creates a user account for the user the first time that they authenticate through AD FS. Subsequent authentication requests simply authenticate the user. This way the same endpoint is used for both registration and authentication.
  • Users registered through an AD FS access token do not have a username in Telerik Platform.
  • The app's default role is assigned to the user.
  • The user is automatically marked as verified.
  • The user profile that Telerik Platform reads from AD is stored as an object in the user account's Identity.ADFS field. The Identity field is visible only when using MasterKey authentication or when a request is made for a specific User object using bearer authentication and the passed access token is issued for the user that the object represents (e.g. getting a user object by Id).
  • The AD name of the user is stored in the user account's DisplayName field.
  • If the provided token has a claim for email, then the AD email address is stored in the Email field of the user.
  • If the application is configured to send a welcome email and an email address is included in the user's AD profile, then the user receives the email.
  • From a security standpoint, Telerik Platform user accounts created from AD FS user accounts are treated exactly the same as Telerik Platform-only user accounts.

Linking and Unlinking AD User Accounts

In addition to authenticating (and registering) AD users, Telerik Platform supports linking your existing app users to their AD user account. This allows them to log in to your app using both their Telerik Platform and AD credentials.

Unlinking a user account from an AD user account prevents the user from logging in using AD FS. Note that the user will still be able to log in using their Telerik Platform account username and password.

You can link or unlink user accounts using the Backend Services RESTful API or the appropriate client SDK. Refer to the See Аlso links for more information.

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.