Configure the HTTP Plug-In for On-Demand Tokencode Delivery

You can configure a deployment to integrate with Short Message Service (SMS) providers or modems using HTTP, HTTPS, or XML-over-HTTP to deliver on-demand tokencodes to a user’s mobile phone.

The HTTP request communicates the following delivery information to your SMS provider or modem:

  • The text message, which includes the on-demand tokencode

  • The mobile phone number

  • Any other information required by your SMS provider or modem

The maximum length of the text message is 140 bytes and the number of characters depends on the type of character encoding used by the SMS provider. The full payload of 140 bytes can support 160 7-bit characters, 140 8-bit characters, or 70 16-bit characters. The $OTT and $Lifetime variables are replaced with the actual values, which uses some of the available characters.

Note: HTTP connections are not secure. Sensitive information, such as a tokencode, may be exposed. For secure connections, configure HTTPS.

Before you begin

  • Each supported SMS provider has its own implementation guide with configuration values and parameters. To download the implementation guide for your SMS provider, go to https://community.rsa.com/community/products/rsa-ready/, enter the name of your SMS provider in the search field, and open the SMS provider's page.

  • If your SMS provider requires digital certificates or if HTTP connections are redirected to an HTTPS site, secure the certificate from your provider and save it locally. Importing the certificate enables Authentication Manager to validate the server to which the on-demand tokencodes are sent. Authentication Manger accepts all connections signed by this certificate. For instructions, see Import a Digital Certificate.

  • Make sure that all users’ destination mobile phone numbers meet the following requirements:

    • The mobile phone numbers must include country codes. If they are not already stored with country codes, select a country code when you configure on-demand tokencode delivery to mobile phones.

    • End the mobile phone number with a number.

    • The mobile phone number may begin with the plus (+) character.

    • Use the following characters or a blank space for separators: . - ( ).

    • Do not use alphabetic characters or any other characters not mentioned in this list.

    The following are examples of valid destination mobile phone numbers:

    +1 123 123 1234

    +44 1234-123-123-1

    123 123

    123.123.1234

    (123) 123-1234

Procedure

  1. In the Security Console, click Setup > System Settings.

  2. Under Authentication Settings, click On-Demand Tokencode Delivery.

  3. Click the SMS Configuration tab.

  4. Under Tokencode Delivery by SMS, do the following:

    1. Select Enable the delivery of on-demand tokencodes using SMS service.

    2. From the User Attribute to Provide SMS Destination drop-down menu, select the user attribute that provides the mobile phone numbers used to deliver on-demand tokencodes to users.

      If you use the internal database for user information, you can map to an attribute there, such as telephone number, or create a custom attribute. If you use an external identity source, you can choose an attribute that is mapped to an attribute in the external identity source (for example, telephone number).

    3. From the Default country code drop-down menu, select a country code to prepend to the destination mobile phone numbers.

      Country codes are required for all on-demand tokencode destination mobile phone numbers. Select a country code only when the mobile phone numbers to which you send on-demand tokencodes are not already stored with country codes.

    4. From the SMS Plug-In drop-down menu, select HTTP.

    5. If you have enabled this feature, you can select the Add Delivery by E-mail checkbox to deliver tokencodes by both SMS and e-mail.

      E-mail delivery requires a configured e-mail (SMTP) server and a user e-mail address if the user selects Mobile Number (SMS) as the preferred option for on-demand authentication. See Configure the SMTP Mail Service and Configure E-mail for On-Demand Tokencode Delivery.

  5. Under SMS Provider Configuration, do the following:

    1. In the Base URL field, enter the base URL for your SMS provider or modem.

    2. Import a certificate when your SMS provider requires digital certificates or for when HTTP connections are redirected to an HTTPS site. For instructions, see Test Your SMS Provider Configuration.

      Note: If your SMS provider does not require digital certificate or the base URL does not use HTTPS, this step is not required.

    3. From the HTTP Method drop-down menu, select the method required by your SMS provider, and configure one of the following.

      • For GET or POST. Enter the parameters supplied by your SMS provider.

      • For XML. Enter the XML request body supplied by your SMS provider.

      Note: If your SMS provider uses XML-over-HTTP, select XML for the HTTP Method.

    4. In the Parameters field, enter the parameters required by Authentication Manager and your SMS provider or modem. For more information, see SMS HTTP Plug-In Configuration Parameters.

    5. In the Account User Name field, enter the user name for your SMS service provider account. This is provided by your service provider.

    6. In the Account Password field, enter the password for your SMS service provider account. This is provided by your service provider.

    7. In the Connection Timeout field, enter a connection time-out between 1,000 and 3,600,000 milliseconds. The default value is 5,000 milliseconds.

    8. In the Success Response Code field, enter the success response code required by your SMS provider.

    9. In the Response Format field, enter the success response format required by your SMS provider.

      Note: See your standard JDK documentation for more information on regular expressions.

  6. (Optional) Under SMS HTTP(S) Proxy Configuration, do the following:

    1. In the Proxy Hostname field, enter a hostname for your HTTP proxy.

    2. In the Proxy Port field, enter your proxy port number.

    3. In the Proxy User field, enter your proxy user name.

    4. In the Proxy Password field, enter your proxy password.

  7. (Optional) Under Test SMS Provider Integration, do the following:

    1. In the Mobile phone number to test fields, select a country code, and enter the number for mobile phone that receives the test message.

    2. Click Send Test Text Message.

      The system saves all of your changes before the test is conducted. If the connection is unsuccessful, you see an error message.

  8. On the Tokencode Settings tab, configure the following:

    1. In the On-Demand Tokencode Message field, enter the text that you want to display in the text message that contains the on-demand tokencode.

      You must leave the $OTT variable in the message. The on-demand tokencode is inserted in place of this variable.

    2. In the On-Demand Tokencode Lifetime field, enter the length of time that on-demand tokencodes are valid after they are delivered to the user.

  9. Click Save.

Related Concepts

On-Demand Authentication

Related Tasks

Configure On-Demand Tokencode Settings

Configure On-Demand Tokencode Delivery

Change the SMS Service Provider