Skip to main content

SMS Proxy

SMS Proxy is a web application that runs on IIS. SMS Proxy connects to the SMPP gateway directly and sends SMS messages. The Axidian Access server does not terminate the session with the SMPP gateway, so the requests are sent within a single connection instead of a separate one for each request.

System requirements​

  • Windows Server 2012 R2 and higher
  • Internet Information Services 7.5 and higher with the following modules:
    • Web server
    • Static Content Compression
    • HTTP Errors
    • HTTP Redirection
    • Windows Authentication
    • WebDAV Publishing
    • ASP.NET
    • ASP
    • ISAPI Extensions
    • ISAPI Filters
    • IIS Management Console
    • IIS Management Scripts and Tools
    • Management Service

Preconfiguration​

  1. Install the IIS role on the server where you plan to install SMS Proxy, in one of the following ways:
    • Open Server Manager, select Local Server, and on the Manage tab, click Add Roles and Features.
    • Run the \Misc\IISScripts\Axidian.Main.IIS.Install.MSServer.ps1 script.
  2. Install .NET 6 by running dotnet-hosting-6.0.10-win.exe from the Axidian Access <version number>/Axidian Idp folder of the distribution.

Installation​

  1. Run the installation file located at Axidian Access <version number>/Axidian SMS Proxy/<version number> and follow the steps of the installation wizard.
  2. After the installation is complete, a system restart may be required. If the installation wizard prompts you to restart the system, confirm this action.
  3. To remove or restore the product, open the Control panel menu and use the standard procedure for the supported operating systems.

Prepare the certificate for SMS Proxy​

During the SMS Proxy module installation, the SSL certificate requirement is enabled by default, which in turn requires HTTPS configuration.

To request a certificate from the Windows domain certification authority on the SMS Proxy server:

  1. Open the certificate manager certlm.msc.

  2. In the Personal folder, right-click Certificates and select All Tasks → Request New Certificate.

  3. In the Certificate Enrollment window, click Next → Next, select the web server certificate template you created earlier, and click More information is required to enroll for this certificate.

  4. In the Certificate Properties window that appears, add the following values and click OK:

    • Subject name: in the Type field, specify Common name, and in the Value field, specify the full computer name (Srv01.axidian.local) or the short one Srv01.
    • Alternative name: in the Type field, specify DNS, and in the Value field, specify the full computer name (Srv01.axidian.local).

  5. Run IIS Manager.

  6. Go to Srv01(AXIDIAN\Admin-axidian) → Sites → Default Web Site and in the Actions section, click Bindings.

  7. Select the line with https 443 and click Edit. In the Edit Site Binding window that opens, select your certificate in the SSL certificate drop-down list and click OK.

  8. Select the line with http 80 and click Remove.

Information

Now you can open the IIS start page in a browser at https://Srv01.axidian.local/

Edit the configuration file​

  1. Open the app-settings.Production.json configuration file from the C:\inetpub\wwwroot\am\proxies\sms folder.

  2. In the Smpp section, fill in the following parameters:

    • SystemId and Password — specify the authentication data to connect to the SMPP server
    • Host — specify the connection address of the SMPP server
    • Port — specify the port defined for the connection to the SMPP server
    • SystemType — an optional sign-in parameter on the SMPP server side, for example, S1
    • EsmeAddressTon — the possible values are Unknown, International, National, NetworkSpecific, SubscriberNumber, Alphanumeric, Abbreviated
    • EsmeAddressNpi — the possible values are Unknown, ISDN, Data, Telex, LandMobile, National, Private, ERMES, IP
    • LoggingPermissions — specify the parameter that controls whether the sender and recipient information is displayed in the logs. You can specify several values separated by commas. The possible parameters are:
      • Source — the message sender
      • Destination — the message recipient
      • None (the default value) — the values of all logged fields are hidden
      • All — the values of all logged fields are shown

  3. The Publication field includes the optional DefaultSource parameter that contains the sender name in the requests, for example, Axidian-AM.

  4. In the Authentication": {"Certificate":} field, specify the thumbprint of the certificate that the provider (SMS or Storage SMS) can be authenticated with in SMS Proxy to send messages. By default, the configuration for authentication without a certificate is used: "Certificate": {"Enabled": false, "Thumbprint": "" }.

    Note

    To rule out possible problems with certificates, first configure the system without them, that is, without establishing a mutual TLS connection:

    • When you configure the SMS proxy policy, leave the certificate thumbprint values empty, as in the default settings.

    • In Axidian Access 8.2.6 and higher, additionally add the "NetworkAddress": { "Enabled": false } value to the Authentication": {"Certificate":} field.

  5. To apply the changes in the app-settings.Production.json file, restart the AxidianAM.Core.proxies.sms server.

