Configure OOB Delivery Gateways

Out-of-band (OOB) delivery gateways and adapters ensures that notifications are sent to the users mobile devices.

ActivID AS supports various types of OOB Delivery Gateways:

• External servers that deliver SMS messages and passwords. For example, it can be a mail server or an SMS server:
  • SMS/Email OTPs can be used through a RADIUS channel or any other channel type
  • SMS/Email OTPs can be triggered through a username/activation code or by the service provider

    The actual SMS/Email OTP is a random number generated by ActivID AS and sent to the end user by SMS or Email through a delivery gateway.

    Multiple SMS and/or Email Delivery Gateways can be configured. If the primary gateway fails or there is no delivery address for the primary channel, then a secondary gateway is used automatically.

    Several Gateways can be defined and applicable for a given Authentication Policy, in a given priority order. If a gateway is not operational, then the next one will be used, following the priority order. This priority order is set in the authentication policy.

• Services that push notifications from servers to applications on devices. Such services are available for Android, Apple and Windows devices using:

  • Google Cloud Messaging for Android
  • Apple Push Notification Service for Android
  • Push Notification Service for Windows

Create an OOB Delivery Gateway

1. Log on to the ActivID Management Console as an ActivID Administrator.
2. Select the Configuration tab and, under Environment, select OOB Delivery Gateway.



3. Click Add.

1. Enter the main information for the gateway:
   • Name – should be unique for ease of administration.
   • Description – (optional) content is free-format.

2. From the drop-down list, select the Delivery Provider to define the notification service adapter settings and click Next:

Azure WNS Push Delivery adapter

Adapter for Microsoft notification services for push-based authentication for Microsoft Windows 10 devices.

Setting	Description
Azure connection string Required	URL of Microsoft Azure Notification Hub dedicated to your deployment. This URL includes the Notification Hub host. Contact HID Global Customer Services to request an Azure connection String for your deployment.
Hub Path Required	Name of Microsoft Azure Notification Hub. Contact HID Global Customer Services to request this value.
Notifications time to live (seconds)	Number of seconds (TTL or lifespan) during which the push notifications are valid and can be delivered. By default, the value is 0 which corresponds to the WNS default behavior (notification does not expire). If you set a time limit, repeated delivery attempts are made (as required) until the defined limit is reached. For further information, go to https://docs.microsoft.com/en-us/previous-versions/windows/apps/hh465435(v=win.10)
Supported OS List (use | as separator) Required	ID used to automatically select the Delivery Gateway for sending the push request message. It is recommended that you only enter WINDOWS in this field, instead of a list of versions. Important: This field is mandatory and case-sensitive (that is, you must use WINDOWS). If this parameter is set to WINDOWS, then this adapter will be selected to send push notifications to all Windows 10 devices. Note: If different applications are running on the same operating system, you can define a specific delivery gateway per application. You should then use a different authentication policy for each application, and map the corresponding delivery gateway to each policy.
Content of Credential messages template Required	Content of the message sent to the user's device to prompt for service activation By default, it is pre-populated with: {"data":{"alert":{"title": "Activation","msg":"Touch to activate"},"prov":"{$secret}"}}
Content of Challenge messages template Required	Content of the message sent to the user's device to prompt for validation By default, it is pre-populated with: {"data":{"alert":{"title": "New Transaction","msg":"Validate transaction"},"tds":"{$secret}"}}

Note:  

• The proxy parameters are deprecated and should not be used. If necessary, configure a forward proxy.
• Credential messages template – is not used in this version.
• Challenge messages template − structure of the notification must be kept but the following text items can be customized and localized (see Logon/Validation Request Display Message Format):
  • "New Transaction"
  • "Validate transaction"
• Due to a JSON limitation, the apostrophe character (‘) is not supported in the message. For example, “Bank New Transaction” is supported but “Banks’s New Transaction” will fail.

Azure Gcm Push Delivery adapter

Adapter for Microsoft notification services for push-based authentication for Google Android devices.

