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
Clickatell
SMS Global
Sybase 365
Comunika (Brazil)
IssueConfiguring On-Demand over HTTP
OnDemand
On-Demand
Cause

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.

Resolution

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:


http://api.clickatell.com/http/sendmsg?api_id=xxxx&user=xxxx&password=xxxx&to=xxxx&text=xxxx


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


http://api.clickatell.com/http/sendmsg?api_id=34263542&user=rsademouser&password=mypass&to=61417555111&text=hello


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


Parameters


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:


https://api.clickatell.com/http/sendmsg?api_id=34263542&user=rsademouser&password=mypass&to=61417555111&text=hello


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:


https://www.smsglobal.com/http-api.php?action=sendsms&user=USERNAME&password=PASSWORD&from=FROMNUMBER&to=TONUMBER&text=Hello%20World


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:


https://www.smsglobal.com/http-api.php?action=sendsms&user=rsademouser&password=mypass&from=RSA&to=61417555123&text=Hello%20World


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'>


<Identification>


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


<Password>Mypass01</Password>


</Identification>


<Service>


<ServiceName>SendMessage</ServiceName>


<ServiceDetail>


<CombiMessage>


<CombiList>


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


</CombiList>


<Text>Test message</Text>


</CombiMessage>


</ServiceDetail>


</Service>


</Request>


 


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">


<Error>


<ErrorCode>00</ErrorCode>


<ErrorReason>OK</ErrorReason>


</Error>


<ResponseData>


<Identification>


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


</Identification>


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


<Detail>


<MessagesSent>1</MessagesSent>


<CreditsRemaining>9.0</CreditsRemaining>


<OffPeakCreditsRemaining>0.0</OffPeakCreditsRemaining>


</Detail>


</ResponseData>


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


<Batches>


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


</Batches>


</OutputData>


</Response>


 


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">


<Error>


<ErrorCode>03</ErrorCode>


<ErrorReason>Invalid account details</ErrorReason>


</Error>


</Response>


 


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'>


<Identification>


<UserID>$cfg.user</UserID>


<Password>$cfg.password</Password>


</Identification>


<Service>


<ServiceName>SendMessage</ServiceName>


<ServiceDetail>


<CombiMessage>


<CombiList>


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


</CombiList>


<Text>$msg.message</Text>


</CombiMessage>


</ServiceDetail>


</Service>


</Request>


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         :
rsademouser@rsa.com
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:


http://www.mollie.nl/xml/sms/?username=rsademouser&password=mypass&originator=originator&recipients=61471330244&message=test


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:


 

Redcoal


TBA (API obtained and account not yet created)


 

www.smsbroadcast.com.au


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:


 http://apac.soprano.com.au/cgphttp/servlet/sendmsg?destination=61471244220&text=hello


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:



result=true


requestID=Q1134DCCE04567



A failure looks like:



result=true


requestID=Q1134DCCE04567


error_code=2nnnnnn



 


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

Attachments

    Outcomes