Sign in with NobleID on Keycloak

Register on NobleID

1. In Dashboard → OAuth apps, register a confidential app. You need two-step login on your NobleID to do this.
2. Add this redirect URI, with your own host:
   https://sso.example.org/realms/<realm>/broker/nobleid/endpoint
   Keycloak shows this URL, read-only, when you add the provider. The alias is part of it, so set the alias first. Tick ORCID iD too if you will map it.
3. Tick these scopes: OpenID (always on), Profile profile, Email email. The platform asks for these, and sign-in stops if it asks for a scope the app does not have.
4. Copy the client ID and the client secret. The secret is shown once.

The app works at once. Until NobleID verifies it, people see a “not verified” notice on the consent screen.

1. Add the provider

Keycloak runs the sign-in: people choose NobleID on the Keycloak login page, and your applications keep talking to Keycloak. This is also the working route for platforms whose own OIDC client cannot handle NobleID, such as OJS.

Identity providers → Add provider → OpenID Connect v1.0:

Fill in the client details:

Discovery fills in the rest. Click Add, then check these values on the provider's settings page:

Turn on PKCE yourself. Discovery does not set it. On the provider's settings page, set Use PKCE On and PKCE Method S256, then Save. Keycloak's default method is plain, which NobleID refuses.

Keycloak checks NobleID's ES256 ID tokens with the JWKS URL. No algorithm setting is needed.

2. Advanced settings

Also turn on Realm settings → Login → Verify email. Trust Email only copies email_verified. Without Verify email, a NobleID user with an unconfirmed address gets straight in with that address on their Keycloak account.

3. Mappers

Identity providers → nobleid → Mappers → Add mapper. Keycloak's default username is NobleID's preferred_username, which can change and can collide with a local username. Use sub instead:

To keep NobleID claims, add an Attribute Importer for each, with Sync mode override Force:

Declare these attributes under Realm settings → User profile → Create attribute, viewable by administrators and editable by nobody. Otherwise Keycloak ignores them. To pass them on to your applications, add a User Attribute mapper to a client scope.

4. First sign-in and existing accounts

The default first broker login flow is the safe one. It creates a new user when nobody has the same email or username. If someone does, it asks the person to prove they own that account, by email or by signing in to it, before linking.

Do not build a flow with Automatically Set Existing User. It links whatever account has the matching email, without proof.

To admit only people whose identity check passed, set Verify essential claim On, Essential claim identity_verified, Essential claim value true. The check reads the ID token, which carries identity_verified when the app asks for profile.

With Logout URL set, signing out of Keycloak also ends the NobleID session. Keycloak sends the person to NobleID, which asks them to confirm, and NobleID sends them back to https://sso.example.org/realms/<realm>/broker/nobleid/endpoint/logout_response with Keycloak's state. Add that URL to the app's sign-out return URLs in the NobleID dashboard. To end only the Keycloak session, empty Logout URL; the person then stays signed in at nobleid.org. Keep Backchannel logout off: it makes Keycloak call the Logout URL from its server, and NobleID's sign-out needs the person's browser.

Fill the profile from NobleID

Add an Attribute Importer per attribute and declare each attribute, as in step 3. Keycloak reads a nested claim with a dot: affiliation.name.

With Sync mode override Force, Keycloak overwrites the attribute at every sign-in. Use Import (first sign-in only) for anything people edit in Keycloak.

Add orcid and affiliations to the provider's Scopes field, and tick ORCID iD and Affiliations on your app.

Every claim, and how to fill a profile without overwriting what people edit: Fill your app's profile from NobleID.

Before you go live

• Sign in once with your own NobleID. People need a first and last name on their NobleID profile to sign in; NobleID asks for it if it is missing.
• Key accounts on sub. Link to an existing account by email only when email_verified is true.
• Remove any localhost redirect URIs from the app.
• Keep the client secret out of version control.

NobleID values