Configure phone number login in Keycloak

This guide shows how to configure a Keycloak client to use Presta's custom phone number and PIN authentication flow.

Prerequisites

The custom Phone Number Login with Pin authenticator must already be available in your Keycloak deployment. You will also need the application URL and the tenant ID assigned to the client.

Create the client

Create a new client with these settings:

Setting	Example
Client ID	customer-self-service-portal
Client type	OpenID Connect

Configure the remaining client settings for your application.

Configure redirect URIs and web origins

In the client settings, add the application URLs. Replace the example domain with your application's domain.

Setting	Example
Valid redirect URIs	https://lending.me.co.ke/*
Valid post logout redirect URIs	https://lending.me.co.ke/*
Web origins	https://lending.me.co.ke

Web origin format

Do not add a trailing slash to the web origin. Use https://lending.me.co.ke, not https://lending.me.co.ke/.

Add the tenant ID claim

Add a protocol mapper to the client to include its tenant ID in tokens. Configure it as a Hardcoded claim:

Mapper setting	Value
Token claim name	tenantId
Claim value	The tenant ID assigned to this client, for example t10009

Enable the mapper for the token types your application needs. For example, if the application reads the claim from the access token, enable it for the access token.

The resulting token claim should look like this:

{
  "tenantId": "t10009"
}

Replace t10009 with the tenant ID assigned to the client.

Configure the phone number login flow

The Keycloak deployment includes a custom browser flow named browser-phone-pin-flow. Configure its forms subflow to use the Phone Number Login with Pin execution and set that execution to Required.

The relevant part of the flow should look like this:

browser-phone-pin-flow

Cookie                          Alternative
Kerberos                        Disabled
Identity Provider Redirector    Alternative
browser-phone-pin-flow forms    Alternative
└── Phone Number Login with Pin Required

If browser-phone-pin-flow is missing, duplicate the browser flow and configure the copy as described above. Check the flow's executions before using it. Changes to a flow affect every client that uses that flow.

Set the client's browser flow override

Open the client and go to its authentication flow settings:

Clients
→ customer-self-service-portal
→ Authentication flow

Set the Browser Flow override to browser-phone-pin-flow. This applies the flow to this client without changing the realm's default browser flow.

Keycloak version differences

Depending on your Keycloak version, the Browser Flow override may appear under the client's advanced settings.

Verify the configuration

Sign out of Keycloak, or use a private browser window, then start a login from the application. An existing Keycloak session may let the Cookie execution skip the phone number and PIN form.

Confirm that:

• The phone number and PIN login form appears.
• The user can authenticate successfully.
• Keycloak redirects to an allowed application URL.
• The issued token contains the correct tenantId claim.
• Logout redirects to an allowed post-logout URI.