Setting	Description
Azure connection string Required	URL of Microsoft Azure Notification Hub dedicated to your deployment. This URL includes the Notification Hub host. Contact HID Global Customer Services to request an Azure connection String for your deployment.
Hub Path Required	Name of Microsoft Azure Notification Hub. Contact HID Global Customer Services to request this value.
Notifications time to live (seconds)	Number of seconds (TTL or lifespan) during which the push notifications are valid and can be delivered. By default, the value is 0 which corresponds to the GCM maximum validity of four (4) weeks. If you set a time limit, repeated delivery attempts are made (as required) until the defined limit is reached. For further information, go to https://firebase.google.com/docs/cloud-messaging/http-server-ref
Supported OS List (use | as separator) Required	ID used to automatically select the Delivery Gateway for sending the push request message. It is recommended that you only enter ANDROID in this field, instead of a list of versions. Important: This field is mandatory and case-sensitive (that is, you must use ANDROID). If this parameter is set to ANDROID, then this adapter will be selected to send push notifications to all Android devices. Note: If different applications are running on the same operating system, you can define a specific delivery gateway per application. You should then use a different authentication policy for each application, and map the corresponding delivery gateway to each policy.
Content of Credential messages template Required	Content of the message sent to the user's device to prompt for service activation By default, it is pre-populated with: {"data":{"alert":{"title": "Activation","msg":"Touch to activate"},"prov":"{$secret}"}}
Content of Challenge messages template Required	Content of the message sent to the user's device to prompt for validation By default, it is pre-populated with: {"data":{"alert":{"title": "New Transaction","msg":"Validate transaction"},"tds":"{$secret}"}}

Note:  

• The proxy parameters are deprecated and should not be used. If necessary, configure a forward proxy.
• Credential messages template – is not used in this version.
• Challenge messages template − structure of the notification must be kept but the following text items can be customized and localized (see Logon/Validation Request Display Message Format):
  • "New Transaction"
  • "Validate transaction"
• Due to a JSON limitation, the apostrophe character (‘) is not supported in the message. For example, “Bank New Transaction” is supported but “Banks’s New Transaction” will fail.

CIBA Callback Delivery Adapter

Adapter for notifications services for push-based feedback via CIBA callback.

Setting	Description
HTTP client connection timeout (seconds)	Number of seconds for which the connection to the HTTP client is valid By default, this is 60 seconds
Test CallBack URL	URL to use for the asynchronous HTTP callback in the following format: <listener_host>:<port>/<MyRegistrationCallback> For example, https://MylistenerHost:8080/RegistrationListener/CB/status
Test Message	Content of the test message. By default, this is testmessage
Supported message type Required	Type of messages supported by the gateway By default, this is CIBA
Content of Credential messages template Required	Internal use only. Important: Do NOT modify the parameter. By default, it is pre-populated with: MESSAGE={$secret}
Content of Challenge messages template Required	Internal use only. Important: Do NOT modify the parameter. By default, it is pre-populated with: MESSAGE={$secret}

Azure Apns Push Delivery adapter

Adapter for Microsoft notification services for push-based authentication for Apple iOS and macOS devices.

Setting	Description
Azure connection string Required	URL of Microsoft Azure Notification Hub dedicated to your deployment. This URL includes the Notification Hub host. Contact HID Global Customer Services to request an Azure connection String for your deployment.
Hub Path Required	Name of Microsoft Azure Notification Hub. Contact HID Global Customer Services to request this value.
Notifications time to live (seconds)	Number of seconds (TTL or lifespan) during which the push notifications are valid and can be delivered. By default, the value is 0 which corresponds to the APNS default behavior (only one delivery attempt is made). If you set a time limit, repeated delivery attempts are made (as required) until the defined limit is reached. For further information, go to https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns/
Supported OS List (use | as separator) Required	ID used to automatically select the Delivery Gateway for sending the push request message. Supported values are: iOS macOS To add support for both systems, use | to separate the values (that is, iOS|macOS). Important: It is recommended that you only enter the OS value(s) in this field, instead of a list of versions. This field is mandatory and case-sensitive (that is, you must use iOS and/or macOS). This adapter will be selected to send push notifications to all devices of the specified OS. Note: If different applications are running on the same operating system, you can define a specific delivery gateway per application. You should then use a different authentication policy for each application, and map the corresponding delivery gateway to each policy.
Content of Credential messages template Required	Content of the message sent to the user's device to prompt for service activation By default, it is pre-populated with: {"aps":{"alert":"Activation"},"prov":"{$secret}"}
Content of Challenge messages template Required	Content of the message sent to the user's device to prompt for validation By default, it is pre-populated with: {"aps":{"alert":"New Transaction"},"tds":"{$secret}"}

Note:  

• The proxy parameters are deprecated and should not be used. If necessary, configure a forward proxy.
• Credential messages template – is not used in this version.
• Challenge messages template − structure of the notification must be kept but the following text items can be customized and localized (see Logon/Validation Request Display Message Format):
  • "New Transaction"
  • "Validate transaction"
