Web-based SMS subscription

Subscription, and unsubscription, to SMS notifications can be performed by making HTTP GET requests to the subscribe SMS servlet. The subscribe SMS servlet can be used for SMS subscriptions without the requirement for a user to have an app installed on their device.

Enter the following URL to access the subscribe SMS servlet:

http://<hostname>:<port>/<context>/subscribeSMS

This URL can be used to subscribe and unsubscribe.

You must create an application and an event source within an adapter and deploy them on the IBM MobileFirst™ Platform Server before you make calls to the subscribe SMS servlet. For more information about how to create an event source, see the createEventSource method in the WL.Server class.

Table 1. Subscribe SMS servlet URL parameters
URL parameter	URL parameter description
option	Optional string. Subscribe or unsubscribe action to perform. The default option is `subscribe`. If any non-blank string other than `subscribe` is supplied, the unsubscribe action is performed.
eventSource	Mandatory string. The name of the event source. The event source name is in the format `AdapterName.EventSourceName`.
alias	Optional string. A short ID defining the event source during subscription. This ID is the same ID as provided in WL.Client.Push.subscribeSMS.
phoneNumber	Mandatory string. User phone number to which SMS notifications are sent. The phone number can contain digits (0-9), plus sign (+), minus sign (-), and space (␣) characters only.
userName	Optional string. Name of the user. If no user name is provided during subscription, an anonymous subscription is created by using the phone number as the user name. If a user name is provided during subscription, it must also be provided during unsubscription.
appId	Mandatory string for subscribe. The ID of the application that contains the SMS gateway definition. The application ID is constructed from the application name, application environment, and application version. For example, version 1.0 of Android application SMSPushApp has appId = SMSPushApp-android-1.0.

Note: If any parameter value contains special characters, this parameter must be encoded by using URL encoding, also known as percent encoding, before the URL is constructed. Parameter values containing only the following characters do not need to be encoded:

a-z, A-Z, 0-9, period (.), plus sign (+), minus sign (-), and underscore (_)

Subscriptions that are created by using the subscribe SMS servlet are independent of subscriptions that are created by using a device. For example, it is possible to have two subscriptions for the same phone number and user name; one created by using the device and one created by using the subscribe SMS servlet. If there are two subscriptions for the same phone number and user name, unsubscription by using the subscribe SMS servlet unsubscribes only the subscription that is made through the subscribe SMS servlet. However, unsubscription by using the IBM MobileFirst Platform Operations Console unsubscribes both subscriptions.

Security

It is important to secure the subscribe SMS servlet because it is possible for entities with malicious intent to call the servlet and create spurious subscriptions. By default,IBM MobileFirst Platform Foundation protects static resources such as the subscribe SMS servlet. The authenticationConfig.xml file is configured to reject all requests to the subscribe SMS servlet with a rejecting login module. To allow restricted access to the subscribe SMS servlet, MobileFirst administrators must modify the authenticationConfig.xml file with appropriate authenticator and login modules.

For example, the following configuration in the authenticationConfig.xml file ensures only requests with a specific user name in the header of the HTTP request are allowed:

  <staticResources>
    <resource id="subscribeServlet" securityTest="SubscribeServlet">
	    <urlPatterns>/subscribeSMS*</urlPatterns>
    </resource>
    ...  
  </staticResources> 
  
  <securityTests>
    <customSecurityTest name="SubscribeServlet">
      <test realm="SubscribeServlet" isInternalUserID="true"/>
    </customSecurityTest>        
    ...
  </securityTests> 
  
  <realms>
    <realm name="SubscribeServlet" loginModule="headerLogin">
      <className>com.worklight.core.auth.ext.HeaderAuthenticator</className>  
    </realm>
    ...  
  </realms>

  <loginModules>
    <loginModule name="headerLogin">
      <className>com.worklight.core.auth.ext.HeaderLoginModule</className>
      <parameter name="user-name-header" value="username"/>  
    </loginModule>
    ...  
  </loginModules>