Introduction

AuthAnvil Single Sign-On (SSO) was designed from the ground up to be highly extensible by using the Managed Extensibility Framework (MEF) within the .NET Framework. There are five components to the server:

• Security Token Service
• Protocol Handlers
• Repositories
• Attribute Definition Language
• User Interface

Each component dependency is injected through MEF composition.

Security Token Service

At the core of AuthAnvil SSO is a Security Token Service (STS). The STS issues tokens for Service Providers (SP) to consume for authentication and authorization. It aggregates attributes/claims for the given SP by parsing a collection of Attribute Definition Language (ADL) Maps and generates a principal for a protocol handler to serialize into something consumable by the SP.

Protocol Handlers

A protocol handler is used to accept requests and issue security tokens. There are three protocol handlers out of the box:

• SAML IdP-Init
• SAML SP-Init
• WS-Federation

Each handler is responsible for parsing the request for a token and generating the appropriate response to issue the token to the SP. Each protocol supports SAML2. Custom protocols can be added by creating a class that inherits from

PassiveProtocolHandler

and decorating with the

[Export(typeof(PassiveProtocolHandler))]

attribute.

Repositories

AuthAnvil SSO uses a repository-based architecture to store and retrieve data. The default repository uses SQL Server to store data. Repositories are designed to support multi-tenancy by filtering via Site ID internally. There are ten repositories within SSO. Each repository handles the retrieval of data as well as the storage of data. Unless otherwise specified all repositories require site filtering. Repositories are based on the following interfaces.

Each repository is designed to allow for replacement without affecting any other repository. The repository interfaces are declared in the ScorpionSoft.IdentityServer.Common.dll assembly.

Attribute Definition Language

The Attribute Definition Language (ADL) is designed to map attributes within a particular data source to an attribute within the token for a particular Service Provider. Each ADL map is associated with a transform provider. A transform provider interprets the values within the map and queries the data from its particular data source. The basic structure of the language is:

("AttributeSource" => "OutputtedAttributeName")

The AttributeSource is used to identify the location of the value and the OutputtedAttributeName is the attribute type within the token. For instance

("Email" => "MyEmailAddress")

Will query the Email property of the user and output the attribute as type MyEmailAddress. The default transform provider will query the current UserAttributeRepository. ADL also supports literal string output as well. This is useful if you want a global output value for all users for a particular SP. It can be used by appending the ‘@’ character to the attribute source:

(@"12345" => "orgID")

Custom transform providers can be built by implementing the IClaimsTransformer interface and decorating it with the [Export(typeof(IClaimsTransformer))] attribute.

User Interface

The User Interface (UI) is where the user interacts with the SSO Portal to access applications they are authorized to use. It also contains the service endpoints for the administration web service and surfaces the protocol handler endpoints.

Service Provider Federation

AuthAnvil SSO was developed to allow applications to federate easily through simple configuration. An application only requires four values for setup:

• The Application name – This must be a unique name across all applications.
• The Application Audience URI – This is a unique identifier used by the application to request a token.
• The Return URL – This value is where the token is sent to on successful authentication; e.g. a page within the application.
• The Protocol – This is used to specify which protocol should be used to handle incoming requests and generate token responses.

Once these values have been configured all that’s necessary is to configure the Service Provider to accept tokens from AuthAnvil SSO. As stated earlier there are three protocols supported currently:

• SAML IdP-Init (Reference)
• SAML SP-Init (Reference)
• WS-Federation (Reference)

Each protocol was implemented to follow industry standard specifications. There are a variety of libraries for consuming SAML tokens available for many different web stacks. We have tested our tokens against many of them. We support:

• ComponentSpace SAML Library
• Windows Identity Foundation for WS-Federation
• Windows Identity Foundation SAML Library
• SimpleSAMLphp
• AuthAnvil SAML PHP

Windows Identity Foundation

The Windows Identity Foundation helps simplify user access for developers by externalizing user access from applications via claims and reducing development effort with pre-built security logic and integrated .NET tools. Users can benefit through single sign-on and seamless collaboration across organizational boundaries.

We created a sample application for federating with AuthAnvil Single Sign On using the Windows Identity Foundation. You can download the sample application here.

We also created a sample that shows how you can use WIF and AuthAnvil Single Sign On in applications that support multi-tenancy. We have samples for both .NET 3.5/4.0 and .NET 4.5.

• .NET 4.5
• .NET 3.5/4.0

AuthAnvil SAML PHP

We created a very simple PHP kit for consuming SAML tokens so PHP developers could get started quickly and easily. This kit was developed so users don’t have to worry about all the moving pieces of other libraries like SimpleSAMLphp until they need all the features provided by a library such as SimpleSAMLphp.