• Due to a JSON limitation, the apostrophe character (‘) is not supported in the message. For example, “Bank New Transaction” is supported but “Banks’s New Transaction” will fail.

 

SMS SMPP Delivery Provider

Short Message Peer-to-Peer (SMPP) protocol is a telecommunications industry protocol for exchanging SMS messages between SMS peer entities such as short message service centers and/or External Short Messaging Entities. It is often used to allow third parties (for example, value-added service providers like news organizations) to submit messages, often in bulk.

Setting	Description
SMPP hostname Required	Hostname or IP address of the SMPP provider
SMPP port Required	Port number of the SMPP provider For a connection via TLS, this must be the TLS port provided by SMS server
SMSC system ID Required	ID of the SMS Center
Password for SMSC server Required	Password of the SMS Center
Source TON	Obtain this value from your SMPP provider
Source NPI	Obtain this value from your SMPP provider
System type	Obtain this value from your SMPP provider
Source ID	It represents the Source Sender ID, which is the “from” address that appears on the user’s handset. This is also known as the message originator or source address. A Sender ID must be registered within your account and approved before it can be used. Obtain this value from your SMPP provider
Destination TON	Obtain this value from your SMPP provider
Destination NPI	Obtain this value from your SMPP provider
ESME address range	Obtain this value from your SMPP provider
User Attribute to store the phone number Required	User attribute for the phone number of the user registered
Test Connection phone number	Phone number to test the connection
SMS encoding (GSM7,Latin1,UCS2)	Encoding format for the SMS messages By default, this is GSM7
Use SSL Connection Required	For a connection via TLS, this must be set to true. Note: You must also import the SMPP server’s root CA certificate into the ActivID AS server’s trust store if it is not trusted by the default installation. Default value is false.
Content of Credential messages template Required	Content of the messages that are used to send the OOB and the credential By default, it is pre-populated with credential-email For additional guidelines, see About the Content of the Message Templates.
Content of Challenge messages template Required	Content of the messages that are used to send the OOB and the challenge By default, it is pre-populated with challenge-email For additional guidelines, see About the Content of the Message Templates.

SMTP Email Delivery Provider

Simple Mail Transfer Protocol (SMTP) is an Internet standard for electronic mail (e-mail) transmission across Internet Protocol (IP) networks.

Setting	Description
Email server Required	IP address of the mail server
Port Required	Port number of the mail server
Login name for SMTP server	Username to log on to the SMTP server
Password for SMTP server	Password for the account to log on to the SMTP server
Use secure connection (no/tls/ssl) Required	Connection type used for sending the email Possible values: no (default) tls ssl
E-mail address of the sender Required	A valid email address of the sender For example, john.smith@yourdomain.com or, if you want to specify the sender's friendly name, john.smith@yourdomain.com John Smith
E-mail subject Required	The subject of the email
User Attribute that stores the email address of the recipient	ActivID AS User Attribute used to store the user's email address By default, this is ATR_EMAIL
The User Attribute that stores the email address of the CC	ActivID AS User Attribute used to store the user's CC email address You must use a different user attribute than the one used for the email address of the recipient and the BCC
The User Attribute that stores the email address of the BCC	ActivID AS User Attribute used to store the user's BCC email address You must use a different user attribute than the one used for the email address of the recipient and the CC
Use html format for Credential messages (no/yes)	Defines if the Credential messages are sent in the HTML format Possible values: yes no (default, the messages are sent in the plain text format)
Use html format for Challenge messages (no/yes)	Defines if the Challenge messages are sent in the HTML format Possible values: yes no (default, the messages are sent in the plain text format)
Content of Credential messages template Required	Content of the messages that are used to send the OOB and the credential By default, it is pre-populated with credential-email For additional guidelines, see About the Content of the Message Templates.
Content of Challenge messages template Required	Content of the messages that are used to send the OOB and the challenge By default, it is pre-populated with challenge-email For additional guidelines, see About the Content of the Message Templates.

About the Content of the Message Templates

Message templates are a set of properties allowing to define messages in multiple languages.

Template properties:

• MESSAGE[_<locale>] - if the locale is not specified, the default is used (that is, en_US)
• SUBJECT[_<locale>] - optionally for email messages, you can include an email subject and define the locale

  If it is not specified in the template, the email delivery gateway subject will be used.

The MESSAGE and SUBJECT properties can both be parametrized with variables that will be resolved when sending the message.

