Custom SMS Providers

Although The Identity Hub supports one out-of-the-box SMS Provider, you might need create a custom one when you want to use your existing mobile provider contract.

Create a Custom SMS Provider

Step 1: Copy the necessary assemblies

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

  • U2UConsult.dll
  • U2UConsult.IdentityHub.Common.dll
  • U2UConsult.IdentityHub.Contracts.dll
  • U2UConsult.IdentityHub.Data.dll
  • U2UConsult.IdentityHub.ServiceProvider.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-SMS-Provider

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

CustomSmsProvider

The entry point for calls from The Identity Hub infrastructure.

class CustomSmsProvider : SmsProviderBase
Property or Method Description Override Required
U2UConsult.IdentityHub.Contracts.SmsProviders.SmsProviderConfiguration ConfigurationSettings The configuation settings for the Sms Provider Yes
string Description The description of the Sms Provider Yes
string DisplayName The display name of the Sms Provider Yes
U2UConsult.IdentityHub.Contracts.SmsProviders.ISmsProviderManager SmsProvividerManager The Sms Provider Manager of the Sms Provider. Set by The Identity Hub infrastructure Yes
System.Guid SmsProviderTypeId A System.Guid uniquely identifying the type of the Sms Provider Yes
System.Threading.Tasks.Task<Uri> GetDetailUrlAsync(string tenant) Called by The Identity Hub infrastructure. Returns the URL where the configuration of the Sms Provider can be seen Yes
System.Threading.Tasks.Task<Uri> GetUpdateUrlAsync(string tenant) Called by The Identity Hub infrastructure. Return the URL where the configuration of the Sms Provider can be edited Yes
System.Threading.Tasks.Task<SendSmsResult> SendSms(string phoneNumber, string text) Called by The Identity Hub infrastructure when sending an sms. This method should send the sms.

Method System.Threading.Tasks.Task<Uri> GetDetailUrlAsync

Parameter Description
string tenant The tenant to return the configuration detail URL.
Note

When a Tenant is being managed as HUB Admin or HUB Tenant Admin the tenant parameter will always be of the hub Tenant
There is example code on how to get the actual Tenant.

Method System.Threading.Tasks.Task<Uri> GetProfileUrl

Parameter Description
string tenant The tenant to return the configuration edit URL.
Note

When a Tenant is being managed as HUB Admin or HUB Tenant Admin the tenant parameter will always be of the hub Tenant
There is example code on how to get the actual Tenant.

Method System.Threading.Tasks.Task<U2UConsult.IdentityHub.Contracts.SmsProviders.SendSmsResult> SendSms(string phoneNumber, string text)

Parameter Description
string phoneNumber The mobile phone number to send the sms to
string text The sms text to send

Method should send the sms and return a U2UConsult.IdentityHub.Contracts.SmsProviders.SendSmsResult to indicate success or failure.

CustomSmsProviderConfiguration

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

class CustomSmsProviderConfiguration : SmsProviderConfiguration

CustomSmsProviderManager

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

class SmsProviderManager<T, U> : DataServiceBase<IdentityHubDataContext>, ISmsProviderManager
        where T : SmsProviderConfiguration, new()
        where U : SmsProviderBase, new()
class CustomSmsProviderManager : SmsProviderManager<CustomSmsProviderConfiguration, CustomSmsProvider>
Property or Method Description Override Required
System.Uri SmsProviderDefaultImageUrl The default image URL of this Claim Provider Yes
string SmsProviderDisplayName The displayname of this Account Provider Yes
U2UConsult.IdentityHub.Contracts.SmsProviders.SmsProviderProtocol SmsProviderProtocol The protocol used by this Sms Provider. Use Custom when using a proprietary protocol Yes
System.Guid SmsProviderTypeId An System.Guid uniquely identifying the type of the Sms Provider Yes
string[] ValidateCreateSmsProviderConfiguration(CustomSmsProviderConfiguration configuration, string tenantUrlSegment) To validate the configuration of a Sms 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[] ValidateDeleteSmsProviderConfiguration(CustomSmsProviderConfiguration configuration) To validate the configuration of a Sms 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[] ValidateUpdateSmsProviderConfiguration(CustomSmsProviderConfiguration oldConfiguration, CustomSmsProviderConfiguration newConfiguration) To validate the configuration of a Sms 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

CustomSmsProviderManagerFactory

Factory class to create new CustomAccountProviderManager instances.

[SmsProviderManagerFactory]
class class CustomSmsProviderManagerFactory : ISmsProviderManagerFactory
Method Description Override Required
ISmsProviderManager GetSmsProviderManager() The methods need to return an instance of the Sms Provider Manager Yes

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

CustomSmsProviderController

The custom controller for the views to manage the configuration of the Sms Provider.

Note

There is example code on how to implement this.

Detail.cshtml & Edit.cshtml

These are specific views for the example Custom Sms Provider. These views will be loaded by The Identity Hub infrastructure.

Step 3: Install the Custom Sms Provider

Installing a Custom Sms 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
                         \ServiceProviders
Customizations
              \Views
                    \CustomSmsProvider
  1. Copy the U2UConsult.DemoSmsProvider.dll in the ServiceProviders folder
  2. Copy the Detail.cshtml and Edit.cshtml in the CustomSmsProvider folder
  3. Edit the web.config file (See The Identity Hub Configuration) and
    • add an application setting UseOnPremiseCustomizations set to true
    • add an application setting ShadowCopyCustomProviders set to true
  4. Recycle the IIS Application Pool so the Account Provider is picked up by The Identity Hub

Step 4: Activate the Custom Sms 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 Services.
  3. Click on Configure Sms Provider
  4. Click on the icon of your Custom Sms Provider
  5. You will have to supply the configuration parameters.
  6. Click Save.

Custom Account Providers

Custom Claim Providers

The Identity Hub Configuration