When a user signs in to an application protected by Keycloak, the one-time code is sent by SMS through SMSEagle, your own hardware SMS gateway. The request stays in your local network, with no cloud SMS provider.
A one-time password is a security credential. Sending it through a cloud SMS provider means your codes pass through an external platform on every login. SMSEagle removes that intermediary: Keycloak calls the gateway over your local network, and the code is sent from your own device over the cellular network.
Cloud SMS OTP needs outbound internet access from your identity infrastructure – a non-starter in air-gapped environments. SMSEagle sends messages on-premises over its own cellular connection, delivering OTP codes even in fully offline installations.
Cloud SMS OTP is billed per message, often at premium rates for authentication traffic. SMSEagle sends over a standard SIM at local carrier rates – no per-message fees, no external contract, no cloud provider that can raise prices or go down.
A user signs in to a Keycloak-protected application and passes the first factor (password).
Keycloak generates a one-time code and calls the SMSEagle device’s API over the local network.
SMSEagle delivers the code over its own cellular connection, not through a third-party service, as an SMS to the user’s own phone.
Connect Keycloak to SMSEagle and set up the SMS step in the authentication flow, and codes are sent by SMS.
An SMS code needs no app: people receive it on any mobile phone.
SMSEagle records every code it sends, together with its status, so you can check whether it was received.
Two SMSEagle devices can work as an HA cluster: if one fails, the other takes over sending codes.
This integration uses Keycloak-mfa-plugins repository to get a 2nd-factor authentication with a OTP/code/token send via SMS. Full instruction can be found under this link.
cp netzbegruenung.keycloak-2fa-sms-authenticator.jar /path/to/keycloak/providers
c) Run the build command and restart Keycloak:
/path/to/keycloak/bin/kc.sh build [your-additional-flags] systemctl restart keycloak.service
2. Setup
a) Navigate to your Authentication flow configuration: https://keycloak.example.com/admin/master/console/#/YOUR-REALM/authentication. Then edit the Browser flow.
b) Add a new step next to the OTP Form step. Choose the SMS Authentication (2FA) authenticator and set it to Alternative.
c) Make sure that you name it sms-2fa. Additional executions with other names can be added. But this first execution will be used for the confirmation SMS when setting up a new phone number.
d) Go into the config of the execution and configure the plugin so that it works with the API of SMSEagle:
SMS API URL: https://IP.OF.YOUR.SMSEAGLE/api/v2/messages/sms_single
where IP.OF.YOUR.SMSEAGLE should be replaced with the actual IP or domain name of your SMSEagle device.
URL encode data: off
API Secret Token Attribute: access_token
API Secret: API access token generated in step SMSEagle setup
Message Attribute: text
Receiver Phone Number Attribute: to
Sender Phone Number Attribute: from
Force 2FA: if the option is enabled and a user has no other 2FA method already enabled, users will have to set up the SMS Authenticator.
3. Usage
After the authenticator and the required actions are configured, users can set up SMS Authentication in the account console /realms/realm/account/#/account-security/signing-in by entering and confirming their phone number.
SMSEagle is a hardware & software solution that guarantees a swift delivery of your messages to designated recipients, whether it’s for notifications, alerts, or important updates.
After registering to a demo you get a remote access to our physical device NXS-9750.
