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
- Open the project in Visual Studio 2017 or higher.
- 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.
- In the root folder of The Identity Hub web site create the following folder structure
Customizations
\Extensions
\ServiceProviders
Customizations
\Views
\CustomSmsProvider
- Copy the U2UConsult.DemoSmsProvider.dll in the ServiceProviders folder
- Copy the Detail.cshtml and Edit.cshtml in the CustomSmsProvider folder
- 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
- add an application setting
- Recycle the IIS Application Pool so the Account Provider is picked up by The Identity Hub
Step 4: Activate the Custom Sms Provider
- Navigate to the URL of your The Identity Hub installation and sign in as Hub or Tenant Admin.
- In the left navigation click Services.
- Click on Configure Sms Provider
- Click on the icon of your Custom Sms Provider
- You will have to supply the configuration parameters.
- Click Save.