登録
登録とは、一つのプロバイダーの一つのクライアントです。プロバイダーでのその 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 はアプリケーションの起動中にプロバイダーに問い合わせます)。そのため、アプリケーション、特にアプリは、プロバイダーに到達できない間でも起動します。
- プロバイダーのメタデータは、設定された発行者を正確に示さなければなりません。そうでなければ登録は拒否されます。
- 失敗した検出は、早くても 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()だけです (シングルサインオン を参照)。アプリのログインウィンドウでは受け取れません。 - JWT であるクライアントシークレット: サーバーがチームの鍵で ES256 署名し、有効期間は最大 6 か月です。
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 のグラント。