Custom Account Providers

Although The Identity Hub supports many out-of-the-box Account Providers, you might need one that is not available because:

  • You want to support a proprietary authentication method
  • You want to support a legacy user authentication database
  • ...

Create a Custom Account Provider

Step 1: Copy the necessary assemblies

To start developing you need to copy the following assemblies to your development machine:

  • U2UConsult.dll
  • U2UConsult.Framework.dll
  • U2UConsult.Framework.Identity.dll
  • U2UConsult.IdentityHub.AccountProvider.dll
  • U2UConsult.IdentityHub.Contracts.dll
  • U2UConsult.IdentityHub.Data.dll
  • U2UConsult.IdentityHub.Web.dll

The assemblies can be found in the installation folder of The Identity Hub. If you have trouble locating the assemblies contact us.

Step 2: Get the Example Visual Studio Class Library project

You can also create and start from a new Microsoft Visual Studio class library project. However we suggest you first try the example project and then create your own project.

The example project can be downloaded from https://github.com/TheIdentityHub/Custom-Account-Provider

  1. Open the project in Visual Studio 2017 or higher.
  2. You will find 7 classes in the project explained below. The name of the classes is arbitrary.
Note

In this example it is assumed that authentication validation happens within The Identity Hub using a custom view and model. This might not apply to every Custom Account Provider. If the Custom Account Provider redirects the user to an external site for authentication no local model and view is needed. Furthermore, if your Custom Account Provider uses a standars protocol like OAuth, OpenID Connect, Client Certificates, SAMLP... you can start from one of the out-of-the-box base classes available in the following libraries:

  • U2UConsult.IdentityHub.AccountProvider.ClientCertificate.dll
  • U2UConsult.IdentityHub.AccountProvider.OAuth2.dll
  • U2UConsult.IdentityHub.AccountProvider.OpenIdConnect.dll
  • U2UConsult.IdentityHub.AccountProvider.Samlp.dll
  • U2UConsult.IdentityHub.AccountProvider.WSFederation.dll

CustomAccountProvider

The entry point for calls from The Identity Hub infrastructure.

class CustomAccountProvider : IAccountProvider
Property or Method Description
int AccountProviderId The instance id of the Account Provider. Set by The Identity Hub infrastructure
U2UConsult.IdentityHub.Contracts.AccountProviders.IAccountProviderManager AccountProviderManager The Account Provider Manager of the Account Provider. Set by The Identity Hub infrastructure
System.Guid AccountProviderTypeId A System.Guid uniquely identifying the type of the Account Provider
bool AlwaysShowDisplayName true to always show the display name of the Account Provider, even when an image is available.
U2UConsult.IdentityHub.AccountProvider.AccountProviderConfiguration ConfigurationSettings The configuration settings for this Account Provider. Set by The Identity Hub infrastructure
bool IdentityCanEditInformation true if the information coming from the Account Provider can be edited, false otherwise.
string DisplayName The display name of the Account Provider.
string IssuerName The issuer name of the user information returned by the Account Provider.
bool LinkWithEnabled true if Accounts of the Account Provider can be linked to other Accounts of other Account Providers, false otherwise.
bool LogOnEnabled true if the Account Provider can be used to Authenticate, false otherwise.
System.Uri ProviderImageUrl The URL pointing to the image to display for the Account Provider.
bool RemoveAllIncomingClaimsThatAreNotMapped true if all incoming claims that are not mapped using claim mappings need to be removed, false otherwise.
bool SupportsSignOut true if the Account Provider supports single sign out, false otherwise.
string[] ProvidedClaimTypes The claim types returned by this Account Provider
System.Threading.Tasks.Task<ICollection<Claim>> GetListOfClaimsAsync(HttpRequestBase request, string state) Called by The Identity Hub infrastructure to retrieve the information (claims) from the authenticated user
System.Uri GetProfileUrl(Claim name, Claim privatePersonalIdentifier) The URL to profile of the user at the Account Provider. Return null if not available.
System.Threading.Tasks.Task<Uri> GetSignInUrlAsync(Uri returnUrl, string state) The URL to redirect the user for authentication using the Account Provider.
System.Uri GetSignOutUrl(Claim name, Claim privatePersonalIdentifier, Uri returnUrl) The URL to redirect the user for single sign out using the Account Provider.
System.Threading.Tasks.Task<ProcessLogonResult> ProcessLogOnAsync(HttpContextBase httpContext) Method called when the user has (attempted) to authenticate using the Account Provider. Use this method to process the authentication response.
void ProcessSignInComplete(HttpRequestBase httpRequest, string state) Method called when the sign in (authentication) using the Account Provider is complete.
void ProcessSignOut(HttpContextBase httpContext) Method called when the user signs out.

