Introduction to SAML Login Integration

Introduction to SAML Login Integration

First introduced in Backend Services JavaScript SDK version 1.7.2

Telerik Platform provides a mechanism for registration and authentication of users coming from identity providers supporting the Security Assertion Markup Language (SAML). This can be a cloud SAML identity provider or an internal SAML identity provider available inside your enterprise.

In the SAML authentication scheme, Telerik Platform serves the role of the service provider (SP).

Telerik Platform supports SAML version 2.0.

Authentication Pattern

After your SAML IdP administrator has set it up as laid out in Enabling SAML Integration, you can start implementing SAML authentication in your application. It features three participants:

  • Client app Your app plays the role of the SAML Principal.
  • Telerik Platform Your app's backend plays the role of the Service Provider (SP).
  • Your Identity Service The identity service that you use is the Identity Provider (IdP) defined by the SAML standard.

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 user agent (Web browser) supporting cookies and JavaScript on the client. In this case most work is done by the user agent.

Passive federation may not be supported by your IdP.

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

SAML passive federation diagram

  1. (Optional) 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 SAML IdP for user authentication.
  3. The SAML IdP presents a login page to the user in the web browser.
  4. The user enters their username and password and sends them to the SAML IdP.
  5. The SAML IdP validates the user credentials and issues an assertion to the Telerik Platform Reply URL through the web browser.
  6. The client app parses the SAML assertion and passes it to Telerik Platform.
  7. Telerik Platform validates the content of the SAML assertion with the IdP. 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.

Active federation may not be supported by your IdP.

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

SAML active federation diagram

  1. The client app sends a user authentication request known as Request Security Token (RST) to the SAML IdP that features username and password.
  2. The SAML IdP validates the client credentials and issues an assertion (security token) to the client.
  3. The client app sends the assertion to Telerik Platform.
  4. Telerik Platform validates the content of the token. If you have specified a SAML metadata URL, Telerik Platform contacts the IdP. If you have uploaded a SAML metadata XML file, Telerik Platform uses the file. 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 SAML authentication in Telerik Platform:

  • Telerik Platform creates a user account for the user the first time that they authenticate through SAML. Subsequent authentication requests simply authenticate the user. This way the same endpoint is used for both registration and authentication.
  • Users registered through a SAML 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 the SAML IdP is stored as an object in the user account's Identity.SAML 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).
  • If the provided token has a claim for email, then the SAML IdP 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 SAML IdP profile, then the user receives the email.
  • From a security standpoint, Telerik Platform user accounts created from SAML IdP user accounts are treated exactly the same as Telerik Platform-only user account.

Linking and Unlinking SAML User Accounts

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

Unlinking a user account from a SAML user account prevents the user from logging in using SAML. 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.