Single Sign-On(SSO) Plugins allow you replace the authentication process within Telligent Community.  If you have an external application with its own custom authentication process you can use Single Sign On plugins to force Telligent Community to use your custom authentication flow.

[toc]

When Should I Create An Custom SSO Plugin?

You only need to create a custom SSO extension if one of the below extensions do not meet the needs of your application.  In most cases however, applications, especially web applications, can use the cookies authentication SSO extension by altering their authentication code to write the required cookie.

The following extensions are already available as part of the Telligent Community core product and can be configured in the Administration -> Authentication area:

Cookies Authentication

This allows a user to be logged in by a third party cookie.   The external application would create this cookie and Telligent Community would recognize it and use to authenticate a user.  This module works for most web based applications if that application is capable of writing and encrypted cookie and exists on the same parent domain as your Telligent Community instance.

Forms Authentication

This is specific to ASP.NET sites.  By default Telligent Community uses Forms authentication so  it is capable of reading or sharing that authentication cookie with other ASP.net site using forms authentication provided each site has configured authentication the same.

Creating an SSO Extension

The IAuthenticationPlugin interface essentially consists of one method:

public int? GetAuthenticatedUserId(AuthenticationOptions options)
{

The AuthenticationOptions object wraps the HttpContext associated with the application request. We can extract it and do a sanity check before proceeding.

    HttpContextBase context = options.HttpContext;
    if (context == null)
        return null;

The HttpContext should hold everything you need to know to extract the identity of the requesting user. The implementation details here are based on your system and how it stores identity.

    // For instance, a certain cookie...
    HttpCookie cookie = context.Request.Cookies["CookieName"];
    if (cookie == null)
        return null;

    // or the context ASP.net user.
    if (context.User == null || context.User.Identity == null || string.IsNullOrEmpty(context.User.Identity.Name))
        return null;

Once you have the needed information to look up the user from Telligent Community API, you can do that. If the user isn't found, you do have the capability here to create a new user account in Telligent Community using the API. This may be useful to do as a method of keeping Telligent Community accounts in sync with the external system. Otherwise, you simply have to throw an error indicating the login attempt failed.

    var userApi = Apis.Get<IUsers>();

    User foundUser = userApi.Get(new UsersGetOptions { Username = "username" });

    if (foundUser == null)
    {
        // If the user doesn't exist, you may want to create an account
        // if you are trying to stay synced with another system.

        // If not, you can throw an exception here about the login failing.
        throw new Exception("Login Failed");
    }

Once the user is retrieved, the method requires you to return the user's id for further use by Telligent Community to fulfill the request.

    // Assuming a user was found, return the id for Community to use.
    return foundUser.Id;
}

Here's the full sample implementation:

using System;
using System.Web;
using Telligent.Evolution.Extensibility;
using Telligent.Evolution.Extensibility.Api.Entities.Version1;
using Telligent.Evolution.Extensibility.Api.Version1;
using Telligent.Evolution.Extensibility.Security.Version2;

namespace Sample
{
    class SampleAuthenticationPlugin : IAuthenticationPlugin
    {
        #region IPlugin Implementation

        public string Name
        {
            get { return "Sample Authentication Single-Sign-On Client"; }
        }

        public string Description
        {
            get { return "Sample IAuthentication plugin implementation."; }
        }

        public void Initialize()
        {
            // Leave blank if not needed.
        }

        #endregion

        public int? GetAuthenticatedUserId(AuthenticationOptions options)
        {
            // Check the HttpContext from the given options
            HttpContextBase context = options.HttpContext;
            if (context == null)
                return null;

            // Use the context to extract the needed information about the accessing user.
            // For instance, from a certain cookie...
            HttpCookie cookie = context.Request.Cookies["CookieName"];
            if (cookie == null)
                return null;

            // or from the context ASP.net user.
            if (context.User == null || context.User.Identity == null || string.IsNullOrEmpty(context.User.Identity.Name))
                return null;

            // Extract information to identify the user.

            // Access the User API and find the user based on the information retrieved above.
            var userApi = Apis.Get<IUsers>();

            User foundUser = userApi.Get(new UsersGetOptions { Username = "username" });

            if (foundUser == null)
            {
                // If the user doesn't exist, you may want to create an account
                // if you are trying to stay synced with another system.

                // If not, you can throw an exception here about the login failing.
                throw new Exception("Login Failed");
            }

            // Assuming a user was found, return the id for Community to use.
            return foundUser.Id;
        }
    }
}

Using An External Login Process

The IExternalAuthenticationPlugin interface adds some additional url properties to allow use of custom/external pages for login control. Use this type when you want navigation of the account management process to be managed by a third party system. A ReturnUrl callback is included so you can navigate the user back to Telligent Community once logged in. Note that use of IConfigurablePlugin would be useful for allowing these properties to be edited in Administration without restarting the site.

Most of the properties on this interface specify what urls Telligent Community should send the user to for completing various actions: logging in, logging out, resetting password, creating an account, etc.

public string ChangePasswordUrl
{
    get { return ""; }
}

public string CreateUserUrl
{
    get { return ""; }
}

public string ForgottenPasswordUrl
{
    get { return ""; }
}

public string LoginUrl
{
    get { return ""; }
}

public string LogoutUrl
{
    get { return ""; }
}

The final property specifies what query string key Telligent Community will use to add the return url to calls to your application. You then return the user to this url when the sign-in (or other) process is complete.

public string ReturnUrlParameter
{
    get { return ""; }
}