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. The Backend Services Android SDK implements active federation through a single method, but it also features a few other methods that help you implement the active federation workflow yourself.

Prerequisites

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

Automatic Implementation

The Backend Services Android SDK provides a method that implements the entire active federation workflow—from discovering your AD FS WS-Trust 1.3 endpoint to requesting and verifying the SAML token to authenticating the user with Telerik Platform.

On first invocation, Telerik Platform registers the user. Consequent invocations for the same user authenticate the user.

With active federation, you need to obtain an AD username and password pair from the app user by showing a user interface form. This is sensitive information that never reaches Telerik Platform. Then pass the collected credentials to the loginWithAdfs() method overload that accepts username and password.

public void loginUser(EverliveApp app, String username, String password) {
    app.workWith().authentication().loginWithAdfs(username, password).executeAsync();
}

On success, the method returns an object containing a Telerik Platform access token (not to be mistaken with the AD FS SAML security token) that can be used with further Backend Services Android SDK operations. In that, the loginWithAdfs() method behaves similarly to the login() method.

Manual Implementation

The Backend Services Android SDK offers a few other methods that help you implement active federation yourself. However, you still need to implement code that obtains the AD FS SAML token.

Getting AD FS Metadata

You can use the getAdfsMetadata() method to read the app's AD FS metadata from the server. The AdfsMetadata class contains MetadataUrl and Realm members that correspond to the settings that you configured for your app on the backend.

public RequestResult<AdfsMetadata> getAdfsMetadata()
{
    return this.everliveApp.workWith().authentication().getAdfsMetadata().executeSync();
}

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 Backend Services Android SDK method for registration/authentication.

To make the following web services calls, you need the AD FS metadata that you obtained in Getting AD FS Metadata.

Use your favorite web services library to make the calls.

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

After you obtain an SAML token from the AD FS STS, you can use the LoginWithAdfs() method overload that accepts a Base64-encoded token.

On first invocation, LoginWithAdfs registers the user. Consequent invocations for the same user authenticate the user.

On success, the method returns an object containing a Telerik Platform access token (not to be mistaken with the AD FS SAML security token) that can be used with further Backend Services JavaScript SDK operations. In that, the loginWithAdfs() method behaves similarly to the login() method.

public void loginUser(EverliveApp app, String token) {
    app.workWith().authentication().loginWithAdfs(token).executeAsync();
}

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.