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

Document created by RSA Information Design and Development on Jun 13, 2017Last modified by RSA Information Design and Development on Jun 13, 2017
Version 2Show Document
  • View in full screen mode

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 

  • Go to www.rsaready.com and click the Solutions Gallery link to download the implementation guide that contains configuration values and parameters for supported SMS providers and modems. Each SMS provider has its own implementation guide. You can search for providers by name or click Partner Product Categories > SMS. The implementation guide is listed on the page for each provider.

  • 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. 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.

 

 

 


Attachments

    Outcomes