アプリのログイン
OAuth2LoginService はアプリのログインです。スマートフォンやデスクトップでは NativeOAuth2LoginService で、OAuth 2.0 for Native Apps (RFC 8252) の認可コードフローと PKCE を使うパブリッククライアントであり、OAuth2 クライアントの登録 (spring.security.oauth2.client.*) の上に組み立てられています。三つの呼び出し login、restore、logout が、ログインの一生を担います。
使う理由
Spring Security は、サーバー上でブラウザーをログインさせます。その oauth2Login() はコンフィデンシャルクライアントで、トークンをセッションに保持します。アプリはシークレットを保持できない (誰でもバイナリーから取り出せる) ので、PKCE で保護されたパブリッククライアントとして自分でログインし、トークンをデバイスに保持します。このサービスは、Spring のサーバー側のログインのすべてのチェックとともにそれを行うので、アプリのコードは三行のままです。
例
@Service()
class Account {
Account(this._login);
final OAuth2LoginService _login;
// 起動時: 前回のユーザーを、新しいトークンとともに。
Future<Authentication?> start() => _login.restore();
// システムのログインウィンドウ。ユーザー、または例外。
Future<Authentication?> signIn() => _login.login('keycloak');
// トークンを取り消して忘れる。プロバイダーのセッションは残る。
Future<void> signOut() => _login.logout();
// 「アカウントの切り替え」: プロバイダーのセッションも終わらせる。
Future<void> switchAccount() => _login.logout(endSession: true);
}
spring:
security:
oauth2:
client:
registration:
keycloak:
client-id: neon-app
scope: openid,profile,email
redirect-uri: dev.neon.books:/oauth2/callback
provider:
keycloak:
issuer-uri: https://id.neon.books/realms/neon
client-secret は省略してください。そうすると登録はパブリッククライアント (client-authentication-method=none) になり、PKCE がそのコードを保護します。
プラットフォームごと
| プラットフォーム | ログインウィンドウ | リダイレクト URI | トークン |
|---|---|---|---|
| iOS、macOS | ASWebAuthenticationSession (Safari のシート)。native-sign-in=apple では Sign in with Apple 独自のシート |
アプリのスキーム (neonbooks:/oauth2/callback)、または関連付けられたドメインを使う https (iOS 17.4、macOS 14.4) |
キーチェーン |
| Android | Custom Tab。リダイレクトはパッケージのアクティビティが受け取る | アプリのスキーム、または https の App Link |
Android Keystore |
| Windows、Linux | デフォルトのブラウザー。リダイレクトは 127.0.0.1 上の一回限りのサーバーで受け取る (RFC 8252 §7.3) |
http://127.0.0.1/callback (任意の空いているポート) |
DPAPI、Secret Service |
| Web | なし: ページはサーバーのログインへ行く | サーバーのもの | なし: サーバーが保持する (Web: サーバーがログインする を参照) |
Windows と Linux では、プロバイダーは任意のポートのループバックのリダイレクトを受け付けなければなりません (Keycloak: http://127.0.0.1/*、Google: デスクトップのクライアント)。ポート付きのリダイレクト URI (http://127.0.0.1:8400/callback) はそれを保ちます。各プラットフォームのセットアップは トークンとログインウィンドウ にあります。
login
login('keycloak'):
- 認可リクエストを組み立てます。ランダムな
state(Random.secure()の 32 バイト)、PKCE のベリファイア (64 バイト) とそのS256のチャレンジ、そしてopenidではランダムなnonce(その SHA-256 ハッシュが送られます) です。 AuthorizationWindowでプロバイダーのログインページを開き、戻ってくるリダイレクトを待ちます。- リダイレクトをチェックします。リダイレクト URI に戻ってきたこと、送った
state(そうでなければinvalid_state_parameter)、存在するか告知されている場合はissパラメーター (RFC 9207、そうでなければinvalid_issuer)、そしてerror(access_deniedなど) またはcodeです。 - ベリファイアと実際に使ったリダイレクト URI でコードを交換します。
- OpenID Connect では、ID トークン (issuer、audience、
azp、60 秒のずれを許した有効期限と発行時刻、nonce) をチェックし、ユーザー情報を読み込みます。そのsubは ID トークンのものと一致しなければなりません。 - 権限を対応付け (
OIDC_USERまたはOAUTH2_USER、SCOPE_<scope>、次にGrantedAuthoritiesMapperBean)、OAuth2AuthenticationTokenをSecurityContextHolderに置き、トークンをOAuth2AuthorizedClientServiceに保存し、AuthenticationSuccessEventを発行します。
どの失敗も、error.errorCode が理由を示す OAuth2AuthenticationException です。閉じられたページは AuthorizationCancelledException です。追加のパラメーター (prompt=login) は additionalParameters に入れます。
ID トークンの署名はチェックされません。TLS 上でトークンエンドポイントから直接来るもので、OpenID Connect Core §3.1.3.7 がそれを許しているからです。それでも alg: none のトークンは拒否されます。署名もチェックするには、OidcIdTokenDecoder Bean を宣言してください。
restore
起動時の restore() は、保存されたトークンからユーザーを呼び戻し、一分以内に期限が切れる場合はトークンを更新します。
- プロバイダーが拒否したリフレッシュトークン (
invalid_grant) はユーザーをログアウトさせます。到達できないプロバイダーはそうしません (アプリはオフラインで起動します)。 - ユーザーは、アプリケーション独自の
OAuth2UserServiceが加えたものも含め、ログイン時の権限とともに戻ってきます (ログインの記録に保持されます。Spring のセッションがログイン時の認証を保持するのと同じく、ユーザーサービスは再び呼ばれません)。SCOPE_のものは現在のアクセストークンに従います。 - 設定から取り除かれた登録のログインの記録は、そのトークンとともに取り除かれます。
logout
logout() は、リフレッシュトークンとアクセストークンを取り消し (RFC 7009。プロバイダーが revocation_endpoint を持つ場合)、それらを忘れ、コンテキストをクリアし、LogoutSuccessEvent を発行します。すべてウィンドウなしでです。ユーザーはシステムのブラウザーではプロバイダーにログインしたままなので、次のログインではパスワードが不要な場合があります。これがモバイルアプリの通常のログアウトです。
logout(endSession: true)は、ログインウィンドウでプロバイダーのセッションも終わらせます (OpenID Connect の RP-initiated logout。ID トークンをid_token_hintとして使います)。「アカウントの切り替え」のためです。iOS と macOS は、そのウィンドウを独自の「... wants to use ... to Sign In」のプロンプトで告知します。- 安全なストレージが保存されたログインを削除できない場合でも、
logout()は実行中のアプリからユーザーをログアウトさせ、その後ストレージのエラーを投げます。そのため、アプリはデバイスがまだログインを保持していることをユーザーに伝えられます。
Bean
ブラウザーの外で、spring.security.oauth2.client.registration.* プロパティがあると、パッケージは次のものを宣言します。
| Bean | 型 | 意味 |
|---|---|---|
oauth2LoginService |
NativeOAuth2LoginService |
ログイン |
authorizedClientService |
SecretStoreOAuth2AuthorizedClientService |
各認可済みのクライアントを JSON として SecretStore に書き込む (oauth2.authorized-client.<registration>.<principal> の下に。ログインは restore が必要とするものを oauth2.login の下に保持する)。OAuth2 クライアントのインメモリーのものを置き換える |
appleIdSignIn |
AppleIdSignIn |
iOS と macOS での Sign in with Apple のシート (プロバイダー を参照) |
platformDPoPKey |
PlatformDPoPKey |
アプリの DPoP の鍵 (DPoP を参照) |
パッケージのすべての Bean は、アプリケーションがその型のものを宣言すると身を引きます。SecretStore、SecretTemplate、AuthorizationWindow、AppleIdSignIn、OAuth2AuthorizedClientService、OAuth2LoginService、PrincipalNotifier、DPoPKey、そして Web では BrowserPage と HttpTransport です。パッケージの中で、トークン、コード、ベリファイア、シークレットをログに出すものはありません。
トークンで API を呼ぶ
OAuth2 クライアントの Feign のインターセプターは、Feign クライアントと同じ名前の登録 (または spring.feign.oauth2.client-registration-id) のアクセストークンを送り、必要なら更新し、トークンが結び付けられていれば DPoP のプルーフも付けます。Feign クライアントには spring_boot_starter_feign を列挙してください。
Spring (Java) との対応
Spring には対応するものがありません。その oauth2Login() はサーバー上でブラウザーをログインさせます。チェックは、その OAuth2LoginAuthenticationFilter、OidcAuthorizationCodeAuthenticationProvider、OidcUserService のものです。