登録

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

使う理由

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

例

# 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>。型とデフォルトは すべてのプロパティ にあります。

キー 意味
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 を参照)。
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 はアプリケーションの起動中にプロバイダーに問い合わせます)。そのため、アプリケーション、特にアプリは、プロバイダーに到達できない間でも起動します。

平文の 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 には、他のプロバイダーにはない二つのものが必要です。

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 を参照)。

コードでの登録

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

@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 のグラント。

関連項目