
# 認可済みクライアント

`OAuth2AuthorizedClient` は、一つの登録についての一つのプリンシパルのトークンを保持します。アクセストークンと、場合によってはリフレッシュトークンと ID トークンです。`OAuth2AuthorizedClientManager` は、アクセストークンが有効な認可済みクライアントを渡します。クライアントクレデンシャルのトークンを取得するか、期限切れが近いものをリフレッシュし、結果を `OAuth2AuthorizedClientService` に保存します。

## 使う理由

トークンは期限が切れます。それに同時に気付いた十の呼び出しが、トークンを十回リフレッシュしてはいけません (二度送られたローテーションするリフレッシュトークンは拒否され、ユーザーはログアウトされます)。プロバイダーが拒否したリフレッシュは保存されたクライアントを取り除かなければなりませんが、到達できないプロバイダーではそうしてはいけません。マネージャーは、すべての呼び出し元のためにこれを一回だけ行います。

## 例

```dart
@Service()
class PartnerApi {
  PartnerApi(this.manager, this.transport);

  final OAuth2AuthorizedClientManager manager;
  final HttpTransport transport;

  Future<HttpResponse> orders() async {
    final client = await manager.authorize(
      OAuth2AuthorizeRequest.withClientRegistrationId('partner')
          .principal(anonymousAuthentication)   // クライアントクレデンシャル: ユーザーなし
          .build(),
    );
    final request = HttpRequest(
      method: HttpMethod.get,
      url: Uri.parse('https://api.partner.example/orders'),
    )..headers.set('Authorization', 'Bearer ${client!.accessToken.tokenValue}');
    return transport.send(request);
  }
}
```

Feign クライアントでは、インターセプターがこれを行います ([Feign の呼び出しのトークン](feign.md) を参照)。

## マネージャー

| 型 | 役割 |
|---|---|
| `OAuth2AuthorizedClientManager` | `authorize(request)`: 有効な認可済みクライアント。できない場合は `null` (例えば `authorization_code` の登録でまだログインしていない)。 |
| `OAuth2AuthorizeRequest.withClientRegistrationId(id)`、`.withAuthorizedClient(client)` | リクエスト (新規、または再認可): `.principal(authentication)` か `.principalName('name')`、そして `.build()`。 |
| `AuthorizedClientServiceOAuth2AuthorizedClientManager` | 登録のリポジトリと認可済みクライアントのサービスの上のデフォルトのマネージャー。 |
| `OAuth2AuthorizedClientProvider` | 認可の一つの方法: `AuthorizationCodeOAuth2AuthorizedClientProvider`、`RefreshTokenOAuth2AuthorizedClientProvider`、`ClientCredentialsOAuth2AuthorizedClientProvider`。`DelegatingOAuth2AuthorizedClientProvider` か `OAuth2AuthorizedClientProviderBuilder` で組み合わせる。 |

デフォルトのマネージャーが行うこと:

- `authorization_code` のクライアントは、アクセストークンが 1 分以内に期限切れになる場合、そのリフレッシュトークンでリフレッシュされます。
- `client_credentials` のクライアントは、同じように新しいトークンを得ます。
- 一つの登録とプリンシパルについての同時の呼び出し元は一つの認可を共有するため、ローテーションするリフレッシュトークンが二度送られることはありません。
- プロバイダーが拒否したリフレッシュ (`invalid_grant`、`invalid_token`) は保存されたクライアントを取り除きます。到達できないプロバイダーでは取り除きません。
- リフレッシュされた ID トークンは、OpenID Connect Core §12.2 のとおり、古いものと照合されます (同じ発行者と subject)。

## OAuth2AuthorizedClient

| メンバー | 意味 |
|---|---|
| `clientRegistration` | 登録。 |
| `principalName` | 誰のトークンか。 |
| `accessToken` | `OAuth2AccessToken`: `tokenValue`、`tokenType` (`bearer` または `dpop`)、`issuedAt`、`expiresAt`、`scopes`。 |
| `refreshToken` | リフレッシュトークン (あれば)。 |
| `idToken` | ID トークン。リフレッシュで新しいものをチェックでき、セッションのないログアウト (再起動後のアプリ) で `id_token_hint` として送れるよう保持される。 |

