Here we describe how to set up MFA/2FA (Multi-Factor Authentication) using SMS OTP (One-Time Password) in Keycloak. The integration uses SMSEagle Hardware SMS Gateway. The process is easy and should take 10-15 minutes to complete.
SMSEagle is an offline hardware SMS gateway. Therefore no external connection to 3rd party system is required. All notifications are generated on-premise and sent directly to a cellular network. This solution can be used in secure installations without Internet access.
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.
