Before you start
You need a self-hosted Keycloak server and a BulkSMS account with credits.
The connection uses the community keycloak-phone-provider extension and its BulkSMS module. It isn't an official Keycloak feature, so check it supports your Keycloak version.
Create a BulkSMS API token
Log in to your BulkSMS account and go to Settings > Developers.
Click Create API Token and give it a name, for example Keycloak. Copy the Token ID and Token Secret. The secret is only shown once.
Install the provider
Copy the phone provider and keycloak-sms-provider-bulksms JAR files into ${KEYCLOAK_HOME}/providers/.
Rebuild Keycloak:
kc.sh build
Start Keycloak with BulkSMS settings
Start Keycloak with BulkSMS as the phone service, using your token details:
kc.sh start \ --spi-phone-default-service=bulksms \ --spi-message-sender-service-bulksms-username=YOUR_TOKEN_ID \ --spi-message-sender-service-bulksms-password=YOUR_TOKEN_SECRET
Optional settings, added the same way:
| Setting | What it does |
|---|---|
...-bulksms-from |
The number or Sender ID to send from. |
...-bulksms-encoding |
Set to UNICODE for non-Latin characters. |
...-bulksms-routing-group |
ECONOMY, STANDARD or PREMIUM. |
Then turn on phone login, registration or OTP in your realm's authentication flows, as described in the extension's documentation, and test with your own number.
Troubleshooting
No codes arrive: check the Keycloak server log for the BulkSMS response. A 401 means the token details are wrong; a 403 usually means no credits.
You can see every message and its delivery status under Sent Messages in BulkSMS. For problems with the extension, see its GitHub page.
All setup and ready to go!
If you have any questions about your BulkSMS account, please contact our support team. Include your account name and put Keycloak in the subject line, and we'll be happy to help.