000012124 - Configuring On-Demand over HTTP

Document created by RSA Customer Support Employee on Jun 14, 2016Last modified by RSA Customer Support Employee on Apr 21, 2017
Version 2Show Document
  • View in full screen mode

Article Content

Article Number000012124
Applies ToRSA Authentication Manager 7.1 SP4
RSA SecurID Appliance 3.0.4
SMS Global
Sybase 365
Comunika (Brazil)
IssueConfiguring On-Demand over HTTP

With the release of service pack 4 there is an updated option for transmitting SMS On-Demand tokencodes.  Prior to this service pack release the only shipping option was Clickatell and use of alternative providers or internal aggregators needed a custom plug-in supplied by RSA Professional Services.  Service pack 4 introduces an option for generic HTTP connections where the the parameters to make the connection are entered through the Security Console GUI

The GUI interface can be found in the Security Console under Setup>Component Configuration>Authentication Manager>On-Demand Tokencodes for users with the appropriate license but it may not be readily apparent how to enter the configuration parameters.


The first step should always be to refer to the documentation supplied by the SMS aggregator you are using, they will tell you how to send messages to them and you need to interpret and translate that information into the parameters in the RSA GUI.  The following sections demonstrate examples of connection to a variety of SMS aggregator services, in all the examples the connections are going direct from RSA Authentication Manager to the provider and are nto configured via a proxy. 

