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 .NET 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 .NET 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 async Task<AccessToken> LoginUser(EverliveApp app, string username, string password)
{
    return await 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 .NET SDK operations. In that, the LoginWithAdfs() method behaves similarly to the Login() method.

Manual Implementation

The Backend Services .NET 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 async Task<AdfsMetadata> GetAdfsMetadata()
{
    return await this.everliveApp.WorkWith().Authentication().GetAdfsMetadata().ExecuteAsync();
}

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

This section shows how to obtain a SAML security token using Windows Identity Foundation. To make the following web services calls, you need the AD FS metadata that you obtained in Getting AD FS Metadata.

using System;
using System.IdentityModel.Protocols.WSTrust;
using System.IdentityModel.Tokens;
using System.Linq;
using System.ServiceModel;
using System.ServiceModel.Security;
using System.Text;

namespace AdfsHelper
{
    public static class AdfsHelper
    {
        /// Gets a Base64-encoded SAML token.
        /// wsTrust13Endpoint: https://example.com/adfs/services/trust/13/usernamemixed
        /// realm: https://api.everlive.com/v1/your-app-id
        /// username: username
        /// password: password
        public static string GetBase64EncodedToken(string wsTrust13Endpoint,
            string realm,
            string username,
            string password)
        {
            var binding = new WS2007HttpBinding(SecurityMode.TransportWithMessageCredential);

            // If you set this to true, you can use a Security Context Token (SCT) for your next
            // calls to the STS instead of sending a Username and Password each time.
            binding.Security.Message.EstablishSecurityContext = false;

            // Instead of using Username/Password authentication you can use any of the 
            // other ClientCredentialType's such as Certificate, IssuedToken or Windows.
            binding.Security.Message.ClientCredentialType = MessageCredentialType.UserName;

            // The same applies to the transport level security. You can secure it in any 
            // of the available ways.
            binding.Security.Transport.ClientCredentialType = HttpClientCredentialType.None;

            var endpoint = new EndpointAddress(wsTrust13Endpoint);
            var factory = new WSTrustChannelFactory(binding, endpoint);
            factory.TrustVersion = TrustVersion.WSTrust13;
            factory.Credentials.SupportInteractive = false;

            // If your MessageCredentialType differs from UserName, make sure you supply 
            // the valid credential here.
            factory.Credentials.UserName.UserName = username;
            factory.Credentials.UserName.Password = password;

            var rst = new RequestSecurityToken()
            {
                RequestType = RequestTypes.Issue,
                KeyType = KeyTypes.Bearer,
                AppliesTo = new EndpointReference(realm),
                TokenType = "urn:oasis:names:tc:SAML:2.0:assertion"
            };

            var channel = (WSTrustChannel)factory.CreateChannel();
            RequestSecurityTokenResponse rstr;
            try
            {
                SecurityToken token = channel.Issue(rst, out rstr);
                // This is an XML string of the form <Assertion>...</Assertion>
                var xml = rstr.RequestedSecurityToken.SecurityTokenXml.OuterXml;
                var base64Token = Convert.ToBase64String(Encoding.UTF8.GetBytes(xml));
                return base64Token;
            }
            catch (Exception e)
            {
                return null;
            }
        }
    }
}

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 async Task<AccessToken> LoginUser(EverliveApp app, string token)
{
    return await 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.