Registrations

A registration is one client of one provider: its id and secret at the provider, the grant it uses, the scopes it asks for. A provider is where the endpoints are: an issuer whose metadata is discovered, or each endpoint by hand. Both are Spring Boot's spring.security.oauth2.client.* properties.

Why

The same application may call a partner API with client credentials, log users in with Google, and log them in with the company's Keycloak. Each is a registration with a few properties; the starter turns them into ClientRegistrations that the token clients, the logins and the Feign interceptor share.

Example

# Keycloak: everything discovered from the issuer.
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

# GitHub: a common provider, only the client.
spring.security.oauth2.client.registration.github.client-id=Iv1.8a61f9b3a7aba766
spring.security.oauth2.client.registration.github.client-secret=${GITHUB_SECRET}

# A partner API, server to server, endpoints by hand.
spring.security.oauth2.client.registration.partner.client-id=shop
spring.security.oauth2.client.registration.partner.client-secret=${PARTNER_SECRET}
spring.security.oauth2.client.registration.partner.authorization-grant-type=client_credentials
spring.security.oauth2.client.registration.partner.scope=orders.read
spring.security.oauth2.client.registration.partner.provider=partner-id
spring.security.oauth2.client.provider.partner-id.token-uri=https://id.partner.example/oauth2/token

Registration keys

spring.security.oauth2.client.registration.<id>.<key>; types and defaults are on All properties.

Key Meaning
client-id The client's id at the provider. Required.
client-secret The secret of a confidential client (a server); none for an app.
client-authentication-method client_secret_basic, client_secret_post or none. Default: none without a secret for authorization_code, else client_secret_basic.
authorization-grant-type authorization_code (logins) or client_credentials (server to server). Default: authorization_code with an issuer-uri or a known provider; required otherwise.
redirect-uri A template: {baseUrl}, {registrationId}, {action}... Default: {baseUrl}/login/oauth2/code/{registrationId}.
scope A comma list or a YAML list; openid makes it an OpenID Connect login.
client-name The name on the login page.
provider The provider id, when it is not the registration id, or a known one.
dpop auto, true, false: tokens bound to the client's key (see DPoP).
response-mode query or form_post.
native-sign-in none or apple: apps sign in with Apple's sheet.
client-secret-jwt.* A client secret that is a JWT signed with the client's key.

Provider keys

spring.security.oauth2.client.provider.<id>.<key>:

Key Meaning
issuer-uri Everything else is discovered: /.well-known/openid-configuration, then RFC 8414. The metadata's issuer must equal it.
authorization-uri, token-uri, user-info-uri, jwk-set-uri Each endpoint by hand, or to override the metadata.
user-info-authentication-method How the token goes to the user-info endpoint: header (default), form, query.
user-name-attribute The attribute that names the user (sub, login, email).

Common providers

A registration named after one of them (or with provider=<name>) gets its endpoints, scopes and user name attribute from CommonOAuth2Provider, exactly as in Spring:

Provider Kind Scopes User named by
google OpenID Connect openid profile email sub
github OAuth 2.0 read:user id
facebook OAuth 2.0, secret in the form public_profile email id
okta OpenID Connect; set provider.okta.issuer-uri openid profile email sub
apple OpenID Connect, client_secret_post, form_post (an addition) openid name email sub

An authorization_code registration without a client secret and without client-authentication-method is a public client (none), even for a common provider that says client_secret_basic.

Discovery

Discovery happens at the first use, not at startup (Spring Boot asks the provider while the application starts), so an application, and an app above all, starts while the provider cannot be reached.

Plain http is warned about

An issuer, authorization, token, JWK Set, user-info or redirect URI with http:// on a host other than localhost, 127.0.0.1 or [::1] is logged as a warning once per registration (logger spring.security.oauth2.client.registration). The registration still works; but over http:// anyone on the way can read or change the tokens.

Redirect URIs

Redirect URIs are Spring's templates. expandRedirectUri(registration, baseUrl:) fills them in with the server's address, or http://127.0.0.1 where there is none (an app's loopback redirect). An app may use a custom scheme: neonbooks:/oauth2/callback.

Apple: form post and a JWT client secret

Sign in with Apple needs two things other providers do not:

spring.security.oauth2.client.registration.apple.client-id=books.neon.web
spring.security.oauth2.client.registration.apple.client-authentication-method=client_secret_post
spring.security.oauth2.client.registration.apple.client-secret-jwt.issuer=ABCDE12345
spring.security.oauth2.client.registration.apple.client-secret-jwt.key-id=XYZ987KEY1
spring.security.oauth2.client.registration.apple.client-secret-jwt.private-key-location=file:/run/secrets/AuthKey_XYZ987KEY1.p8
client-secret-jwt. key Default Meaning
issuer required The JWT's iss (Apple: the team id).
key-id required The JWT's kid (Apple: the key id).
private-key-location The PKCS #8 key (Apple's .p8), file: or resources:. Either this or private-key is required.
private-key The PEM itself, from an environment variable (\n escapes allowed).
audience the provider's issuer-uri The JWT's aud.
lifetime 1h How long each JWT is valid, from 1m to 180d; made again when a tenth is left.

The clientSecretResolver bean (a JwtClientSecretResolver) makes JwtClientSecrets per request. The key is read at the first token request, and is never logged, shown by toString or put into an error. A registration with a JWT secret but client-authentication-method=none is refused.

The apps' side checks Apple's identity token, which comes from the operating system, with JwkSetOidcIdTokenDecoder (see OpenID Connect).

Registrations in code

Declare a ClientRegistrationRepository bean to keep registrations elsewhere:

@Bean()
ClientRegistrationRepository registrations() => InMemoryClientRegistrationRepository([
      CommonOAuth2Provider.google
          .getBuilder('google')
          .clientId('1234.apps.googleusercontent.com')
          .build(),
      ClientRegistration.withRegistrationId('partner')
          .clientId('shop')
          .clientSecret(partnerSecret)
          .authorizationGrantType(AuthorizationGrantType.clientCredentials)
          .tokenUri('https://id.partner.example/oauth2/token')
          .scope(['orders.read'])
          .build(),
    ]);

findByRegistrationId(id) returns a Future.

In Spring (Java)

The keys and CommonOAuth2Provider are Spring Boot's and Spring Security's. Differences: discovery at the first use; http:// warnings; dpop, response-mode, native-sign-in, client-secret-jwt.* and the apple provider are additions. Not here yet: private_key_jwt, client_secret_jwt (client_assertion), tls_client_auth, and the password, device, token exchange and JWT bearer grants.

See also