Description
This article describes the general setup on an SMS gateway. It links to a few more specific setups as well. It intends to expand the documentation on the administration guide: SMS Gateway documentation
Note that this does not include the FortiGuard SMS service. For FortiGuard SMS, no configuration is required, but only a credit-based license.
Scope
FortiAuthenticator SMS Gateway integration, typically used for Multi-factor authentication.
Solution
FortiAuthenticator will use variables in the format {{:variable}} and when sending a message, replace the variable with the actual content.
The variables as of now are:
{{:country_code}}
{{:mobile_number}}
{{:message}}
{{:random_id_64}
{{:null}}
The variable {{:mobile_number}} would be filled out with the mobile number of that user (must be known to FortiAuthenticator).
{{:country_code}} is filled with the users country, also must be known to FortiAuthenticators user database.
{{:message}} contains the text that is to be sent to the user. This is filled out with a message that is from the replacement messages on FortiAuthenticator and may be adapted.
{{:random_id_64} can be used if the SMS gateway requires some unique message ID. This is usually not required, the providers documentation would however state it, if needed.
{{:null}} can be used if an empty value is supposed to be sent, also depends on the provider.
The SMS integration at GUI -> System -> Messaging -> SMS gateways contains the following parts:
Protocol: Whether to use SMTP or HTTP(S). The protocol selection 'SMTP' will rely on a mail server setup and the OTPs for 2FA will be sent via email to the SMS gateway provider. The provider converts the mail to an SMS with given information. The protocol selection HTTP and HTTPS will have FortiAuthenticator act as an HTTP client, similar to a browser or HTTP client applications like 'POSTMAN'.It will issue an HTTP GET or POST to the SMS Gateway, that acts as HTTP server.
Note:
Whether HTTPS (encrypted) is used, is irrelevant to the general function. If HTTPS isn’t working, but HTTP is, the TLS session setup needs to be troubleshooted. Very likely the FortiAuthenticator doesn’t trust the server certificate and the team handling the SMS gateway server should provide the CA certificate(s) related to the SMS gateways server certificate.
Import these CA certificates as per documentation into the Trusted CAs.
Troubleshooting and examples can be found here:
SMS gateway using HTTPS protocol unable to send a text message: HTTP request failed
Configure Gmail (STARTTLS) as a mail server
Configure Microsoft Office 365 SMTP as Mail server in FortiAuthenticator
More about certificates and encryption can be found in the article about SSL/TLS and the use of Digital Certificates.
The following settings however rely on the provider. Seek the documentation of the provider for the details. What parameters are required, what responses are expected, etc.
The API URL is the URL that the server will be listening on for requests.
The CA certificate will need to be the one that issued the SMS gateway server certificate.
How the HTTP Parameters work:
The HTTP parameters come as pairs of an attribute and a value.
The left-hand side (Field) contains the attribute that the gateway expects. The right-hand side (Value) is the value that the gateway will act on, matching the variable.
An attribute 'To' typically is mapped or filled with a value of the recipient, the cell phone number of the end user.
An attribute like 'body', 'text', 'message' will contain the message that is to be sent to the user.
For example, see the following setup:
The SMS gateway server expects the attribute api_key and a value. An API key is typically used for authentication of the individual organization, so the request to the SMS server cannot be made by anyone without the correct API key.
It is sent as an HTTP parameter/value pair in the form of a pair-like parameter<->value.
The example link on the bottom of the picture breaks down to:
https:// api . sms . to /sms/send ?api_key = 123456789apikey987654321 & from = 2FA%20service&to=6045551234 & text = Your%20authentication%20token%20code%20is%20123456
URL = https:// api . sms . to / sms / send
Starting HTTP parameters with '?'.
parameter1 and value1:
api_key=123456789apikey987654321
indicating the next parameter value pair with '&'.
from=2FA%20service (the %20 translates in HTTP to an empty space)
indicating the next parameter value pair with '&'
This pair now is the recipient where the value is replaced with the variable. FortiAuthenticator for the purpose of demonstration, replaces this with a bogus number.
to=6045551234
indicating the next parameter value pair with '&'
Likewise, this pair has another variable filled out, the {{:message}} variable:
text=Your%20authentication%20token%20code%20is%20123456 (the %20 translates in HTTP to a space).
The variable {{:message}} in turn is filled here with an example, but in a productive setup, the content can be controlled with a replacement message.
These can be found at System -> Administration -> Replacement Messages. Select 'SMS Token Message' from that list to open the message:
The replacement message can be edited, for example:
The variables in the replacement messages work the same as in the SMS gateway setting and will be replaced. {{:username}} will be replaced with the actual username that is authenticating and enter the second factor.
{{:token_code}} will be replaced with the actual one-time password (OTP), like 123456.
Above example in the screenshot would lead to the {{:message}} variable to be filled with the following text (different user and random OTP always filled according to the need):
Hello user1, this is your Token code:
485926
The URL preview is valid only for the HTTP GET method and serves well as a demonstration.
The HTTP POST method works a little differently and has no preview. The difference is the content-type that the HTTP post should be using. This also depends on the provider's documentation.
Select what is required.
However, with HTTP POST, FortiAuthenticator does NOT support setting custom headers. HTTP Header modification cannot be done, so a bearer token cannot be added either.
The authorization type can authenticate the server (analog to the API key on the GET method).
Sending the Mobile number can be done as a variable definition - a string (so text) or a number/integer). This also depends on the SMS gateway provider. The integer can contain a '+' character, to indicate the country code and predial. The JSON number will not use that character but instead, just write the number. For example, the string can be '+49', the number can be '0049' or just '49' as the country predial.
HTTP parameters on the POST method however are then similar to the GET method, except the API key may not be required for authentication due to HTTP POST offering another authentication method already.
Troubleshooting:
The FortiAuthenticator does SMTP or HTTP communication and as such, the responses from the server adhere to the protocol.
On SMTP, the intended success response will be 250. On HTTP the intended success response is 200. If the server sends such a response, but the SMS is not delivered, engage the support of the SMS gateway.
The FortiAuthenticator logs this. So for example, the HTTP 200 will be logged like this:
date=2024-09-05 time=10:48:42+0000 oid=6513246 logid=30911 cat="Event" subcat="System" level="information" nas="" action="" status="" msg="SMS gateway "test-SMS-gateway" via HTTPS POST returns status code 200 (response: )" user=""
That would mean that the SMS gateway accepted the request of FortiAuthenticator to send the SMS. If the SMS does not arrive, check with the team handling that SMS gateway.
A few providers, for example Airtel, must whitelist the FortiAuthenticator and would otherwise drop the SMS, but still respond with an HTTP 200.
If the response code is something different like HTTP 415, HTTP 400, HTTP 405, HTTP 401, see with the provider on why that response is issued.
A HTTP 404 would for example mean that the API URL is incorrect.
Communication troubleshooting:
Test the SMS sending, see that reachability is given. Typical error network-based error messages would include:
In detail:
- DNS must work, for FortiAuthenticator to resolve the SMS gateway unless the IP can be used.
- In the case of encrypted communication: TLS must work. The IP likely cannot be used as it opposes regular TLS setup.
- The general communication must work, so FortiAuthenticator must have access to that SMS gateway.
- Temporarily, the encryption can be turned off and a packet capture will show more information on the exchange between server and client (gateway and FortiAuthenticator).
In the case of HTTP, the request and responses can be seen in the clear.
In the case of SMTP, likewise, the SMTP communication can be seen in the clear.
To create a packet capture on FortiAuthenticator, best to use the CLI:
execute tcpdumpfile -i any port 25
Reproduce the issue report and stop the packet capture with CTRL-C. Download the PCAP file at https://fac-ip/debug/pcap-dump.
The FortiAuthenticator will only log the most recent response. If the response is unexpected, keep in mind to investigate on the server to understand why the response is given.
For example the SMTP server may respond with these two packets (shortened Wireshark output):
S: 550 5.7.1 Service unavailable, Client host [test.forti.lab] blocked using Spamhaus. To request removal from this list see https://www.spamhaus.org/query/ip/ test.forti.lab AS
S: 503 5.5.2 Need rcpt command | 500 5.3.3 Unrecognized command 'Length: 5' | 500 5.3.3 Unrecognized command 'Length: 3' | 500 5.3.3 Unrecognized command 'Length: 8' | 500 5.3.3 Unrecognized command 'Length: 5' | 500 5.3.3 Unrecognized command 'Length: 11' | 500 5.3.3 Unrecognized command 'Length: 7' | 503 5.5.2 Need rcpt command | 500 5.3.3 Unrecognized command 'Length: 7' | 503 5.5.2 Need rcpt command
FortiAuthenticator shows the following on the SMS test:
Unable to send a test email: Unrecognized command 'Length: 3' [DA5PRPF02012394. Please check your server configuration.
Logging the same in the FortiAuthenticator GUI:
date=2024-09-05 time=10:48:42+0000 oid=4343986 logid=30908 cat="Event" subcat="System" level="error" nas="" action="" status="" msg="smtp mail: failed send to fortiuser@forti.lab via 10.255.48.40:25, error: Unrecognized command 'Length: 3' [DA5PRPF02012394" user="admin"
The failure reason here is not that FortiAuthenticator is sending bad SMTP commands to the server.
The actual reason is visible only in the packet capture:
The mail server categorizes the sender IP as spam and blocks the message with SMTP code 550 (550 5.7.1 Service unavailable, Client host [test.forti.lab] blocked using Spamhaus.).
This however must be addressed on the server end and its spam mechanism. The server block leads FortiAuthenticator to continue with the message, while the server stopped parsing it. As such, any following SMTP command is unrecognized.
Over time, we have received a few reports of working SMS gateway providers. The list is not exhaustive and will be updated when needed:
100coins: using HTTP GET
Airtel: using HTTP GET, as HTTP POST would require HTTP header modification, which isn't supported. This provider is reported to require whitelisting. Otherwise the SMs that FortiAuthenticator handed successfully over, will be dropped silently.
Clickatell: using HTTP GET
Cyberlink: using HTTP POST
Infobip: using HTTP POST
Goinfinito: using HTTP GET
Pinnacle: using HTTP POST
Proximus: using HTTP GET
SendQuick: using HTTP GET
SMS Masivos: using HTTP GET
SMS Eagle: using HTTP GET, as HTTP POST would require HTTP header modification, not supported. SMTP also works, but a 'message-id' is added to the SMS. The SMTP requires a message-ID to be sent, the gateway however adds it by default.
SMS.to: using HTTP GET, as HTTP POST would require HTTP header modification, not supported. SMTP also works, but a 'message-id' is added to the SMS. The SMTP requires a message-ID to be sent, the gateway however adds it by default.
SMSjust.com: using HTTP GET
Textmagic: using SMTP
Twilio: using HTTP POST. A configuration example is found in the article How to configure FortiAuthenticator with the Twilio SMS gateway
Zong: using HTTP GET