Some HTTP proxies (especially those which do SSL inspection may not be possible to configure as the security validation on Authentication Manager works to avoid the SMS message having any possibility of being decrypted between sending from Authentication Manager and reception by the SMS carrier. 


Clickatell over HTTP GET

As an example it would be possible to configure a connection to Clickatell via the generic HTTP interface instead of using the dedicated plug-in.  Obviously this is not ever required but serves to demonstrate the process.

The existing Clickatell interface used by RSA is an HTTP GET command and the Clickatell HTTP documentation says that the message should be sent in this format:


As an example, here is a line with some actual values:


This message could be pasted into a browser URL and would be expected to give a result back in the browser such as:

 ID: 9b1785fd4c130ce3f8ec66f0acacbf13

Or, if something was wrong you might get this:

ERR: 001, Authentication failed

From here, you can now map these details into the GUI for the HTTP configuration (remember that this is all just as a demonstration of how to use the interface and if you are using Clickatell then the dedicated configuration would be used).

The parameter options in the RSA GUI are as follows:

Base URL

Certificate Name

HTTP Method


Account User Name

Account Password

Connection Timeout

Success Response Code

Response Format


Using the Clickatell URL above as an example, here is how we would enter these values into the GUI

Base URL                        : http://api.clickatell.com/http/sendmsg

     Certificate Name                : <Leave blank for the moment>

HTTP Method             : GET

Parameters              : api_id=34263542&user=$cfg.user&password=$cfg.password&to=$msg.address&text=$msg.message

Account User Name       : rsademouser

Account Password        : mypass

Connection Timeout      : 5000

Success Response Code   : ID:

Response Format         : ID:


You should be able to enter these details (substituting the ?rsademouser?, ?mypass? and ?34263542? for your own Clickatell connection details.  At this point you can test the connection and confirm that you can send the RSA test message to a mobile phone.

For the Certificate Name you should go back to your browser and modify your test USL to HTTPS, for example:


When you connect using this you should be able to click on the padlock symbol on your browser (or equivalent symbol), view the certificates and save the root certificate to file.  The certificate required for the Clickatell connection is the ?Thawte Premium Server CA (SHA1)? certificate.  This would be saved as a file on your local computer and then uploaded using the Import Certificate button in the GUI and then the BASE URL value changed to read https://api.clickatell.com/http/sendmsg


SMS Global over HTTP GET

As a second example we might want to use the service from SMS Global (http://www.smsglobal.com). Again, this is an HTTP GET service and the format of the URL is this:


As before the first thing to do is to test this on a URL with your connection parameters that you have got for the service, for example:


This gives an on-screen result such as:

OK: 0; Sent queued message ID: 09f8922685e881e8 SMSGlobalMsgID:6773292666805107

And an example of a failed authentication:

ERROR: 402

These details can now be entered into the RSA GUI:

Base URL                        : https://www.smsglobal.com/http-api.php

Certificate Name                : <Leave blank for the moment ? see below>

HTTP Method             : GET

Parameters                      :action=sendsms&user=$cfg.user&password=$cfg.password&from=RSA&to=$msg.address&text=$msg.message

Account User Name       : rsademouser

Account Password                : mypass

Connection Timeout      : 5000

Success Response Code   : OK:

Response Format         : OK:


As with Clickatell we also need to load the SSL certificate and we do the same action:

?          Connect using a browser and send a test message using the URL such as https://www.smsglobal.com/http-api.php?action=sendsms&user=rsademouser&password=mypass&from=RSA&to=61417555123&text=Hello%20World

?          Download the root certificate and save as a file (in this case it is Equifax Secure Certificate Authority)

?          Import this certificate (and give it a name using the Import Certificate button


Sybase 365 over XML

A connection to Sybase 365 is an example of sending the On-Demand SMS message via XML.  Here an XML message is generated and sent to the Sybase 365 system.  It is not possible to demonstration of this is using a browser but you need to send an XML message via HTTP to http://www.2sms.com/xml/xml.jsp , here is an example the XML message:

<?xml version='1.0' encoding='UTF-8'?>

<Request xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='http://schema.2sms.com/2.0/schema/0410_RequestSendMessage.xsd' Version='1.0'>










<Individual type='sms'>61417555123</Individual>


<Text>Test message</Text>






When this is submitted correctly an XML message is returned in an XML response such as:

<?xml version="1.0" encoding="UTF-8"?>

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.2sms.com/2.0/schema/0410_ResponseSendMessage.xsd" Version="1.0">







<UserID>rsademouser@rsa.com </UserID>


<Result>1 message was sent. You have 9.0 credits, 0.0 off peak credits remaining</Result>







<OutputData individualSMS="1" groupSMS="0" individualEmails="0" groupEmails="0" peakCredits="0.0" offPeakCredits="0.0">


<Batch GUID="2011-01-10T21:12:07.173Z" DateID="1294693927173" />





A failure will get an XML message back such as this:

<?xml version="1.0" encoding="UTF-8"?>

<Response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="http://schema.2sms.com/2.0/schema/0000_ResponseGenericError.xsd" Version="1.0">



<ErrorReason>Invalid account details</ErrorReason>




These details can now be translated into the required parameters needed by the AM71 GUI:

Base URL                : https:// www.2sms.com/xml/xml.jsp

Certificate Name                : <Leave blank for the moment ? see below>

HTTP Method             : XML

Parameters              :              

<?xml version='1.0' encoding='UTF-8'?>

<Request xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='http://schema.2sms.com/2.0/schema/0410_RequestSendMessage.xsd' Version='1.0'>










<Individual type='sms'>$msg.address</Individual>







Account User Name       : rsademouser@rsa.com

Account Password                : Mypass01

Connection Timeout      : 5000

Success Response Code   :

Response Format         :


Test using just HTTP first and then when it is working switch to HTTPS by doing the following:

?          Connect using a browser to https:// www.2sms.com/xml/xml.jsp

?          Save the root certificate for the connection (VeriSign Class 3 Public Primary Certification Authority - G5)

?          Use the Import Certificate to import this certificate

?          Modify the base URL to use HTTPS instead of HTTP



Comunika(Brazil) CGI2SMS

This site (http://www.comunika.com.br) off a number of connection methods, this example demonstrates the CGI2SMS connection method.  Ensure that you have enrolled and have an account available and then fill in the details as follows:

Base URL                  : https://cgi2sms.com.br/3.0/user_message_send.php
Certificate Name          : << Load DER encoded USERTrust cert from https://cgi2sms.com.br >>
HTTP Method               : GET
Parameters                : user=$cfg.user&pass=$cfg.password&linesep=0&testmode=0&messages=AM71-Leonov%09$msg.address%09%09$msg.message%091
Account User Name         :
Account Password          : Mypass01
Connection Timeout        : 5000
Success Response Code     : 00
Response Format           : 00



Over Mollie B.V. (NL) using HTTP GET

This is a Dutch service and is another example where HTTP GET may be used.  The main details on their web site at https://www.mollie.nl/support/documentatie/sms-diensten/sms/http/en/ describe the connection to look like this:

 http://www.mollie.nl/xml/sms/?username=[username] &password=[password]&originator=[originator]&recipients=[recipient(s)]&message=[message]

And an example we could send a test from a browser using this URL:


This will give us an error message like this:

 0  false  31  Not enough credits to send message.

We now have enough to enter details into the RSA GUI:

Base URL                                : http://www.mollie.nl/xml/sms/

Certificate Name                 : <Leave blank for the moment ? see below>

HTTP Method                      : GET

Parameters                       :                               username=$cfg.user&password=$cfg.password&originator=0294638401&recipients=$msg.address&message=$msg.message

Account User Name                       : rsademouser

Account Password                 : mypass

Connection Timeout                      : 5000

Success Response Code           : OK:

Response Format                  : OK:


As with Clickatell we also need to load the SSL certificate and we do the same action:



TBA (API obtained and account not yet created)



TBA (but has been proven to work)


Soprano powered systems such as Telstra and AT&T

Test account configured directly into a Soprano test system

Soprano connects using a URL like this:


and in some systems HTTP basic auth mechanism prompts for username and password.

A successful response will look like this:

0 001 OK
Message-ID: 9657280

There may be an issue with the SP4 code which will not do an HTTP basic auth but Soprano has modified their external systems to work differently.

Where (internal) systems still need an HTTP basic auth then we may need to consider it as a but or alternatively we may be able to set this as a POST operation and supply the required parameter as an HTTP header value such as "Authorization: Basic bWF0dGhldy5ib25kQHJzZS5jb206cGFzc3dkMDE=  where the value is B64 encoding of username:password



PCCW SMS gateway (Hong Kong) has a registration page at http://www2.pccwmobile.com/portal/index.jsp 

The URL looks like this:  https://smsapi.pccmobile.com/service?username=rsademouser&password=mypass&number=61407123654*charset=ascii&sender=AM71&msg=hello

A success is a two line response like this:



A failure looks like:





This means that the regex expression needs to be inverse of most values and return a ?true? result if ?error_code? is not seen


Legacy Article IDa53514