Setup guide

Create the authentication in StudioCopy Anchor Link

1. Create an authentication dedicated to this realm and environment. Add both email and phone to every wallet you offer. Do not offer a wallet that cannot supply both.
2. If the flow is active, click Deactivate. Open Redirect URIs and add the broker callback exactly as shown under What you need. Keep https://test.ver.id/authentication/callback if you use Studio's test tool.
3. Under Secrets, attach an OAUTH secret.
4. Add an active brand, click Activate, and copy the client identifier from Configuration and the secret's Key (as base64url) value.
5. Test the authentication with scope openid email phone. The decoded ID token must contain email, email_verified, phone_number and phone_number_verified.

Add Ver.iD as an identity providerCopy Anchor Link

1. In the Keycloak Admin Console, select the realm, open Identity providers and choose OpenID Connect v1.0. If the realm already has providers, click Add provider first.
2. Enable Use discovery endpoint and enter the discovery URL. Keycloak imports the issuer, authorization, token, user info and JWKS endpoints. Leave them unchanged.

https://ssi.oauth.ver.id/.well-known/openid-configuration

3. Complete the remaining fields and click Add.

4. Open the saved provider and set the following. Validate signatures and Use JWKS URL are in OpenID Connect settings. Use PKCE, Scopes, Disable user info and Disable nonce are in that section's Advanced expander, halfway down the page. Store tokens, Trust Email, Account linking only and Sync mode are in the separate Advanced settings section at the bottom, where step 3 also binds the flows.

5. Click Save. The provider's Redirect URI must equal the broker callback you registered in Studio.

Configure first login and account linkingCopy Anchor Link

When a wallet login carries an email address that already belongs to a user, Keycloak's default flow offers to link the two after that user clicks a verification email. Replace it with a copy that accepts only a password or second factor from the existing user, so a compromised mailbox cannot claim an account.

1. Open Authentication → Flows, find first broker login and choose Action → Duplicate. Name the copy verid-first-login.
2. In the copy, set Verify existing account by Email to Disabled. Leave every other requirement unchanged, including the conditional 2FA and organization branches.
3. Open Identity providers → verid, scroll to Advanced settings, set First login flow override to verid-first-login, keep Sync mode at Force, and click Save.

A new wallet identity now creates a new user. A wallet identity whose email matches an existing user triggers Confirm link existing account, followed by that user's password or second factor.

Store the wallet claimsCopy Anchor Link

Keycloak imports the standard email claim into the user's profile, which the user can edit. Store the wallet claims separately as attributes that only administrators can read or change, so a profile edit can never pass as a verified value.

1. Open Realm settings → User profile → Create attribute and create the four attributes below. For each, set Multivalued = Off, Required field = Off, Enabled when = Always, and restrict both Who can edit? and Who can view? to Admin.

2. Open Identity providers → verid → Mappers → Add mapper and create the four mappers below. After saving a mapper, return to Mappers and click Add mapper for the next one. Leave Allow Nullable Property off.

With Force, every wallet login overwrites the four attributes and removes a value whose claim is absent. Boolean claims are stored as the strings true and false.

Test the loginCopy Anchor Link

1. Close every private browser window, then open a new private window so no Keycloak session exists.
2. Open <keycloak-base-url>/realms/<realm>/account/. If the Account Console shows a welcome page, click Sign in.
3. Click Log in with Digital Identity Wallet and approve the request in your wallet with the email and phone credentials.
4. Complete any profile fields Keycloak asks for. You return to the Account Console signed in.
5. Open Account security → Linked accounts and confirm the provider is linked.

6. In the Admin Console, open Users, select the new user and check Attributes.

If you have no wallet with email and phone credentials yet, use Yivi. It issues both credentials to any wallet holder after verifying the address and number inside the app, so a personal Yivi wallet is enough for this test.

Deliver claims to your applicationsCopy Anchor Link

Expose the wallet attributes through a dedicated client scope and assign it only to the applications that need them. Shared scopes such as the built-in email scope expose the editable profile email, not the verified wallet copy.

1. Open Client scopes → Create client scope. Name it verid-wallet-claims, set Type to None and Protocol to OpenID Connect, and save.
2. Open the scope's Mappers tab, choose Configure a new mapper → User Attribute, and create one mapper per attribute. Set Add to ID token = On, Add to access token = Off and Add to userinfo = Off.

3. Open Clients, select the application, open its Client scopes tab, click Add client scope, pick verid-wallet-claims and add it as Default.
4. Open Clients → your application → Client scopes → Evaluate, select the test user and open Generated ID token. The four wallet_* claims are present. Repeat for an application without the scope and confirm they are absent.

Use the claim names your application expects. Enable Add to access token or Add to userinfo only for an application that reads claims there.