You can download the kit here.

Consuming a SAML token with our kit is simple. For example:

<?php
    require_once 'Config.php';

    if(!empty($_GET['login']))
    {
        $authRequest = new AuthnRequest($config);
        $url = $authRequest->RedirectUrl();

        header("Location: $url");
        return;
    }

    $validToken = FALSE;
    $signOutUrl = $config->IdPSignOutUrl;

    if(!empty($_POST['SAMLResponse']))
    {
        $samlResponse = new SamlResponse($config, $_POST['SAMLResponse']);
        $validToken = $samlResponse->IsTokenValid();
    }

	if($validToken)
	{
		// CreateSession($samlResponse);
	}
?>
<html>
    <head>
        <title>PHP Federation</title>
        <link href="Style/StyleSheet.css"
              rel="stylesheet"
              type="text/css" />
    </head>
    <body>
        <div class="container">
            <h1>Federate PHP with SAML</h1>
            <?php if($validToken) { ?>
       Hi, <?php echo $samlResponse->NameId() ?>.
            <span style="color: green">Token is valid!</span>
            <a href="<?php echo $signOutUrl ?>">Sign Out</a>
            <?php } else { ?>
            <span style="color: #ff0000">Token is not valid!</span>
            <div>
                <a href="index.php?login=1">Sign In</a>
            </div>
            <?php } ?>
            <h3>Attributes</h3>
            <?php

                if($validToken)
                {
                    $attributes = $samlResponse->GetAttributes();

                    if (!empty($attributes) && $validToken) 
                    {
                        echo '<pre>';
                        print_r($attributes);
                        echo '</pre>';
                    } 
                    else
                    {
                        echo 'Cannot show attributes';
                    }
                }
                else
                {
                    echo 'Please sign in first';
                }
            ?>
            <h3>Token</h3>
            <?php if($validToken) { ?>
            <textarea style="width: 1000px; height: 400px"><?php echo htmlentities( base64_decode( $_POST['SAMLResponse'] )) ?></textarea>
            <?php } else { ?>
           Please sign in first
            <?php } ?>
        </div>
    </body>
</html>

For more information take a look at the provided kit above.

SAML IdP-Init

Identity Provider (IdP) initiation is the act of starting a federated authentication workflow from within the SSO Portal. In this workflow the Service Provider doesn’t know how to request a token so everything must kick off from within the SSO Portal. In order to start the workflow a request must be made to the IdP-Init protocol handler. This can be done by passing the Audience URI of the Service Provider at the following URL:

federation/passive/Saml2IdPInit?sp=uri:authanvil:passwordserver

This will cause the protocol handler to generate a token for the given Service Provider and post it to the reply-to URL.

SAML SP-Init

Service Provider initiation is the act of the Service Provider starting the federated authentication workflow and requesting a token from the SSO Portal. The SP-Init workflow is usually started by a Service Provider requesting a security token. The request is passed into the protocol handler via the SAMLRequest parameter at the following URL:

federation/passive/Saml2SPInit?SAMLRequest=[base64 encoded request]

The SAMLRequest parameter is a base64 encoded and compressed XML string. In order to allow users to connect to SP-Init configured applications directly from the SSO Portal, the SSO Portal supports internal generation of the SAMLRequest as well. The AuthAnvil SSO Portal also allows for SP-Init through a non-standard active service at the following endpoint:

Services/SPInit.svc

This service exposes the following members.

WS-Federation

The WS-Federation protocol is a subset of the WS-Security protocol suite. It is similar in nature to the SP-Init workflow in that the Service Provider (or Relying Party when working with WS-Federation) requests a token. The WS-Federation workflow is started by the Service Provider requesting a token by passing its Audience URI to the following URL:

federation/passive/WSFed?wa=wsignin1.0&wtrealm=https://app.audience.uri

The protocol handler requires that both the wa and wtrealm parameters be set.

Administration API

AuthAnvil SSO handles all administration through a SOAP Web Service which can be accessed at the following endpoint:

Services/admin.svc

The admin web service is an interface to the repositories. This service exposes the following members.

UserWithId

Retrieves a user within the admin user’s site with a given internal user ID. Throws AccessDeniedFault

WithUserName

Retrieves a user within the admin user’s site with a given user name. Throws AccessDeniedFault

WithUserNameAndSite

Retrieves a user within the provided site by user name. Throws AccessDeniedFault

AllUsers

Gets a list of all users within the admin user’s site. Throws AccessDeniedFault

CreateUser

Creates a user within the admin user’s site. Throws AccessDeniedFault

