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.
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.
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.
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:
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