シングルサインオン

oauth2Login() を使うと、ユーザーはアプリケーションのパスワードではなく、アイデンティティプロバイダー (Keycloak、Google、GitHub、Auth0、Okta、Apple など) でログインします。ブラウザーはプロバイダーのログインページに送られ、ログインした状態で戻ってきます。これは PKCE を使う OAuth 2.0 の認可コードフローで、プロバイダーが対応していれば OpenID Connect も使います。サーバーがクライアントであり、トークンを保持します。

使う理由

パスワード、多要素ログイン、アカウントの復旧はプロバイダーが扱い、アプリケーションはパスワードを見ることがありません。サーバーが描画するページと Flutter Web アプリに使ってください。サーバーはアプリのバックエンド (BFF) としてトークンを保持し、ブラウザーは HttpOnly のセッション Cookie だけを持ちます。これは注入されたスクリプトからも読めません。Web ページにはトークンを安全に置く場所がないため、トークンは決して渡されません。ネイティブアプリは自分でログインしてアクセストークンを送ります。チェーンは両方を受け入れられます。

例

Spring Boot と同じく登録を設定すると、デフォルトのチェーンがそれを通じてブラウザーをログインさせます。

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=http://localhost:8180/realms/neon

プロバイダーはリダイレクト URI {baseUrl}/login/oauth2/code/{registrationId} (http://localhost:8080/login/oauth2/code/keycloak) を受け入れなければなりません。登録のプロパティは spring_boot_starter_oauth2_client のものです。

または独自のチェーンで:

@Bean()
SecurityFilterChain web(HttpSecurity http, ClientRegistrationRepository registrations) => http
    .authorizeHttpRequests((auth) => auth
        .requestMatchers('/', '/public/**').permitAll()
        .anyRequest().authenticated())
    .oauth2Login((login) => login
        // 同じサイトの別のポートから配信される Flutter Web アプリ。
        .defaultSuccessUrl('http://localhost:5050/', alwaysUse: true))
    // ネイティブアプリはプロバイダーのアクセストークンを送る。
    .oauth2ResourceServer((server) => server.jwt())
    // ログアウトするとプロバイダーでのセッションも終了する。
    .logout((logout) => logout.logoutSuccessHandler(
        OidcClientInitiatedLogoutSuccessHandler(
          registrations,
          postLogoutRedirectUri: '{baseUrl}/',
        )))
    .build();

@RestController()
class MeController {
  @GetMapping('/api/me')
  Map<String, Object?> me(@AuthenticationPrincipal() OidcUser user) =>
      {'name': user.fullName, 'email': user.email};
}

何が起きるか

  1. ログインが必要なブラウザーは、登録を列挙する生成されたログインページに向かいます。登録がちょうど一つで (フォームログインがない) 場合は、直接 /oauth2/authorization/{registrationId} に向かいます。oauth2ResourceServer もある場合、JSON を求めるプログラムは代わりに 401 を受け取り、Flutter Web アプリはそれを /oauth2/authorization/keycloak へのナビゲーションに変えます。
  2. /oauth2/authorization/{registrationId} は新しい認可リクエスト (ランダムな state、PKCE の verifier、OpenID Connect の nonce) を署名付きの Cookie に保持し、プロバイダーにリダイレクトします。未知の登録は 400 です。
  3. プロバイダーは /login/oauth2/code/{registrationId} にリダイレクトして戻します。保存されたリクエストはその state で取り出されて取り除かれます (コールバックは一度だけ動きます)。リクエストがない、state が異なる、または別の登録のコールバックは失敗します。プロバイダーからの error も、別の発行者の iss パラメーター (RFC 9207) も失敗します。
  4. コードはトークンエンドポイントで交換されます。PKCE の verifier と正確なリダイレクト URI を使います。ID トークンの署名はプロバイダーの鍵でチェックされ、次に発行者、オーディエンス、azp、有効期限、nonce がチェックされます。ユーザー情報が読み込まれ、その sub は ID トークンのものと一致しなければなりません。権限 (OIDC_USER、SCOPE_*) は、GrantedAuthoritiesMapper Bean があればそれを通ります。
  5. セッションは新しい ID を得て、ユーザーとトークン (OAuth2AuthorizedClientRepository) を保持し、ブラウザーは求めていたページ、なければ defaultSuccessUrl (/) に戻ります。その URL は設定です。リクエストの中の何物も、ブラウザーを別の場所に送ることはできません。失敗すると、理由なしで /login?error に向かいます。

オプション

oauth2Login のオプション デフォルト
loginPage(url) /login に生成されるページ
defaultSuccessUrl(url, alwaysUse:) /。保存されたページが優先
failureUrl(url)、successHandler(h)、failureHandler(h) /login?error。リダイレクト
authorizationEndpoint: baseUri、authorizationRequestRepository、authorizationRequestResolver /oauth2/authorization、署名付きの Cookie、DefaultOAuth2AuthorizationRequestResolver
redirectionEndpoint: baseUri (または loginProcessingUrl) /login/oauth2/code/*
tokenEndpoint: accessTokenResponseClient Bean、なければ HttpTransport を使うもの
userInfoEndpoint: userService、oidcUserService、userAuthoritiesMapper Bean、なければ DefaultOAuth2UserService、OidcUserService、なし
clientRegistrationRepository、authorizedClientRepository、authorizedClientService Bean
idTokenDecoder OidcIdTokenDecoder Bean、なければ OidcIdTokenDecoderFactory (署名をチェックする)

コントローラーはユーザーを @AuthenticationPrincipal() OAuth2User user (OpenID Connect では OidcUser) として受け取り、トークンを OAuth2AuthorizedClientRepository Bean から受け取ります。

フォーム POST での応答

登録に response-mode=form_post を指定すると (apple プロバイダーのデフォルト)、プロバイダーのページは code と state をフォームとしてコールバックに POST します。そのため、それらが URL、ログ、履歴に現れることはありません。

spring.security.oauth2.client.registration.keycloak.response-mode=form_post

Google でのログイン

spring.security.oauth2.client.registration.google.client-id=123-abc.apps.googleusercontent.com
spring.security.oauth2.client.registration.google.client-secret=${GOOGLE_SECRET}

google の登録は、そのエンドポイントを CommonOAuth2Provider から得ます (スコープは openid profile email)。Google Cloud で、リダイレクト URI https://<your server>/login/oauth2/code/google を持つ Web アプリケーションのクライアントを作成してください。

@Component()
class Admins implements GrantedAuthoritiesMapper {
  Admins(this._users);
  final UserRepository _users;

  @override
  List<GrantedAuthority> mapAuthorities(Iterable<GrantedAuthority> authorities) => [
        ...authorities,
        for (final authority in authorities)
          if (authority is OidcUserAuthority && _users.isAdmin(authority.idToken.subject))
            SimpleGrantedAuthority('ROLE_ADMIN'),
      ];
}

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

apple の登録 (追加されたもので、Spring にはありません) は、Apple のエンドポイント、スコープ openid name email、client_secret_post、ユーザー情報エンドポイントなし、response-mode=form_post を持ちます。Apple Developer アカウントでは、戻り URL https://<your server>/login/oauth2/code/apple を持つ Services ID (クライアント ID。Apple は localhost も IP も受け入れません)、Sign in with Apple を有効にした鍵 (.p8 ファイルとその鍵 ID)、そして チーム ID が必要です。

プロバイダーでのログアウト

OidcClientInitiatedLogoutSuccessHandler(registrations, postLogoutRedirectUri: '{baseUrl}/') はここでのセッションを終了し、次にブラウザーを ID トークンとともにプロバイダーの end_session_endpoint に送ります。そのためユーザーはそこでもログアウトされます。

Spring (Java) との対応

http.oauth2Login(login -> login.defaultSuccessUrl("http://localhost:5050/", true));

差分テスト (同じ偽のプロバイダーに対する同じブラウザーの手順) で Spring Security 7.1 と比較すると、結果は一致します。ただし、このスターターがより厳格な点は例外です。iss が発行者でないリダイレクトや、別の登録のコールバックへのリダイレクトは、ここでは失敗します (Spring はユーザーをログインさせます)。未知の登録は 400 です (Spring: 500)。失敗したログインはセッションを作りません。ID トークンの署名は常にチェックされます。apple プロバイダー、response-mode、JWT のクライアントシークレットは追加されたものです。まだないもの: oauth2Client()、@RegisteredOAuth2AuthorizedClient、バックチャネルログアウト (oidcLogout())。

関連項目