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

Integrating Active Federation

Integrating Active Federation

Active federation involves contacting the Active Directory Federation Services (AD FS) web services endpoints. You need to obtain an AD username and password pair from your app user before you can use active federation.

Prerequisites

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

Obtaining a SAML Token

You need to obtain a SAML security token from the Active Directory Federation Services Security Token Service (AD FS STS) before calling the Telerik Platform endpoint for registration/authentication.

The following steps explain the basic method for obtaining a SAML security token: filling in a template RST message and sending it to the STS over HTTPS as a Web Services request.

The presented method uses Transport Layer Security. If you need a higher degree of security, discuss the alternatives with your AD FS administrator.

  1. Customize the following request body template for your environment. You need to replace the following tag values:

    • <s:Header><a:To>—the URL of the UsernameMixed endpoint
    • <o:Security><o:UsernameToken><o:Username>—the username of the AD user account that you want to register or authenticate, including the domain name
    • <o:Security><o:UsernameToken><o:Password>—the password for the above user
    • <s:Body><trust:RequestSecurityToken><wsp:AppliesTo><a:EndpointReference><a:Address>—the URL of Backend Services API server appended with a slash and then your app's App ID.

      <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope"
                  xmlns:a="http://www.w3.org/2005/08/addressing"
                  xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
        <s:Header>
          <a:Action s:mustUnderstand="1">http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue</a:Action>
          <a:To s:mustUnderstand="1">https://your.adfs.server/adfs/services/trust/13/UsernameMixed</a:To>
          <o:Security s:mustUnderstand="1" xmlns:o="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <o:UsernameToken>
              <o:Username>adfs-user@your.adfs.server</o:Username>
              <o:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">your-password</o:Password>
            </o:UsernameToken>
          </o:Security>
        </s:Header>
        <s:Body>
          <trust:RequestSecurityToken xmlns:trust="http://docs.oasis-open.org/ws-sx/ws-trust/200512">
            <wsp:AppliesTo xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
              <a:EndpointReference>
                <a:Address>https://api.everlive.com/v1/your-app-id</a:Address>
              </a:EndpointReference>
            </wsp:AppliesTo>
            <trust:KeyType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Bearer</trust:KeyType>
            <trust:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue</trust:RequestType>
            <trust:TokenType>urn:oasis:names:tc:SAML:2.0:assertion</trust:TokenType>
          </trust:RequestSecurityToken>
        </s:Body>
      </s:Envelope>
      
  2. Send a POST request to your your AD FS service's UsernameMixed endpoint using the body the you constructed in the previous step.

    Request:
        POST https://your.adfs.server/adfs/services/trust/13/UsernameMixed
    Headers:
        Content-Type application/soap+xml; charset=utf-8
    Body:
        (Body from previous step)
    
    Response:
        Status: 200 OK
    Content-Type:
        application/soap+xml; charset=utf-8
    Body:
        (skipped for brevity)
    
  3. Take the XML data that you received as response and encode it in Base64 format.

The resulting Base64-encoded string is the SAML token in a format suitable for passing to Backend Services RESTful endpoints or SDK methods.

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:

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