Integrating Active SAML Federation

Integrating Active Federation

Active federation involves contacting the SAML IdP web services endpoints directly. You need to obtain the user credentials from your app user before you can use active federation. The type of credentials vary from SAML IdP to SAML IdP.

Prerequisites

You need to make certain settings before you can successfully log in your app users through a SAML IdP.

Obtaining a SAML Assertion

You need to obtain a SAML assertion from the SAML IdP before calling the Telerik Platform endpoint for registration/authentication.

How you obtain the SAML assertion depends on your SAML IdP. Consult its documentation for detailed steps. The general steps include the following:

  1. Prepare an XML file with information specific to your SAML IdP and Telerik Platform.
    You will most likely need the Telerik Platform Audience URL and Reply URL.
  2. Send the XML file deflated, Base64-encoded and URL-encoded to a designated endpoint provided by the SAML IdP.
  3. Parse the XML response to extract the assertion value.
  4. Encode the assertion value to a URL-safe format.

Registering or Authenticating a User

The Backend Services RESTful API provides a single endpoint that is used for both registration and authentication. On first invocation the user is registered with Telerik Platform. On consequent invocations for the same user Telerik Platform authenticates the user.

You register or log in a SAML user by making a POST request to the built-in Users content type. You need to specify the Provider as SAML and to use the URL-encoded assertion value that you acquired earlier.

The request result contains the Telerik Platform access token and its type in the access_token and token_type fields. Registration requests will also return the Id of the created user along with its CreatedAt date on the server. Use the Telerik Platform access token in subsequent requests to Telerik Platform endpoints.

The SAML assertion typically has an expiration date. This expiration date is automatically transferred to the Telerik Platform access token. When it is reached, obtain a fresh SAML assertion before issuing a new registration/authentication call.

Request:
    POST https://api.everlive.com/v1/your-app-id/Users
Headers:
     Content-Type: application/json
Body:
    {
        "Identity": {
            "Provider": "SAML",
            "Token": "your-URL-encoded-SAML-assertion"
        }
    }

Response:
    -When registering:-

    Status: 201 Created
    Content-Type: application/json
    Body: {
        Id: 'user id',
        CreatedAt: 'date',
        access_token: 'Telerik Platform token',
        token_type: 'bearer'
    }

    -When authenticating:-

    Status: 200 OK
    Content-Type: application/json
    Body: {
        access_token: 'Telerik Platform token',
        token_type: 'bearer'
    }
var user = {
    "Identity": {
        "Provider": "SAML",
        "Token": "your-URL-encoded-SAML-assertion"
    }
};
$.ajax({
    type: "POST",
    url: 'https://api.everlive.com/v1/your-app-id/Users',
    contentType: "application/json",
    data: JSON.stringify(user),
    success: function(data){
        alert(JSON.stringify(data));
    },
    error: function(error){
        alert(JSON.stringify(error));
    }
});

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.