Integrating Passive Federation

Integrating Passive Federation

Passive federation relies on the device's web browser to do most of the communication between the device and AD FS. That said, you still need to know what URL to request and how to acquire the SAML token from the Security Token Service's (STS) reply. The security benefit of passive federation is that the user never provides their AD credentials to your app.

The detailed passive federation workflow is presented in Introduction to Active Directory Federation Services Integration.

Prerequisites

You need to make certain settings before you can successfully log in your app users through AD FS.

Preparing the Request URL

To request a SAML token from the AD FS STS you need to open the device's web browser and point it to the appropriate URL.

The URL must be in the following format:

https:// + AD FS FQDN + /adfs/ls/ + ?wa=wsignin1.0&wreply= + AD FS metadata URL + /adfs/token + &wtrealm + AD FS realm

Where:

For example:

https://adfs.example.com/adfs/ls?wa=wsignin1.0&wreply=https://api.everlive.com/v1/your-app-id/adfs/token&wtrealm=https://api.everlive.com/v1/your-app-id

Extracting the SAML Access Token

After the browser contacts the AD FS STS and performs authentication, the STS redirects the browser to the Reply URL and posts the SAML token to it. The server logic behind the Reply URL encodes the SAML response in base64 format and redirects the user device browser to localhost appended with the access_token HTML parameter containing the SAML token. You need to parse the resulting URL to extract the SAML token from it.

The URL has the following format:

http://localhost?access_token=saml-access-token

Where saml-access-token is the base64-encoded SAML access token.

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 an AD user by making a POST request to the built-in Users content type. You need to specify the Provider as ADFS and to use the Base64-encoded SAML token 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 security token issued by AD FS has an expiration date. This expiration date is automatically transferred to the Telerik Platform access token. When it is reached, obtain a fresh SAML authentication token before issuing a new registration/authentication call.

Request:
    POST https://api.everlive.com/v1/your-app-id/Users 
Headers:
     Content-Type: application/json 
Payload - raw:
    {
        "Identity": {
            "Provider": "ADFS",
            "Token": "your-Base64-encoded-SAML-token"
        }
    } 
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": "ADFS",
        "Token": "your-Base64-encoded-SAML-token"
    }
};
$.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

External resources:

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.