keycloak-phone-provider

To install the Twilio SMS Sender Provider, copy the provider JAR files and the Twilio-specific JAR file into the Keycloak providers/ directory, then run the Keycloak build command.

Note: This provider is not verified for Quarkus 19.0.1.

cp target/providers/keycloak-phone-provider.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-phone-provider.resources.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-sms-provider-twilio.jar ${KEYCLOAK_HOME}/providers/

${KEYCLOAK_HOME}/bin/kc.sh build

When starting Keycloak, you must specify Total Voice as the default phone service and provide your Total Voice API token using the --spi-message-sender-service-totalvoice-token configuration option.

Use the following command structure:

--spi-phone-default-service=totalvoice to set the service. --spi-message-sender-service-totalvoice-token=${token} to provide your credentials.

${KEYCLOAK_HOME}/bin/kc.sh start  --spi-phone-default-service=totalvoice \
  --spi-message-sender-service-totalvoice-token=${token}

To allow users to reset their credentials using a phone number, you must configure a custom authentication flow in the Keycloak Admin Console:

1. Navigate to Authentication > Flows.
2. Copy the existing Reset credentials flow and name it Reset credentials with phone.
3. On the Reset credentials with phone flow, click Add step on the Reset Credential With Phone line.
4. Click Add step on the Send Rest Email If Not Phone line.
5. Delete or disable all other steps in that flow.
6. Set the Send Rest Email If Not Phone step to Conditional.
7. Set both Reset Credential With Phone and Reset Password to REQUIRED.
8. Bind the new Reset credentials with phone flow to the Reset credentials flow binding.

To install the YUNXin SMS provider, copy the provider JAR files and the resources JAR file into your Keycloak providers/ directory, then run the Keycloak build command.

Note: This provider has not been verified in Quarkus 19.0.1.

cp target/providers/keycloak-phone-provider.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-phone-provider.resources.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-sms-provider-yunxin.jar ${KEYCLOAK_HOME}/providers/

${KEYCLOAK_HOME}/bin/kc.sh build

When starting Keycloak, you must configure the SPI (Service Provider Interface) properties to use AWS as the default phone service and specify your AWS Sender ID.

Use the following configuration flags:

• --spi-phone-default-service=aws
• --spi-message-sender-service-aws-sender=${senderId}

${KEYCLOAK_HOME}/bin/kc.sh start  --spi-phone-default-service=aws \
  --spi-message-sender-service-aws-sender=${senderId}

To install the Aliyun SMS provider, copy the provider JAR files and the resources JAR file into the Keycloak providers/ directory, then run the Keycloak build command.

Note: This provider has been verified on Quarkus 21.0.1.

cp target/providers/keycloak-phone-provider.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-phone-provider.resources.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-sms-provider-aliyun.jar ${KEYCLOAK_HOME}/providers/

${KEYCLOAK_HOME}/bin/kc.sh build

To install the Twilio SMS Sender Provider, copy the provider JAR files into your Keycloak providers/ directory and run the Keycloak build command.

Note: This provider is not verified for Quarkus 19.0.1.

cp target/providers/keycloak-phone-provider.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-phone-provider.resources.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-sms-provider-twilio.jar ${KEYCLOAK_HOME}/providers/

${KEYCLOAK_HOME}/bin/kc.sh build

To use SMS as a second factor (2FA):

1. Create a new Flow: Copy the Browser flow and replace OTP with OTP Over SMS.
2. Bind Flow: Bind this new flow as the de facto Browser flow.
3. Enable Required Action: In the Required Actions tab, enable Configure OTP over SMS.

To allow users to register using a phone number:

1. Create a new Flow: In Authentication > Flows, copy the Registration flow to a new flow named Registration with phone.
2. Update Registration Logic: Replace Registration User Creation with Registration Phone User Creation.
3. Enable Phone Validation (Optional): In Registration with phone registration Form, add the Phone validation execution.
4. Configure User Attributes: The provider uses phoneNumberVerified (bool) and phoneNumber (str). Only one user per number will have phoneNumberVerified = true.
5. Set as Required: Set the new flow as Required in the Authentication page and bind it to the Registration flow.
6. Update Theme: Set the Realm Login Theme to phone under Realm Settings > Themes.

When starting Keycloak, you must specify the Twilio service as the default phone service and provide your Twilio credentials using the following configuration flags:

• --spi-phone-default-service=twilio
• --spi-message-sender-service-twilio-account (Your Twilio Account SID)
• --spi-message-sender-service-twilio-token (Your Twilio Auth Token)
• --spi-message-sender-service-twilio-number (The Twilio service phone number)

${KEYCLOAK_HOME}/bin/kc.sh start  --spi-phone-default-service=twilio \
  --spi-message-sender-service-twilio-account=${account} \
  --spi-message-sender-service-twilio-token=${token} \
  --spi-message-sender-service-twilio-number=${servicePhoneNumber} 

To install the BulkSMS provider, copy the provider JAR files into your Keycloak providers/ directory and run the Keycloak build command.

Note: This provider is not verified in Quarkus 19.0.1.

cp target/providers/keycloak-phone-provider.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-phone-provider.resources.jar ${KEYCLOAK_HOME}/providers/
cp target/providers/keycloak-sms-provider-bulksms.jar ${KEYCLOAK_HOME}/providers/

${KEYCLOAK_HOME}/bin/kc.sh build