
# 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

```properties
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
```

```dart
// 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`, `exp` and `iat` are present;
- `iss` equals the registration's issuer (when it has one);
- `aud` contains the client id;
- with several audiences, `azp` is present; when present, it is the client id;
- `exp` has not passed and `iat` is not in the future, each with 60 seconds of skew;
- the `nonce` is 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](../spring-boot-starter-security/oauth2-login.md)).

## In Spring (Java)

The types are Spring Security's; the user services return `Future`s. 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.

## See also

- [Registrations](registrations.md)
- [Single sign-on](../spring-boot-starter-security/oauth2-login.md)
- [JWT resource servers](../spring-boot-starter-security/jwt.md)
