How do I set up the HOTP Authentication module for SMS in AM (All versions)?

Background information

Custom Attributes

Custom attributes are required in your LDAP directory server for the following purposes:

• Mobile Phone Number - this attribute will store the user's mobile phone number. The default attribute is telephoneNumber, which already exists in the embedded DS.
• Mobile Carrier - this attribute will store the carrier domain associated with the user's mobile phone number. For example, carrierName.

The HOTP service picks up the mobile phone number and carrier from these custom attributes, it then concatenates them into an email address, passes this to the SMS gateway, which sends the email. For example, if you have:

The resulting email address used by the SMS gateway for User1 is: 14151234567@vtext.com

If a Mobile Carrier attribute name is not specified, the default @txt.att.net carrier domain is used when forming the email address. Alternatively, you may specify the carrier domain as part of the user's mobile phone number, for example: 14151234567@vtext.com; in which case this will be used as the email address. However, this means the user's mobile phone number may not be useful for other purposes.

AM doesn't perform any processing on the phone number itself as part of the default SMS gateway implementation (com.sun.identity.authentication.modules.hotp.DefaultSMSGatewayImpl). Therefore, you should ensure you use the correct format for your mobile phone numbers as determined by your carrier/SMS gateway service. Typically this will mean removing any spaces or dashes from mobile phone numbers as these will result in an invalid email address.

Load balancer

If you have set up a site with a load balancer in front of it, you must ensure that the load balancer uses the amlbcookie for stickiness to correctly route user sessions. The AM server sending the HOTP response code must be the same one that the request came from since the HOTP Authentication module stores its current response codes in the server's cache. Failing to route correctly will result in the following error in the browser when the HOTP response code is submitted:

Authentication chain

The HOTP Auth module must be added as the second required module in the authentication chain. The first required authentication module in the authentication chain must be a module that stores the user's username attribute, such as the Data Store module. For example, your resulting authentication chain would look like this:

Session upgrades

You can utilize session upgrades (the sessionUpgradeSSOTokenId parameter) to allow the HOTP authentication module to work on its own in a separate authentication chain.

When the following flow is used with XUI, the sessionUpgradeSSOTokenId parameter is automatically added to the request:

1. Configure an authentication chain with one DataStore module (called DS in this example).
2. Configure an authentication chain with one HOTP module (called OTP in this example).
3. Authenticate to AM with ?service=DS.
4. Enter the correct credentials and receive a token.
5. Authenticate to AM with ?service=OTP.

See Session upgrade for further information on session upgrades.

Configuring the HOTP module for SMS

You can configure the HOTP Authentication module as follows for SMS:

1. Create the two custom attributes (Mobile Phone Number and Mobile Carrier) in your directory server:
   • If you use an external DS, see Update LDAP schema for further information.
   • If you use the embedded DS, see Add custom user profile attributes for further information.
2. Update your user profiles to add and populate these custom attributes, for example, using the ldapmodify command. Only users who have a valid mobile phone number will receive a text message containing the one-time passcode.
3. Update the data store configuration in AM to add the new custom class and custom attributes by navigating to: Realms > [Realm Name] > Data Stores > [Data Store Name] > User Configuration and update the LDAP User Object Class and LDAP User Attributes fields.
4. Update the HOTP authentication module in your realm for SMS by navigating to: Realms > [Realm Name] > Authentication > Modules > HOTP in the admin UI. See HOTP authentication module for further information on the fields you can configure for the HOTP module. In particular, you should ensure the following fields are completed correctly:
   • Mobile Phone Number Attribute Name - enter the name of the custom attribute that contains the user's phone number.
   • Mobile Carrier Attribute Name - enter the name of the custom attribute that contains the mobile carrier associated with the user's phone number. This must not be the carrier domain itself.
   • All Mail Server fields - you need to configure the SMTP details correctly since the SMS goes through a SMTP service.
5. Add the HOTP module to an authentication chain by navigating to: Realms > [Realm Name] > Authentication > Chains > [Chain Name] in the admin UI and add the HOTP module as a required module; it should be the second required module.

Testing your configuration

You can test this with a free trial from a service such as: TextMagic and AM will send an email to [user's phone number]@textmagic.com, which is then converted to SMS. You will need to create an account with TextMagic before you start.

For testing purposes, you should:

• Ensure the Mobile Carrier attribute is set to @textmagic.com for the user you want to test with.
• Specify the user name you have in the Mail Server Authentication Username field as an Allowed Email in TextMagic (Services > Email to SMS).

See How to set up Email to SMS for further information on setting up email for SMS in TextMagic.

See Also

FAQ: Upgrading AM

Multi-factor authentication

Configure authentication chains

Customize before upgrading

Related Training

N/A

Related Issue Tracker IDs

N/A