Method GetListOfClaimsAsync

Parameter Description
System.Web.HttpRequestBase request The current web request
string state A state passed by The Identity Hub infrastructure

The Identity Hub infrastructure will call this method after succesfull authentication using the Account Provider. The method should return the information on the authenticated user as claims.

Method GetProfileUrl

Parameter Description
System.Security.Claims.Claim name The name claim of the user.
System.Security.Claims.Claim privatePersonalIdentifier The PPID claim of the user.

Method should return the url to the profile of the user for this Account Provider. If no profile url is available, return null.

Method GetSignInUrlAsync

Parameter Description
System.Uri returnUrl The URL to return to after authentication using the Account Provider completes.
string state A state passed by The Identity Hub infrastructure

Method should return the url where the user should be redirected for authenticating using this Account Provider

Method GetSignOutUrl

Parameter Description
System.Security.Claims.Claim name The name claim of the user.
System.Security.Claims.Claim privatePersonalIdentifier The PPID claim of the user.
System.Uri returnUrl The URL to return to after authentication using the Account Provider completes.

Method should return the url where the user should be redirected to sign out for this Account Provider.

Method Task ProcessLogOnAsync

Parameter Description
System.Security.Claims.Claim name The name claim of the user.
System.Security.Claims.Claim privatePersonalIdentifier The PPID claim of the user.
System.Uri returnUrl The URL to return to after authentication using the Account Provider completes.

The Identity Hub infrastructure will call this method after the user returns from the external authentication. The method should process the authentication response and return a success or failure.

void ProcessSignInComplete

Parameter Description
System.Web.HttpRequestBase request The current web request
string state A state passed by The Identity Hub infrastructure

The Identity Hub infrastructure will call this method after the processing of the authentication of the user by The Identity Hub completes.

void ProcessSignOut

Parameter | Description :--- | :--- System.Web.HttpRequestBase request | The current web request The Identity Hub infrastructure will call this method when the user is singing out.

CustomAccountProviderConfiguration

This class allows for adding specific configuration parameters for the Account Provider. These can be retrieved from a database, configuration file...

class CustomAccountProviderConfiguration : AccountProviderConfiguration
Note

Currently it is not possible to configure these parameters in The Identity Hub UI.

CustomAccountProviderManager

The Account Provider Manager is called by The Identity Hub infrastructure when retrieving, deleting, updating an Account Provider, its configuration... .
You can use this class to validate the update, create and delete of a Custom Account Provider or manipulate the configuration before it is returned to The Identity Hub infrastructure.

class AccountProviderManager<T, U> : AccountProviderManagerBase, IAccountProviderManagerCache, IAccountProviderManager
                                        where T : AccountProviderConfiguration, new()
                                        where U : IAccountProvider, new()

