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
• Obtaining a SAML Token
• Registering or Authenticating a User

Prerequisites

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

• Ensure that your AD FS is set up as described in Introduction to Active Directory Federation Services Integration.
• Ensure that you have enabled AD FS login in your app as described in Enabling Active Directory Federation Services Integration.

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 JavaScript SDK method for registration/authentication.

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

The Backend Services JavaScript SDK provides a single method 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.

The Authentication.loginWithADFS() method takes an Base64-encoded AD FS SAML security token that you must have acquired beforehand. 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. If the user has already been registered, the object contains Id and CreatedAt fields in addition.

var el = new Everlive('your-app-id');
var accessToken = "AD FS access token here";
el.authentication.loginWithADFS(accessToken,
    function (data) {
        alert(JSON.stringify(data));
    },
    function(error){
        alert(JSON.stringify(error));
    });

See Also

• Introduction to Active Directory Federation Services Integration
• Enabling Active Directory Federation Services Integration
• Introduction to User Management
• Friends Sample App

External resources:

• Request a token from AD FS using WS-Trust from iOS, Objective-C, IPhone, IPad, Android, Java, Node.js or any platform or language
• Request AD FS Security Token with PowerShell
• Using Active Directory Federation Services 2.0 in Identity Solutions
• Message Protection Patterns