Template variables must use the {$variable[, type, style]} format and can be:

• Predefined variables:
  • secret - the secret code to send
  • usercode - the username
  • temp_pwd_validity_period - the reset password temporary pass code validity period in miliseconds
  • temp_pwd_expiry_date - the reset password temporary pass code expiry date
  • now - the current date
• User attributes
• Authentication request parameters

For further information about the supported types and styles, go to https://docs.oracle.com/javase/8/docs/api/java/text/MessageFormat.html and https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html

Guidelines:

• There is no limitation on the length of the message in ActivID AS.

  However, modern networks limit a single SMS message to 160 characters.

• Special characters are supported.

  However, ActivID AS applies GSM encoding for SMS messages (by default, GSM-7) which might result in limitations depending on the encoding system.

• The date style is extended to optionally specify a timezone (default time zone is GMT).

For example, {$now, date, dd/M/yyyy hh:mm:ss [Europe/Paris]}

• The duration style can be used to format a duration expressed in milliseconds (ms) where the y/M/d/H/m/s/S element format corresponds to years/months/days/hours/minutes/seconds/milliseconds.

For example, with a validity_period of 139801000 ms:

MESSAGE=Your temporary password is only valid for {$validity_period, duration ,  m 'Minutes' }.

Displayed message – Your temporary password is only valid for 2330 minutes.

MESSAGE=Your temporary password is only valid for {$validity_period, duration ,  d 'Days' H 'Hours' m 'Minutes' s 'Seconds'}.

Displayed message – Your temporary password is only valid for 1 Days 14 Hours 50 Minutes 1 Seconds.

• Single quotes should be escaped using a single quote.

For example, It can't be changed must be replaced by It can''t be changed.

• Curly brackets should be enclosed with single quotes.

For example, { or } should be escaped must be replaced by '{' or '}' should be escaped.

• To add a new line, use \r\n. Do not use carriage returns as the message validation will fail.

Example of an email template - text/plain:

MESSAGE=Hello,\r\nYou requested a password reset for ActivID AS. Your temporary password is {$secret}. Your temporary password is only valid for {$temp_pwd_validity_period, duration , d 'Days' H 'Hours' m 'Minutes'}.\r\nPlease enter the temporary password at the reset screen, to set your permanent password.\r\nIf you did not request a password reset, please ignore this email.\r\n\r\nThank you.\r\n\r\nSystem Administration\r\nHID Global\r\n\r\nPlease do not reply to this message.\r\n©{$now, date, yyyy} HID Global Corporation/ASSA ABLOY AB

SUBJECT=ActivID AS – Password Reset

Example of an email template - text/plain in French (fr):

MESSAGE_fr=Bonjour,\r\nVous avez demandé à changer le mot de passe de votre compte ActivID AS. Votre mot de passe temporaire est {$secret}. Ce mot de passe expirera le {$temp_pwd_validity_period, duration , m 'Minutes'}.\r\nEntrez ce mot de passe temporaire pour pouvoir changer de mot de passe.\r\nSi vous n'’avez pas demandé à changer votre mot de passe, ignorez ce message.r\n\r\nMerci.\r\n\r\nAdministration Système\r\nHID Global\r\n\r\nMerci de ne pas répondre à ce message.\r\n©{$now, date, yyyy} HID Global Corporation/ASSA ABLOY AB

SUBJECT_fr=ActivID AS – Changement de mot de passe

Example of an email template - text/HTML:

MESSAGE=Hello,<br>You requested a password reset for the ActivID AS. Your temporary password is <b>{$secret}</b>. Your temporary password is only valid for {$temp_pwd_validity_period, duration , d 'Days' H 'Hours' m 'Minutes'}.<br>Please enter the temporary password at the reset screen, to set your permanent password.<br>If you did not request a password reset, please ignore this email.<br><br>Thank you.<br><br>System Administration<br>HID Global<br><br>Please do not reply to this message.<br>&copy;{$now, date, yyyy} HID Global Corporation/ASSA ABLOY AB

SUBJECT=ActivID AS – Password Reset

5. Click Save and proceed to Add an OOB Delivery Gateway to SMS Authentication Policy.

Add an OOB Delivery Gateway to SMS Authentication Policy

After creating an OOB delivery gateway, you must add an OOB delivery gateway to an OOB authentication policy and set a specific channel for the delivery.

Register User and OOB Credentials

Once the gateway is assigned to the authentication policy, you can register a user for OOB authentication.