
# 登録

登録とは、一つのプロバイダーの一つのクライアントです。プロバイダーでのその ID とシークレット、使うグラント、求めるスコープです。プロバイダーはエンドポイントのある場所です。メタデータが検出される発行者か、手で指定した各エンドポイントです。どちらも Spring Boot の `spring.security.oauth2.client.*` プロパティです。

## 使う理由

同じアプリケーションが、クライアントクレデンシャルでパートナーの API を呼び、Google でユーザーをログインさせ、会社の Keycloak でもログインさせることがあります。それぞれがいくつかのプロパティを持つ登録です。スターターはそれらを、トークンクライアント、ログイン、Feign のインターセプターが共有する `ClientRegistration` に変換します。

## 例

```properties
# Keycloak: すべてを発行者から検出する。
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: 共通のプロバイダー。クライアントだけ。
spring.security.oauth2.client.registration.github.client-id=Iv1.8a61f9b3a7aba766
spring.security.oauth2.client.registration.github.client-secret=${GITHUB_SECRET}

# パートナーの API、サーバーからサーバー、エンドポイントは手で指定。
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
```

## 登録のキー

`spring.security.oauth2.client.registration.<id>.<key>`。型とデフォルトは [すべてのプロパティ](properties.md) にあります。

| キー | 意味 |
|---|---|
| `client-id` | プロバイダーでのクライアントの ID。必須。 |
| `client-secret` | コンフィデンシャルクライアント (サーバー) のシークレット。アプリにはない。 |
| `client-authentication-method` | `client_secret_basic`、`client_secret_post`、`none`。デフォルト: `authorization_code` でシークレットがなければ `none`、それ以外は `client_secret_basic`。 |
| `authorization-grant-type` | `authorization_code` (ログイン) または `client_credentials` (サーバーからサーバー)。デフォルト: `issuer-uri` か既知のプロバイダーがあれば `authorization_code`。それ以外は必須。 |
| `redirect-uri` | テンプレート: `{baseUrl}`、`{registrationId}`、`{action}` など。デフォルト: `{baseUrl}/login/oauth2/code/{registrationId}`。 |
| `scope` | カンマ区切りのリストか YAML のリスト。`openid` があると OpenID Connect のログインになる。 |
| `client-name` | ログインページでの名前。 |
| `provider` | プロバイダーの ID。登録 ID や既知のものでない場合に指定する。 |
| `dpop` | `auto`、`true`、`false`: クライアントの鍵にバインドされたトークン ([DPoP](dpop.md) を参照)。 |
| `response-mode` | `query` または `form_post`。 |
| `native-sign-in` | `none` または `apple`: アプリは Apple のシートでサインインする。 |
| `client-secret-jwt.*` | クライアントの鍵で署名した JWT であるクライアントシークレット。 |

## プロバイダーのキー

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

| キー | 意味 |
|---|---|
| `issuer-uri` | それ以外はすべて検出される: `/.well-known/openid-configuration`、次に RFC 8414。メタデータの `issuer` はこれと等しくなければならない。 |
| `authorization-uri`、`token-uri`、`user-info-uri`、`jwk-set-uri` | 各エンドポイントを手で指定するか、メタデータを上書きする。 |
| `user-info-authentication-method` | トークンをユーザー情報エンドポイントに渡す方法: `header` (デフォルト)、`form`、`query`。 |
| `user-name-attribute` | ユーザーを表す属性 (`sub`、`login`、`email`)。 |

## 共通のプロバイダー

これらのいずれかの名前を持つ (または `provider=<name>` を持つ) 登録は、Spring とまったく同じく、そのエンドポイント、スコープ、ユーザー名の属性を `CommonOAuth2Provider` から得ます。

| プロバイダー | 種類 | スコープ | ユーザーを表すもの |
|---|---|---|---|
| `google` | OpenID Connect | `openid profile email` | `sub` |
| `github` | OAuth 2.0 | `read:user` | `id` |
| `facebook` | OAuth 2.0、シークレットはフォームで | `public_profile email` | `id` |
| `okta` | OpenID Connect。`provider.okta.issuer-uri` を設定する | `openid profile email` | `sub` |
| `apple` | OpenID Connect、`client_secret_post`、`form_post` (追加されたもの) | `openid name email` | `sub` |

クライアントシークレットも `client-authentication-method` もない `authorization_code` の登録は、`client_secret_basic` を指定する共通のプロバイダーであっても、パブリッククライアント (`none`) です。

