AuthAnvil Single Sign On APIs

Developer Center - Scorpion Software

­

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.

Interface

Description

IAdlRuleRepository

Accesses the ADL Rules

ICryptoRepository

Access to keying data as well as crypto transforms

IProtocolRepository

Access to protocol handler configuration

IRoleRepository

Access to role configuration

IServerRepository

Access to Server-level configurationNot site specific

IServiceProviderRepository

Access to service provider configuration

ISessionRepository

Access to sessions and session configuration

ISiteRepository

Access to current site configuration

IUserAttributeRepository

Access to user attribute data

IUserRepository

Access to user configuration

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.

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.

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.

Method Name

Description

Faults Thrown

RequestSamlToken

Authenticates a user with Two Factor Auth credentials and returns a base64 encoded string of a SAML token for the given user and for the specified Assertion Consumer Service URL.

AccessDeniedFaultUserNotSsoEnabledFault

RequestSamlTokenWithSamlRequest

Authenticates a user with Two Factor Auth credentials and returns a base64 encoded string of a SAML token for the given user and for the specified SAML Request.

AccessDeniedFaultUserNotSsoEnabledFault

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: