
# 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 `ClientRegistration`s that the token clients, the logins and the Feign interceptor share.

## Example

```properties
# 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](properties.md).

| 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](dpop.md)). |
| `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_post`** when the login asks for the name or the e-mail: the provider's page posts the response to the redirect URI. `response-mode=form_post` puts it into the authorization request; only a server's `oauth2Login()` receives it, over HTTPS (see [Single sign-on](../spring-boot-starter-security/oauth2-login.md)). 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:

```properties
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 `JwtClientSecret`s 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](openid-connect.md)).

## Registrations in code

Declare a `ClientRegistrationRepository` bean to keep registrations elsewhere:

```dart
@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

- [All properties](properties.md)
- [Authorized clients](authorized-clients.md)
- [Single sign-on](../spring-boot-starter-security/oauth2-login.md)