UpdateUser

Updates a user within the admin user’s site. Throws AccessDeniedFault

DeleteUser

Deletes a user within the admin user’s site. Throws AccessDeniedFault

UsersInRole

Gets all users in the specified role within the admin user’s site. Throws AccessDeniedFault

AllProtocols

Gets a list of all protocols hosted on the server. Throws AccessDeniedFault

ForServiceProvider

Gets the ADL maps for the given Service Provider within the admin user’s site. Throws AccessDeniedFault

UpdateAdlRule

Updates an ADL map for a given Service Provider within the admin user’s site. Throws AccessDeniedFault

CreateRuleFor

Creates an ADL map for the given Service Provider within the admin user’s site. Throws AccessDeniedFault

DeleteRule

Deletes an ADL map for a given Service Provider within the admin user’s site. Throws AccessDeniedFault

AllRoles

Gets a list of all roles within the admin user’s site. Throws AccessDeniedFault

RolesFor

Gets a list of all roles a user belongs within the admin user’s site. Throws AccessDeniedFault

RolesAllowedToAccess

Gets a list of roles that can access the given Service Provider within the admin user’s site. Throws AccessDeniedFault

AddRole

Creates a role within the admin user’s site. Throws AccessDeniedFault

RemoveRoleFromServiceProvider

Removes the authorization for a role to access the given Service Provider within the admin user’s site. Throws AccessDeniedFault

AddRoleToServiceProvider

Authorizes a role to access then given Service Provider within the admin user’s site. Throws AccessDeniedFault

AddUserToRole

Adds the given user to the given role within the admin user’s site. Throws AccessDeniedFault

AddUsersToRole

Adds the collection of given users into the given role within the admin user’s site. Throws AccessDeniedFault

AddUserToRoles

Adds the given user into the given collection of roles within the admin user’s site. Throws AccessDeniedFault

AddUsersToRoles

Adds the given collection of users to the given collection of roles within the admin user’s site. Throws AccessDeniedFault

RemoveUserFromRole

Removes the given user from the given role within the admin user’s site. Throws AccessDeniedFault

DeleteRole

Deletes the given role within the admin user’s site. Throws AccessDeniedFault

RoleWithId

Gets the role with the given internal ID within the admin user’s site. Throws AccessDeniedFault

UpdateRole

Updates the given role within the admin user’s site. Throws AccessDeniedFault

Server

Gets the current server settings. Throws AccessDeniedFault

UpdateServer

Updates the current server settings. Throws AccessDeniedFault

NewServer

Creates a new server profile. Throws AccessDeniedFault

AllServiceProviders

Gets a list of all Service Providers within the admin user’s site. Throws AccessDeniedFault

WithAudienceUri

Gets the Service Provider with the given Audience URI within the admin user’s site. Throws AccessDeniedFault

ServiceProviderWithId

Gets the Service Provider with the given internal ID within the admin user’s site. Throws AccessDeniedFault

ServiceProviderUsingProtocol

Gets all Service Providers using the given protocol within the admin user’s site. Throws AccessDeniedFault

ServiceProviderAccessibleByUser

Gets all Service Providers accessible by the given user within the admin user’s site. Throws AccessDeniedFault

ServiceProviderAccessibleByRole

Gets all Service Providers accessible by the given role within the admin user’s site. Throws AccessDeniedFault

CreateServiceProvider

Creates a new Service Provider within the admin user’s site. Throws AccessDeniedFault

UpdateServiceProvider

Updates the given Service Provider within the admin user’s site. Throws AccessDeniedFault

DeleteServiceProvider

Deletes the given Service Provider within the admin user’s site. Throws AccessDeniedFault

AttributesForUser

Gets all stored attributes for the given user within the admin user’s site. Throws AccessDeniedFault

UpdateAttributeForUser

Updates the given attribute for the given user within the admin user’s site. Throws AccessDeniedFault

DeleteAttributeForUser

Deletes the given attribute for the given user within the admin user’s site. Throws AccessDeniedFault

AddAttributeForUser

Adds the given attribute to the user within the admin user’s site. Throws AccessDeniedFault

KnownAttributeNames

Gets a list of all known attribute names within the admin user’s site. Throws AccessDeniedFault

Site

Gets the current admin’s site configuration. Throws AccessDeniedFault

SiteWithId

Gets the site configuration by the specified internal ID. Throws AccessDeniedFault

AllSites

Gets a list of all site configurations. Throws AccessDeniedFault

UpdateSite

Updates the given site configuration. Throws AccessDeniedFault

CreateSite

Creates a new site and configuration. Throws AccessDeniedFault