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.
- The provider's metadata must name exactly the configured issuer, or the registration is refused.
- A failed discovery is tried again 10 seconds later at the earliest; until then every use gets its error at once, so a provider that is down never gets one request per login. The 10 seconds use a monotonic clock: a device clock set back does not stretch them.
- The security starter's resource server finds the metadata with the same code (
ClientRegistrations.configurationForIssuerLocation).
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:
response_mode=form_postwhen the login asks for the name or the e-mail: the provider's page posts the response to the redirect URI.response-mode=form_postputs it into the authorization request; only a server'soauth2Login()receives it, over HTTPS (see Single sign-on). An app's login window cannot.- A client secret that is a JWT the server signs ES256 with the team's key, at most six months valid:
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.