## 検出

**検出は起動時ではなく最初の使用時に行われます** (Spring Boot はアプリケーションの起動中にプロバイダーに問い合わせます)。そのため、アプリケーション、特にアプリは、プロバイダーに到達できない間でも起動します。

- プロバイダーのメタデータは、設定された発行者を正確に示さなければなりません。そうでなければ登録は拒否されます。
- 失敗した検出は、早くても 10 秒後に再試行されます。それまでは、すべての使用が即座にそのエラーを受け取ります。そのため、停止しているプロバイダーがログインごとにリクエストを受けることはありません。10 秒は単調増加の時計で計られます。デバイスの時計を戻しても延びません。
- セキュリティスターターのリソースサーバーは、同じコード (`ClientRegistrations.configurationForIssuerLocation`) でメタデータを見つけます。

## 平文の http は警告される

`localhost`、`127.0.0.1`、`[::1]` 以外のホストで `http://` を使う発行者、認可、トークン、JWK Set、ユーザー情報、リダイレクトの URI は、登録ごとに一度、警告としてログに出ます (ロガー `spring.security.oauth2.client.registration`)。登録はそのまま動きますが、`http://` では経路上の誰でもトークンを読んだり変更したりできます。

## リダイレクト URI

リダイレクト URI は Spring のテンプレートです。`expandRedirectUri(registration, baseUrl:)` は、それをサーバーのアドレス、なければ `http://127.0.0.1` (アプリのループバックのリダイレクト) で埋めます。アプリは独自のスキームを使えます: `neonbooks:/oauth2/callback`。

## Apple: フォーム POST と JWT のクライアントシークレット

Sign in with Apple には、他のプロバイダーにはない二つのものが必要です。

- ログインが名前やメールアドレスを求める場合の **`response_mode=form_post`**: プロバイダーのページが応答をリダイレクト URI に POST します。`response-mode=form_post` はそれを認可リクエストに入れます。それを受け取れるのは、HTTPS 上のサーバーの `oauth2Login()` だけです ([シングルサインオン](../spring-boot-starter-security/oauth2-login.md) を参照)。アプリのログインウィンドウでは受け取れません。
- **JWT であるクライアントシークレット**: サーバーがチームの鍵で ES256 署名し、有効期間は最大 6 か月です。

```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.` のキー | デフォルト | 意味 |
|---|---|---|
| `issuer` | 必須 | JWT の `iss` (Apple: チーム ID)。 |
| `key-id` | 必須 | JWT の `kid` (Apple: 鍵 ID)。 |
| `private-key-location` | | PKCS #8 の鍵 (Apple の `.p8`)。`file:` または `resources:`。これか `private-key` のどちらかが必須。 |
| `private-key` | | 環境変数からの PEM そのもの (`\n` のエスケープを使える)。 |
| `audience` | プロバイダーの issuer-uri | JWT の `aud`。 |
| `lifetime` | `1h` | 各 JWT の有効期間。`1m` から `180d`。残りが 10 分の 1 になると作り直される。 |

`clientSecretResolver` Bean (`JwtClientSecretResolver`) は、リクエストごとに `JwtClientSecret` を作ります。鍵は最初のトークンリクエストで読まれ、ログに出ることも、`toString` で表示されることも、エラーに入ることもありません。JWT のシークレットを持ちながら `client-authentication-method=none` の登録は拒否されます。

アプリ側は、オペレーティングシステムから来る Apple のアイデンティティトークンを `JwkSetOidcIdTokenDecoder` でチェックします ([OpenID Connect](openid-connect.md) を参照)。

## コードでの登録

登録を別の場所に保持するには、`ClientRegistrationRepository` Bean を宣言します。

```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)` は `Future` を返します。

## Spring (Java) との対応

キーと `CommonOAuth2Provider` は Spring Boot と Spring Security のものです。違い: 検出は最初の使用時。`http://` の警告。`dpop`、`response-mode`、`native-sign-in`、`client-secret-jwt.*`、`apple` プロバイダーは追加されたもの。まだないもの: `private_key_jwt`、`client_secret_jwt` (`client_assertion`)、`tls_client_auth`、そしてパスワード、デバイス、トークン交換、JWT Bearer のグラント。

## 関連項目

- [すべてのプロパティ](properties.md)
- [認可済みクライアント](authorized-clients.md)
- [シングルサインオン](../spring-boot-starter-security/oauth2-login.md)
