Skip to main content

Messages Proxy

Messages Proxy is a web application that runs on IIS. Messages Proxy provides a Web API for sending OTPs by running external modules (scripts, binary executable modules). Unlike SMS Proxy, Messages Proxy does not connect to an SMPP gateway; it only runs scripts (any executable file).

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 Messages 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 Messages 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 certificates for Messages Proxy and Core Server​

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

On the Messages Proxy server (server)​

To request a certificate from the Windows domain certification authority:

  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/ (the connection is secure).

On Core Server (client)​

Generate a client authentication certificate. You can use the Computer template in the Windows domain certification authority as a basis. To do this, on the machine 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.

Edit the configuration file​

  1. On the Messages Proxy server, open the app-settings.Production.json configuration file from the C:\inetpub\wwwroot\am\proxies\messages folder.

  2. In the Scripts field, specify the following values:

    • Path — the path to the program that runs the script
    • Arguments — the script startup parameters, including the path to the script
    • Timeout — the time after which Messages Proxy returns an error if the script has not been executed. The default value is 00:00:20 (20 seconds)
    Information

    You can add more than one script to the Scripts field. To do this, specify several blocks with the parameters for each script, separated by commas. You can also define the script startup order — sequential (Sequential) or simultaneous (Parallel). If this parameter is not defined, the default value Sequential is used.

  3. In the LoggingPermissions field, specify the parameters that define the information to be logged. The possible parameters are:

    • Source — the message sender
    • Destination — the message recipient
    • Error — the script execution errors
    • Output — the messages generated during the script execution
    • None (the default value) — the values of all logged fields are hidden
    • All — the values of all logged fields are shown

    For example, if the Source parameter is specified in LoggingPermissions, the message sender is logged (not hidden). All the other parameters are hidden and replaced with ****. The logs are located in the C:\inetpub\wwwroot\am\proxies\messages\Logs\<folder with the date> folder.

  4. The Publication field includes the optional DefaultSource parameter that contains the default SMS sender name.

  5. Optionally, you can configure the parameter that enables Swagger. In the Documentation field, set the Enabled parameter to true. Swagger is then available at /am/proxies/messages/documentation.

  6. In the Authentication": { "Certificate": { "Thumbprint": "" } } field, specify the thumbprint of the (client) certificate that the provider (SMS or Storage SMS) can be authenticated with in Messages Proxy to send messages. You can use several certificates from several clients; in this case the field is named "Thumbprints".

An example of the configuration file
{
  "MessagesProxy": {
    "Scripts": [
      {
        "Path": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
        "Arguments":
            [
                "/c",  "C:\\inetpub\\wwwroot\\am\\proxies\\messages\\script.bat",
                "{0:Source}",
                "{0:Content}",
                "{0:Phone}",
                "{0:RawObjectId}",
                "{0:Sid}",
                "{0:DistinguishedName}",
                "{0:PrincipalName}",
                "{0:SamCompatibleName}",
                "{0:Email}",
                "{0:CustomParameter}"
            ],
        "Timeout": "00:00:10"
      }
    ],
    "LoggingPermissions": "Source"
  },
  "Publication": {
    "DefaultSource": "Axidian sender"
  },
  "Documentation": {
    "Enabled": false
  },
  "Debug": {
    "ExceptionResponsesEnabled": false
  },
  "Authentication": {
    "Certificate": {
      "Thumbprint": "124b3c62f4da3ce8bb271dc4990e354d118daa0g"
    }
  },
  "ReverseProxyIntegration": {
    "BasePath": "/am/proxies/messages"
  },
  "Localization": {
    "DefaultCulture": "en-US"
  }
}

Script​

The script file reads the parameters passed from Messages Proxy. The parameters are written to the C:\distr\ps.json file (the fileName parameter from the PowerShell script example). When Messages Proxy is used through an SMS provider, the OTP is passed in the Content parameter.

An example of a PowerShell script

$body = @(
@{
Source = $args[0]
Content = $args[1]
Phone = $args[2]
RawObjectId = $args[3]
Sid = $args[4]
DistinguishedName = $args[5]
PrincipalName = $args[6]
SamCompatibleName = $args[7]
Email = $args[8]
CustomParameter = "I am PS"
}
)

$body | ConvertTo-Json | Out-File "C:\distr\ps.json"

Invoke-WebRequest -Method Post -Uri 'http://Srv01.axidian.local:82/api/sms' -Body ($body|ConvertTo-Json) -ContentType 'application/json'

Start-Sleep -Seconds 5

Configure SMS OTP / Storage SMS OTP Provider​

Use group policies to configure SMS OTP Provider or Storage SMS OTP Provider to send OTPs through Messages Proxy. Before you configure the group policies, add the Axidian Access policy templates to the administrative template list. The policy template files are included in the Messages Proxy distribution and are located in the Misc folder.

Select the connection type​

The Select the provider connection type policy applies to the Axidian Access servers and is designed to select the connection type of Core Server (through SMS OTP Provider or Storage SMS OTP Provider) to the SMS gateway.

  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 Messages proxy option for Messages Proxy.

Connection type settings​

The Messages proxy settings policy applies to the Axidian Access servers and defines the connection type settings.

  1. Open the Messages proxy settings policy. The policy is located at Administrative Templates → Axidian-ID → Id Providers → SMS OTP.

  2. Set the policy value to Enabled.

  3. Define the following parameters:

    • URL — the server connection address
    • Sender — the sender name displayed when the message is received
    • Additional text before the OTP — an arbitrary message text that precedes the one-time password
    • Client certificate thumbprint — the provider certificate specified in the Messages Proxy app-settings.Production.json configuration file (the Authentication": {"Certificate": { "Thumbprint": "" } } field)
    • Server certificate thumbprint — the Messages Proxy certificate for working through HTTPS (configured in IIS)