Login
    Contenu x
    Configuring SMS delivery (HTTP gateways)
    • 08 Jan 2025
    • 9 Minutes à lire
    • Sombre
      Lumière
    • PDF
    Contenu

    Configuring SMS delivery (HTTP gateways)

    • Mis à jour le 08 Jan 2025
    • 9 Minutes à lire
    • Sombre
      Lumière
    • PDF
    The content is currently unavailable in French. You are viewing the default English version.
    Résumé de l’article

    You can use the MDC Configuration Utility to configure an HTTP gateway for SMS delivery. The application allows you to import, export, or manually configure an HTTP gateway. For more information about importing or exporting gateway definitions, see Importing/exporting gateway definitions (Message Delivery Component). For more information about configuring SMPP gateways for SMS delivery, see Configuring SMS delivery (SMPP gateways).

    To configure an HTTP gateway connection for SMS delivery

    1. Start the MDC Configuration Utility.
    2. Switch to the SMS delivery tab.
    3. If the delivery method is not yet enabled, select the Enable SMS delivery checkbox.
    4. Click Add HTTP gateway. Type a display name and click OK.
    5. Select the profile you just created from the SMS gateways list.

    6. Configure the SMS gateway settings:

      1. Switch to the Gateway settings tab.

      2. Type the URL of the gateway. If the URL uses an https:// prefix, then it is TLS/SSL-enabled. In that case, click Browse and navigate to the certificate file to use.

        Certification authority (CA) files should be located on the same host as OneSpan Authentication Server. If your CA file is located on a network share, you need to copy the file locally before you browse to it and select it.

      3. Type the port on which the gateway should be listening.

      4. Configure load-balancing, failover, and/or failback by specifying the following:

        • The order of the gateway definition in the gateway list.
        • The server type (i.e. Primary or Backup).

        For more information, see MDC gateway load-balancing, failover, and failback.

      5. Type the user name and password of the gateway account in the SMS gateway account section.

        If you are using the OneSpan Notification Gateway hosted by OneSpan to send SMS, the user name is the contract ID and the password is the API key.

    7. If required, switch to the Request Details tab to configure request format settings and parameters (see Request details).
    8. If required, switch to the Response Handling tab to configure result matching rules settings (see Response handling).
    9. Click Apply.

    For more information about testing your gateway settings, see Testing gateway configurations.

    For more information about configuring proxy settings, see Configuring HTTP proxy servers (for Message Delivery Component).

    Request details

    Depending on the specific requirements of the SMS gateway used, you need to set up the request format and parameters accordingly. Request format settings determine how the message is encoded and submitted and include the HTTP request method, i.e. GET or POST, and the content type, i.e. plain text or JSON.

    The message usually includes different message parameters that you may want or need to submit to the gateway, e.g. as HTTP header fields or query string parameters. It typically contains the following parameters:

    • username. The user name to log in to the gateway.
    • password. The password to log in to the gateway.
    • device. The mobile phone number to send the message to.
    • network. The type of mobile network to use (if required by the gateway).
    • message. The message content.

    Each message parameter can contain a value or a pre-configured MDC variable. The following variables are available:

    • [acc_user]. From the User name field in the SMS Delivery > Gateway Setting > SMS gateway account section (MDC Configuration Utility).
    • [acc_pwd]. From the Password field in the SMS Delivery > Gateway Setting > SMS gateway account section (MDC Configuration Utility).
    • [otp_dest]. The user's mobile phone number in the respective user record. Sent by OneSpan Authentication Server.
    • [otp_msg]. Message template string set in the Configuration Utility. Sent by OneSpan Authentication Server.

    To set up the HTTP request parameters

    1. Start the MDC Configuration Utility.
    2. Switch to the SMS Delivery tab.
    3. Select the gateway definition you want to configure from the gateway list.
    4. Switch to the Request details tab.

    5. Select a request method. This depends on the requirements of the gateway, but typically is POST.

      • POST. The message data (as specified in the Request body parameters list) is enclosed in the request body of the HTTP request.
      • GET. The message data (as specified in the Query string parameters list) is appended to the URL as a regular HTTP query string.

    6. Select a content type. This specifies the original media type encoding of the message data and depends on the requirements of the gateway.

      • Plain text. The message data is enclosed as plain text key–value pairs, e.g. key=value. The HTTP Content-Type header field is set to text/plain.
      • JSON. The message data is encoded and submitted as JSON format, e.g. { "key": "value" }. The HTTP Content-Type header field is set to application/json.
    7. (OPTIONAL) Specify any HTTP header fields that you want to add to the request. Use the Add, Edit, and Delete buttons to manipulate the HTTP header fields list accordingly. The order in which the header fields are added to HTTP requests is not guaranteed.
    8. (OPTIONAL) Specify any query string parameters that you want to add to the request. Use the Add, Edit, and Delete buttons to manipulate the Query string parameters list accordingly. The order in which the query string parameters are added to HTTP requests is not guaranteed.

    9. (OPTIONAL) Specify any request body parameter that you want to add to the request. Use the Add, Edit, and Delete buttons to manipulate the Request body parameters list accordingly. The order in which the header fields are added to HTTP requests is not guaranteed.

      The Request body parameters list can only be edited if Request Method is set to POST.

    10. Click Apply to store your changes and restart the MDC service/daemon.

    Response handling

    SMS gateways usually return a request result when a text message is submitted. Depending on the gateway type and requirements that result can be, for instance, an HTML-formatted page containing specific error codes and additional messages for success/failure or a JSON structure.

    Result messages are generally categorized as three types:

    • Information. The message delivery was successful, i.e. the message has been accepted by the server.

    • Warning. The submission/delivery failed, but it is most likely a specific error only affecting this particular user. The user’s logon request will fail on the first step. Possible causes are:

      • The phone number is invalid.
      • A temporary gateway failure occurred.

    • Error. Some error occurred during the delivery attempt. This means that the delivery failed for a particular user, but the error might be affecting all users. In this case, the user’s logon request will fail immediately. Possible errors are:

      • The account data is incorrect, i.e. account user or password is wrong.
      • The account credit expired (for a pre-paid gateway account).
      • A communication error with the gateway occurred (network error).
      • Another permanent gateway error occurred.

    Result matching rules

    You can define result matching rules to process gateway results and to create alternate messages for auditing whenever a result is received. A gateway result page can be recognized by key words and phrases, and an alternate message created for logging to the audit console whenever the result is received. Variables can be extracted from the result and used in the log message to provide extra information.

    You can set the order of the result matching rules to match more specific messages first and finally catch any other message, which the gateway might send. If no rule matches a result returned, an error will be added to the audit log, reporting that the result page returned from the gateway could not be matched.

    Result matching patterns

    A result matching rule defines a result matching pattern that triggers the rule. The format of the matching patterns depend on the content type configured in the request details settings of the SMS gateway definition (see Request details).

    Plain text

    Plain text matching patterns use the following syntax:

    fixed_1 [variable_1] fixed_2 [] fixed_3variable_2 ...

    Where the pattern is constructed in the following way:

    • fixed_<x> is a character string that must be matched exactly as is in the result returned by the gateway. Note that multiple fixed_<x> segments can appear in a single template, as long as they do not overlap. Matching is case-sensitive.
    • [ ] omits a variable part of the result between two fixed_<x> segments, when matching a template. This can be useful to ignore arbitrary data or time/date data in the returned web page.

    • variable_<x> describes a segment of the result between two fixed_<x> segments or at the end of the result page, which will be stored in a variable to use as a named backreference in the audit text. Usually this will be data that can provide more detailed information why a particular message submission has failed.

      The variable name is put in square brackets. Variables can be used as part of the audit message template to create a meaningful audit message. The variable names are case-sensitive and must be unique.

    Plain text result matching patterns

    Consider a gateway that returns the following results for successful and failed transmissions, respectively:

    • Success: “<b>Submission successful at 10:00, 11/11/02, status: 00 - message delivery in progress.</b>”
    • Failure: "<b>Submission unsuccessful at 10:05, 11/11/02, status: 47 - number too short</b>"

    The following possible result matching rules can be configured to handle these results:

    1. Rule name: Success

      Matching pattern: successful at [DateTime], status: [Status] - [Message]</b>

      Variables retrieved: DateTime, Status, Message

    2. Rule name: Warning

      Matching pattern: unsuccessful at [DateTime], status: 47 - [Message]</b>

      Variables retrieved: DateTime, Message

    3. Rule name: Error

      Matching pattern: unsuccessful at [DateTime], status: [Status] - [Message]</b>

      Variables retrieved: DateTime, Status, Message

    JSON

    JSON matching patterns are defined by a valid JSON structure:

    { <"key>": "<value>" ... }

    value can be either a literal value or a segment, which will be stored in a variable to use as a named backreference in the audit text. In the later case, you specify the variable name within square brackets. Variables can be used as part of the audit message template to create a meaningful audit message. The variable names are case-sensitive and must be unique. Note that value used as variable must always be put in quotes to define a valid JSON structure, regardless of the actual JSON data type in the response.

    A JSON matching pattern can contain multiple key–value pairs. In that case, the result matching rule triggers only if all of the specified key–value pairs are present. The order does not matter.

    JSON result matching patterns

    Consider a gateway that returns the following results for successful and failed transmissions, respectively:

    • Success:

      {
  "success": true,
  "message": "Messages will be processed and sent",
  "errors": []
}

    • Failure:

      {
  "success": false,
  "message": "Invalid notification request",
  "errors": [
    {
      "field": "phoneNumber",
      "message": "The phoneNumber may not be missing/empty",
      "errorCode": "INVALID_PHONENUMBER"
    }
  ]
}

    The following possible result matching rules can be configured to handle these results:

    1. Rule name: Success

      Matching pattern: { "success": true, "message": "[Message]" }

      Variables retrieved: Message

    2. Rule name: Error

      Matching pattern: { "success": false, "message": "[Message]", "errorCode": "[ErrorCode]" }

      Variables retrieved: Message, ErrorCode

    Audit text templates

    If a result matching rule triggers, a corresponding audit message is constructed and written to the audit log. The result processing stops, subsequent result matching rules are not evaluated. The audit message is constructed based on the audit text template defined in the result matching rule, it can contain variables retrieved from the result matching pattern and the following pre-defined variables:

    • [otp_dest]. The destination address (a mobile phone number) the OTP was sent to.
    • [otp_msg]. The message that was submitted. This variable will also contain the OTP, so should not be used for the construction of audit messages.
    • [acc_user]. Account name for the gateway. Not recommended for use in audit messages.
    • [acc_pwd]. Account password for the gateway. Not recommended for use in audit messages.
    • [Username]. The user ID of the user requesting the OTP.

    Use variables in audit text templates

    • Insufficient credit on account [acc_user] when sending to [Username]
    • Message not sent to user [Username]/[otp_dest]. Gateway reported: [Message]

    To add a result matching rule

    1. Start the MDC Configuration Utility.
    2. Switch to the SMS delivery tab.
    3. Select the gateway definition you want to configure from the gateway list.
    4. Switch to the Response handling tab.
    5. Click Add to open the Result matching rule dialog.
    6. Type a descriptive name for the rule in the Description box.
    7. Type the full text or a partial match of the text displayed by the gateway in the Matching pattern box, optionally with variables (see Result matching patterns).
    8. Select an audit message level for the rule. Each message level will be displayed with a different color scheme in the Audit Viewer application, based on the respective color highlighting settings configured.
    9. Type the message text you want the users to see into the Audit text box, optionally using variables (see Audit text templates).

    10. Click OK.

      The new result matching rule is added to the rule list. Use the Move up and Move down buttons, to configure the order of the result matching rules. The result matching rules are processed from top to bottom, the first one that is triggered writes the audit message.

    Cet article vous a-t-il été utile ?
    What's Next
    Change password!
    Changing your password will log you out immediately. Use the new password to log back in.
    Change profile
    Success!
    First name must have atleast 2 characters. Numbers and special characters are not allowed.
    Last name must have atleast 1 characters. Numbers and special characters are not allowed.
    Enter a valid email
    Enter a valid password
    Your profile has been successfully updated.
    Logout
    ESC

    Ozzy, facilitant la découverte de connaissances grâce à l’intelligence conversationnelle