アプリのログイン

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'):

  1. 認可リクエストを組み立てます。ランダムな state (Random.secure() の 32 バイト)、PKCE のベリファイア (64 バイト) とその S256 のチャレンジ、そして openid ではランダムな nonce (その SHA-256 ハッシュが送られます) です。
  2. AuthorizationWindow でプロバイダーのログインページを開き、戻ってくるリダイレクトを待ちます。
  3. リダイレクトをチェックします。リダイレクト URI に戻ってきたこと、送った state (そうでなければ invalid_state_parameter)、存在するか告知されている場合は iss パラメーター (RFC 9207、そうでなければ invalid_issuer)、そして error (access_denied など) または code です。
  4. ベリファイアと実際に使ったリダイレクト URI でコードを交換します。
  5. OpenID Connect では、ID トークン (issuer、audience、azp、60 秒のずれを許した有効期限と発行時刻、nonce) をチェックし、ユーザー情報を読み込みます。その sub は ID トークンのものと一致しなければなりません。
  6. 権限を対応付け (OIDC_USER または OAUTH2_USER、SCOPE_<scope>、次に GrantedAuthoritiesMapper Bean)、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() は、保存されたトークンからユーザーを呼び戻し、一分以内に期限が切れる場合はトークンを更新します。

logout

logout() は、リフレッシュトークンとアクセストークンを取り消し (RFC 7009。プロバイダーが revocation_endpoint を持つ場合)、それらを忘れ、コンテキストをクリアし、LogoutSuccessEvent を発行します。すべてウィンドウなしでです。ユーザーはシステムのブラウザーではプロバイダーにログインしたままなので、次のログインではパスワードが不要な場合があります。これがモバイルアプリの通常のログアウトです。

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 のものです。

関連項目