シングルサインオン
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};
}
何が起きるか
- ログインが必要なブラウザーは、登録を列挙する生成されたログインページに向かいます。登録がちょうど一つで (フォームログインがない) 場合は、直接
/oauth2/authorization/{registrationId}に向かいます。oauth2ResourceServerもある場合、JSON を求めるプログラムは代わりに401を受け取り、Flutter Web アプリはそれを/oauth2/authorization/keycloakへのナビゲーションに変えます。 /oauth2/authorization/{registrationId}は新しい認可リクエスト (ランダムなstate、PKCE の verifier、OpenID Connect のnonce) を署名付きの Cookie に保持し、プロバイダーにリダイレクトします。未知の登録は400です。- プロバイダーは
/login/oauth2/code/{registrationId}にリダイレクトして戻します。保存されたリクエストはそのstateで取り出されて取り除かれます (コールバックは一度だけ動きます)。リクエストがない、stateが異なる、または別の登録のコールバックは失敗します。プロバイダーからのerrorも、別の発行者のissパラメーター (RFC 9207) も失敗します。 - コードはトークンエンドポイントで交換されます。PKCE の verifier と正確なリダイレクト URI を使います。ID トークンの署名はプロバイダーの鍵でチェックされ、次に発行者、オーディエンス、
azp、有効期限、nonceがチェックされます。ユーザー情報が読み込まれ、そのsubは ID トークンのものと一致しなければなりません。権限 (OIDC_USER、SCOPE_*) は、GrantedAuthoritiesMapperBean があればそれを通ります。 - セッションは新しい 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 から受け取ります。
Cookie とサイト
- セッション Cookie は、プロバイダーからのトップレベルのリダイレクトであるコールバックに届かなければなりません。
StrictではなくSameSite=Lax(デフォルト) のままにしてください。 - Flutter Web アプリとサーバーは同じサイト (二つのポートを持つ
localhost、app.example.comとapi.example.com) になければならず、アプリのリクエストは Cookie (credentials: 'include') を送り、POST、PUT、DELETEでは CSRF トークンを送らなければなりません。
フォーム POST での応答
登録に response-mode=form_post を指定すると (apple プロバイダーのデフォルト)、プロバイダーのページは code と state をフォームとしてコールバックに POST します。そのため、それらが URL、ログ、履歴に現れることはありません。
spring.security.oauth2.client.registration.keycloak.response-mode=form_post
- コールバックは、同じチェックで
POSTのボディ (最大 64 KB) から応答を受け取ります。フォーム POST のログインへのGET、クエリのログインへのPOST、クエリとボディに分かれた応答は失敗し (invalid_request)、進行中のログインには手を触れません。 - コールバックの
POSTは CSRF から除外されます。署名付きの Cookie でブラウザーに結び付いたstateが保護します。 - プロバイダーの POST はクロスサイトであり、
SameSite=None; Secureの Cookie しか運びません。認可リクエストの Cookie は HTTPS ではそのように作られます。平文の HTTP ではログインは安全側に失敗し、ログに警告が出ます。フォーム 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 アプリケーションのクライアントを作成してください。
- ロール: Google はロールを送りません。
GrantedAuthoritiesMapperBean で与えてください。
@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'),
];
}
- ユーザーは
subで保持し、メールアドレスでは決して保持しないでください。アドレスは持ち主が変わることがあり、別のプロバイダーは検証していないアドレスを送ることがあります。メールアドレスはemail_verified=trueの場合にだけ使ってください。 - リフレッシュトークンはローテーションされません: 安全に保管し、ユーザーがログアウトするかアカウントを削除したときに失効させてください。
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 が必要です。
- クライアントシークレットは、その鍵で ES256 署名した JWT で、
client-secret-jwt.*プロパティからリクエストごとに作られます (デフォルトは 1 時間、残りが 10 分の 1 になるまでキャッシュされます)。鍵がログに出ることはありません。 - 名前とメールアドレスは一度だけ、最初のログインで、POST された
user(OidcUserServiceのuserRequest.additionalParameters['user']) で届きます。そのときに保存してください。これは署名されていません。これでユーザーが誰かを決めてはいけません。 - HTTPS でのみ: Apple は応答を POST で返します (フォーム POST)。
- App Store が求めるとおり、ユーザーがアカウントを削除したときはそのトークンを失効させてください。
プロバイダーでのログアウト
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())。