OpenID Connect
With openid among a registration's scopes, a login is an OpenID Connect login: the provider returns an ID token that says who the user is, checked by the client. The user services load the user (OAuth2User, or OidcUser with OpenID Connect) from the ID token and the user-info endpoint.
Why
An access token says what the client may do; it does not say who the user is. An ID token does, but only after strict checks: a token issued to another application, an old one, or one from another provider must never log a user in. The validator does those checks on every ID token.
Example
spring.security.oauth2.client.registration.keycloak.client-id=neon-web
spring.security.oauth2.client.registration.keycloak.client-secret=${KEYCLOAK_SECRET}
spring.security.oauth2.client.registration.keycloak.scope=openid,profile,email
spring.security.oauth2.client.provider.keycloak.issuer-uri=https://login.example.com/realms/neon
// On a server with oauth2Login(): the logged-in user.
@GetMapping('/api/me')
Map<String, Object?> me(@AuthenticationPrincipal() OidcUser user) => {
'sub': user.subject,
'name': user.fullName,
'email': user.emailVerified == true ? user.email : null,
};
Users
| Type | What it is |
|---|---|
OAuth2User |
A user of an OAuth 2.0 login: attributes (the user-info answer), authorities, name (the user-name-attribute). |
OidcUser |
An OpenID Connect user: also the idToken, the userInfo and the standard claims. |
DefaultOAuth2UserService |
Loads an OAuth2User from the user-info endpoint. |
OidcUserService |
Loads an OidcUser: the ID token, then the user info, whose sub must be the ID token's. |
Standard claims of an OidcUser (and OidcIdToken): subject, fullName, givenName, familyName, middleName, nickName, preferredUsername, profile, picture, website, email, emailVerified, gender, birthdate, zoneInfo, locale, phoneNumber, phoneNumberVerified, address, updatedAt; and of the ID token: issuer, audience, expiresAt, issuedAt, authenticatedAt, nonce, authorizedParty.
Keep users by subject, never by e-mail: an address can change owner, and another provider may send one it never verified.
The checks of an ID token
OidcIdTokenValidator checks, as OpenID Connect Core §3.1.3.7 says:
iss,sub,aud,expandiatare present;issequals the registration's issuer (when it has one);audcontains the client id;- with several audiences,
azpis present; when present, it is the client id; exphas not passed andiatis not in the future, each with 60 seconds of skew;- the
nonceis the SHA-256 hash of the value the login sent, so a token cannot be replayed into another login.
A refreshed ID token is checked against the old one: the same issuer and subject (§12.2).
The ID token decoders
| Decoder | Checks |
|---|---|
TokenEndpointOidcIdTokenDecoder (the starter's bean) |
The claims, but not the signature: the token comes straight from the token endpoint over TLS, which OpenID Connect Core §3.1.3.7 allows. Tokens with alg: none are refused all the same. |
The security starter's OidcIdTokenDecoderFactory |
Replaces it on a server: the signature with the provider's JWK Set, then the claims, as Spring does. |
JwkSetOidcIdTokenDecoder |
For ID tokens that did not come from the token endpoint, such as Apple's identity token from the device's sheet. |
Declare an OidcIdTokenDecoder bean of your own for any other rule.
JwkSetOidcIdTokenDecoder
It checks the signature with the registration's JWK Set: RS256 by default, ES256 on request; alg: none, HS*, keys inside the token and weak RSA keys are refused; an unknown kid fetches the keys again, at most once a minute (on a monotonic clock). The typ header must be JWT (any case), blank or absent: a logout+jwt, at+jwt or secevent+jwt token signed with the same keys is refused. Then the claims, as above.
Authorities
A login's authorities are OIDC_USER (or OAUTH2_USER) and SCOPE_* for the granted scopes. A GrantedAuthoritiesMapper bean adds your own roles (see Single sign-on).
In Spring (Java)
The types are Spring Security's; the user services return Futures. Spring's OidcIdTokenDecoderFactory always checks the signature; this package's default trusts TLS, and the security starter's bean checks it on a server. JWT signatures are checked here only in JwkSetOidcIdTokenDecoder; the full JOSE code is the security starter's.