class CustomAccountProviderManager : AccountProviderManager<CustomAccountProviderConfiguration, CustomAccountProvider>
Property or Method Description Override Required
System.Uri AccountProviderDefaultImageUrl The default image URL of this Claim Provider Yes
string AccountProviderDisplayName The displayname of this Account Provider Yes
bool AccountProviderImageConfigurable true if the image URL for this Account Provider can be changed Yes
bool AccountProviderIsUnique true if only one instance of the Account Provider can be created per Tenant Yes
U2UConsult.IdentityHub.Contracts.AccountProviders.AccountProviderProtocol AccountProviderProtocol The protocol used by this Account Provider. Use Custom when using a proprietary protocol Yes
System.Guid AccountProviderTypeId An System.Guid uniquely identifying the type of the Account Provider Yes
bool DisplayNameConfigurable true if the display name for this Account Provider can be changed Yes
U2UConsult.DemoAccountProvider.CustomAccountProviderConfiguration GetAccountProviderConfiguration(CustomAccountProviderConfiguration storedConfiguration) No
bool SupportsScimProvisioning true if The Identity Hub can enable a SCIM service provider for this account provider, allowing accounts to be provisioned using SCIM protocol Yes
string[] GetProvidedClaimTypes(IAccountProvider accountProvider) The claim types returned by this Claim Provider No
System.Xml.Linq.XElement UpdateAccountProviderConfigurationTenantUrlSegment(XElement configurationXml, string currentUrlSegment, string newUrlSegment) When the URL of the Tenant of this Account Provider changes, this method is called to allow updating the configuration of the Account Provider Yes
string[] ValidateCreateAccountProviderConfiguration(CustomAccountProviderConfiguration configuration, string tenantUrlSegment) To validate the configuration of a Account Provider before it is created. A string array of validation errors can be returned. Return an empty array when there are no validation errors. No
string[] ValidateDeleteAccountProviderConfiguration(CustomAccountProviderConfiguration configuration) To validate the configuration of a Account Provider before it is deleted. A string array of validation errors can be returned. Return an empty array when there are no validation errors No
string[] ValidateUpdateAccountProviderConfiguration(CustomAccountProviderConfiguration oldConfiguration, CustomAccountProviderConfiguration newConfiguration) To validate the configuration of a Account Provider before it is updated. A string array of validation errors can be returned. Return an empty array when there are no validation errors. No

CustomAccountProviderManagerFactory

Factory class to create new CustomAccountProviderManager instances.

[AccountProviderManagerFactory]
class CustomAccountProviderManagerFactory : IAccountProviderManagerFactory
Method Description Override Required
IAccountProviderManager GetAccountProviderManager() The methods need to return an instance of the Account Provider Manager Yes

You can use this class to instantiate and configure the Account Provider Manager.

CustomAccountProviderSignInViewModel & SignIn.cshtml

This is a specific model and view for the example Custom Account Provider. This might not apply to every Custom Account Provider. If the Custom Account Provider redirects the user to an external site for authentication no local model and view is needed.

CookieManager

Helper class for cookies for this example Custom Account Provider

Step 3: Install the Custom Account Provider

Installing a Custom Account Provider is a simple copy and paste operation.

  1. In the root folder of The Identity Hub web site create the following folder structure
Customizations
              \Extensions
                         \AccountProviders
  1. Copy the U2UConsult.DemoAccountProvider.dll in the AccountProviders folder
  2. If your account provider has a custom controller (eg CustomAccountProviderController ) with a view SignIn.cshtml: copy the view to the folder named after the controller
Customizations
              \Views
                         \CustomAccountProvider
  1. Edit the web.config file and add an application setting UseOnPremiseCustomizations set to true.
  2. If your account provider has a custom controller: also add an application setting ShadowCopyCustomProviders set to true to the web.config.
  3. Recycle the IIS Application Pool so the Account Provider is picked up by The Identity Hub

See The Identity Hub Configuration

Step 4: Activate the Custom Account Provider

  1. Navigate to the URL of your The Identity Hub installation and sign in as Hub or Tenant Admin.
  2. In the left navigation click Account Providers.
  3. Click on Add
  4. You will have to supply the common configuration parameters.
  5. Click Save. You will navigate to the list of Account Providers where the activated Account Provider will be listed.

Activate an Account Provider

Custom Claim Providers

Custom SMS Providers

The Identity Hub Configuration