## 保存

`OAuth2AuthorizedClientService` は、登録とプリンシパルごとに認可済みクライアントを保持します: `loadAuthorizedClient`、`saveAuthorizedClient`、`removeAuthorizedClient`。

- スターターのものは、Spring Boot と同じく `InMemoryOAuth2AuthorizedClientService` です。クライアントクレデンシャルのトークンに適しており、プログラムが止まると忘れられます。
- 別の場所 (データベース) に保持するには、`OAuth2AuthorizedClientService` Bean を宣言してください。
- `spring_boot_starter_flutter_security` は、プラットフォームのセキュアストレージの上のものを宣言します。そのため、アプリのログインは再起動後も残ります。
- サーバーでは、`oauth2Login()` がセキュリティスターターの `OAuth2AuthorizedClientRepository` を通じて、ユーザーのトークンをセッションに保持します。

## トークンクライアント

マネージャーは、三つの `OAuth2AccessTokenResponseClient` Bean を通じてトークンエンドポイントを呼びます。それぞれ `spring_web_dart` の `HttpTransport` の上で動きます。

| Bean | グラント |
|---|---|
| `DefaultAuthorizationCodeTokenResponseClient` | PKCE の verifier を使う `authorization_code` (PKCE はすべての `authorization_code` の登録で有効)。 |
| `DefaultRefreshTokenTokenResponseClient` | `refresh_token`。 |
| `DefaultClientCredentialsTokenResponseClient` | `client_credentials`。 |

これらは、登録が指定するとおりにクライアントを認証し (`client_secret_basic`、`client_secret_post`、`none`、または JWT のシークレット)、DPoP の登録では DPoP の証明を送ります。コードのトークンリクエストは、認可リクエストに `redirect_uri` がなかった場合にはそれを省きます (RFC 6749 §4.1.3)。

## 他のリクエストでのトークン

スターターが行わないリクエスト (独自の `HttpTransport` の呼び出し、WebSocket のハンドシェイク) には、`OAuth2AccessTokenHeaders` がトークンの種類に応じたヘッダーを書きます: `Bearer <token>`、または `DPoP <token>` と新しい証明です。

```dart
// WebSocket のハンドシェイクでのログイン中のユーザーのトークン。
final client = await manager.authorize(request);
final headers = await OAuth2AccessTokenHeaders(dPoPKey: key).of(
  client!.accessToken,
  method: 'GET',
  url: handshake.url, // wss://api.example.com/ws/chat
);
headers.forEach(handshake.headers.set);
```

`ws` / `wss` の URL は、ハンドシェイクが HTTP の `GET` であるため、証明の `htu` には `http` / `https` として入ります。ブラウザーはハンドシェイクにヘッダーを設定できません。ページは代わりにセッション Cookie を送ります。

## Spring (Java) との対応

```java
OAuth2AuthorizedClient client = manager.authorize(
    OAuth2AuthorizeRequest.withClientRegistrationId("partner").principal("shop").build());
```

型は Spring Security のもので、すべての呼び出しが `Future` を返します。デフォルトのマネージャーはそのプロバイダーを必要とし (Spring のデフォルトはクライアントクレデンシャルだけ)、登録とプリンシパルごとに一度に一つの認可を実行し、`invalid_grant` や `invalid_token` の後に保存されたクライアントを取り除きます。トークンクライアントは、`HttpTransport` の上の Spring 7 の `RestClient*TokenResponseClient` です。まだないもの: データベースを使うサービス、HTTP クライアントの `@ClientRegistrationId`。

## 関連項目

- [Feign の呼び出しのトークン](feign.md)
- [登録](registrations.md)
- [DPoP](dpop.md)
