Keycloak

This page shows how to let people sign in to MicroB2B with Keycloak. It also shows how a script gets a Keycloak token for the REST API. Read identity providers first for the concepts.

The examples use:

• MicroB2B at https://b2b.example.com (so PUBLIC_URL=https://b2b.example.com),
• Keycloak at https://keycloak.example.com, with a realm you choose,
• the provider name keycloak in MicroB2B.

Create the client in Keycloak

1. In your realm, create a client. Set Client type to OpenID Connect and Client ID to microb2b.
2. Under Capability config:
   • turn Client authentication on (this makes it a confidential client),
   • turn Standard flow on,
   • turn direct access grants, implicit flow and service accounts off.
3. Under Access settings, set Valid redirect URIs to https://b2b.example.com/ui/auth/keycloak/callback. Leave Web origins empty.
4. Under Advanced > Advanced settings, set Proof Key for Code Exchange Code Challenge Method to S256.
5. On the Credentials tab, copy the client secret.

Add the provider in MicroB2B

1. Go to Access > Identity providers and click New identity provider.

2. Fill in:

   Setting	Value
   Name	keycloak
   Display Name	for example Company login
   Issuer URL	https://keycloak.example.com/realms/<realm>
   Client ID	microb2b
   Client Secret	the secret from Keycloak

3. Save.

4. Sign out, then click Sign in with Company login on the login page.

Older Keycloak versions (before the Quarkus distribution) have /auth in the path. Their issuer URL is https://keycloak.example.com/auth/realms/<realm>.

Who may sign in

Every user of the realm can sign in, unless you restrict the client in Keycloak. For example, add a condition on a group or role to the client’s authentication flow. Remember that every MicroB2B user is an administrator.

A script with a Keycloak token

A script or another system can call the REST API with a Keycloak access token. Keycloak does not put the client in the audience of its access tokens by default, so you add an audience yourself.

1. Create a second client, for example importer. Turn Client authentication on and Service accounts roles on. Turn Standard flow off.
2. Open the client’s Client scopes tab and its dedicated scope. Click Add mapper > By configuration > Audience.
3. Set Included Custom Audience to microb2b-api and turn Add to access token on.
4. In MicroB2B, open the keycloak provider and set API Audience to microb2b-api.
5. Register the client in MicroB2B as a federated service account. Choose the keycloak provider and enter the token’s subject (sub) exactly.

The script then gets a token and calls the API:

TOKEN=$(curl -s -d grant_type=client_credentials -d client_id=importer -d client_secret=... \
  https://keycloak.example.com/realms/<realm>/protocol/openid-connect/token | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" https://b2b.example.com/api/v1/stats

MicroB2B refuses a token whose subject is not a registered service account or a MicroB2B user of that provider. If the call answers 401 INVALID_TOKEN, check the reason in the MicroB2B log. See troubleshooting sign-in.