An example of the configuration file
{
 "Smpp": {
    "SystemId": "smppclient1",
    "Password": "password",
    "Host": "am1.axidian.local",
    "Port": "2776",
    "EsmeAddressTon": "International",
    "EsmeAddressNpi": "ISDN",
    "ReconnectionDelay": "00:02:00",
    "LoggingPermissions": "Source"
    },
 "Publication": {
    "DefaultSource": "Axidian-Id"
    },
 "Documentation": {
    "Enabled": false
    },
 "Debug": {
    "ExceptionResponsesEnabled": false
    },
 "Authentication": {
    "Certificate": {
        "Enabled": false,
        "Thumbprint": "",
        "ForwardingHeader": "Proxy-Client-Certificate"
       },
        "NetworkAddress": {
           "Enabled": false
       }
    },
 "ReverseProxyIntegration": {
    "BasePath": "/am/proxies/sms"
    },
 "Localization": {
    "DefaultCulture": "en-US"
    }
}

Select the connection type​

Information

Before you configure the group policy, add the Axidian Access policy templates to the administrative template list. The policy template files are included in the SMS Proxy distribution and are located in the Misc folder.

The Select the provider connection type policy applies to the Axidian Access servers and is designed to select the Sender of SMS OTP Provider.

  1. Open the Select the provider connection type policy. The policy is located at Administrative Templates → Axidian-ID → Id Providers → SMS OTP.
  2. Set the policy value to Enabled.
  3. In the parameters, select the SMS proxy option for SMS Proxy.

SMS proxy settings​

The policy applies to the Axidian Access servers and defines the settings of the SMS sending service.

Enable the SMS proxy settings policy and specify the required parameters:

  • URL — the connection address of SMS Proxy. For example: https://am1.axidian.local/am/proxies/sms.
  • Sender — the sender name displayed when the SMS is received.
  • Additional text before the OTP — an arbitrary message text that precedes the one-time password.
  • Client certificate thumbprint (an optional parameter) — the provider certificate specified in the SMS Proxy app-settings.Production.json configuration file (the Authentication": {"Certificate": {"Thumbprint": "" } } field). This certificate is added to the client certificate list when a request is made to SMS Proxy.
  • Server certificate thumbprint — the SMS Proxy certificate for working through HTTPS (configured in IIS).

Mutual TLS connection​

To establish a mutual TLS connection between Core Server and SMS Proxy:

  1. For the SMS Proxy server (server), generate a server authentication certificate (using the Web Server template).

  2. For Core Server (client), generate a client authentication certificate (for example, using the Computer template in the Windows domain certification authority).

    To do this, on the host with Core Server:

    1. Open the certificate manager certlm.msc.

    2. In the Personal folder, right-click Certificates and select All Tasks → Request New Certificate.

    3. In the Certificate Enrollment window, click Next → Next and select the Computer certificate template you created earlier.

  3. Export the client certificate to a file and install it on the SMS Proxy server in Computer certificates → Personal.

  4. In the SMS Proxy configuration file, specify the following parameters.

    "Authentication": {
       "Certificate": {
          "Enabled": true,
          "Thumbprint": "client_certificate_thumbprint"
          }
        }

In the table below, you can find the possible parameters for the "Authentication": {"Certificate":} field.

ParameterDescription
Authentication:Certificate:Enabledtrue by default. Enables the use of a mutual TLS connection.
Authentication:Certificate:ForwardingEnabledtrue by default. Enables support for forwarding the client certificate from the proxy server in the Authentication:Certificate:ForwardingHeader HTTP header.
Authentication:Certificate:ForwardingHeaderA Base64-encoded certificate is expected. In an out-of-process integration with IIS, the certificate is passed in MS-ASPNETCORE-CLIENTCERT, which is used automatically. Example: Proxy-Client-Certificate
Authentication:Certificate:ThumbprintExample: 380854EA27F2BAED041A941CAC73337E27D0BA6A
Authentication:Certificate:RevocationModeNoCheck by default. The possible values are NoCheck, Online, Offline.
Authentication:Certificate:ValidateCertificateUsetrue by default. Defines whether the EKU check is required.
Authentication:Certificate:ValidateValidityPeriodtrue by default. Defines whether the certificate validity period check is required.
  1. Add the certificate thumbprint to the SMS proxy settings policy on Core Server.