新人と先輩の会話形式で理解しよう

新人

「先輩、最近『Spring BootでOAuth2を導入する』ってよく聞くんですけど、OAuth2って何なんですか？」

先輩

「OAuth2は、外部サービスとの連携やログイン認証を行うための標準的な仕組みなんだ。例えば、Googleアカウントでログインするようなケースが代表的だよ。」

新人

「なるほど！じゃあSpring Bootでは、どのようにOAuth2を導入するんですか？」

先輩

「それじゃ、OAuth2の基本から導入手順、Spring Bootとの連携方法まで順番に説明していくね。」

1. OAuth2とは何か

OAuth2（オーオースツー）は、ユーザーのパスワードをサービス側に渡さずに、安全に認可（アクセス許可）を行うためのプロトコルです。現在では、Google、Facebook、GitHubなど多くのサービスで採用されています。

例えば、あるWebアプリがGoogleアカウントでログインさせたいとき、OAuth2を使うことでユーザーはGoogleのログイン画面で認証し、その結果だけをWebアプリに伝えることができます。

これにより、パスワードをそのアプリに直接入力する必要がなくなり、セキュリティ面でも非常に優れているのです。

また、OAuth2は認可サーバーとリソースサーバーに分かれており、アクセストークンという一時的な鍵を使って安全に情報を取得します。

2. Spring BootにOAuth2を導入する目的と基本的な仕組み

Spring BootでOAuth2を導入する目的は、簡単かつ安全に外部認証サービスと連携することです。Spring Securityというフレームワークを利用すれば、OAuth2の機能も組み込みやすくなります。

例えば、社内アプリケーションにGoogleアカウントログインを導入する場合、Spring SecurityのOAuth2機能を活用することで、ユーザー情報の取得やリダイレクト処理を自動化できます。

Spring Bootでは、以下のような構成になります。

ユーザーがログイン要求を送信
Spring SecurityがGoogleなどの認可サーバーにリダイレクト
認可後にアクセストークンを受け取り、ユーザー情報を取得
アプリケーションに認証済みユーザーとして戻る

この流れにより、OAuth2の認証フローが簡潔に実装可能になります。

3. 開発前の前提準備（Pleiadesでのプロジェクト作成や依存関係の追加）

ここからは、Spring BootでOAuth2を導入するための準備手順を紹介します。

今回は、Pleiades（Eclipse日本語化パッケージ）を使い、Gradleで構成されたSpring Bootプロジェクトを作成します。

① Pleiadesで新しいGradleプロジェクトを作成

「ファイル」→「新規」→「Gradleプロジェクト」を選択
プロジェクト名を入力（例：oauth2-demo）
パッケージ名（例：com.example.oauth2demo）を指定

② 必要な依存関係をチェックで追加

プロジェクト作成時に以下の依存関係にチェックを入れてください。

Spring Web（@Controllerなどを使うため）
Spring Security
OAuth2 Client
Thymeleaf（ログイン画面用）

③ build.gradleに自動で追加される依存関係

チェックを入れた依存関係は、自動的にbuild.gradleファイルに記述されます。以下はその一例です。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
}

④ プロジェクトを起動して確認

依存関係を確認したら、Pleiadesからプロジェクトを右クリック →「Spring Bootアプリケーションとして実行」で起動してください。

コンソールにStarted Applicationというメッセージが出れば、起動成功です。

4. 必要な依存関係とbuild.gradleの設定（Gradleを使用）

Spring BootでOAuth2の導入を行う際には、まずbuild.gradleファイルに必要な依存関係を記述する必要があります。Pleiadesのプロジェクト作成時にチェックを入れていれば自動で追加されますが、ここでは手動で設定する場合の内容も確認しておきましょう。

以下の依存関係は、OAuth2による認証機能を構築する上で重要です。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'org.springframework.boot:spring-boot-starter-oauth2-client'
    implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
}

spring-boot-starter-oauth2-client はOAuth2のクライアント機能を提供するモジュールで、GoogleやGitHubなどの外部サービスと連携する際に必須です。

spring-boot-starter-security は認証・認可の全体的な仕組みを担います。セキュリティの構成やルール設定には欠かせません。

spring-boot-starter-web はHTTP通信、MVCコントローラ、ルーティングを提供する基本的なWeb機能を構成します。

spring-boot-starter-thymeleaf はビューの作成に使用します。ログイン画面などをHTMLで構築するために便利です。

5. application.ymlの設定ポイント

次に、OAuth2の認証情報やリダイレクトの設定を行うapplication.ymlを構成します。ここではGoogleログインを例に設定方法を解説します。

まず、src/main/resources 配下にある application.yml に以下のような設定を追加します。


spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: your-client-id
            client-secret: your-client-secret
            scope:
              - email
              - profile
        provider:
          google:
            authorization-uri: https://accounts.google.com/o/oauth2/v2/auth
            token-uri: https://oauth2.googleapis.com/token
            user-info-uri: https://www.googleapis.com/oauth2/v3/userinfo

ここで指定するclient-idとclient-secretは、Google Cloud Consoleで作成した認証情報から取得します。

registrationセクションでは、どのプロバイダー（この例ではGoogle）を使うかを定義し、認証スコープやクライアントIDを設定します。

providerセクションでは、Googleの認証、トークン発行、ユーザー情報取得の各URLを指定します。

この設定を正しく行うことで、Spring BootアプリケーションがGoogleのOAuth2認証に対応できるようになります。

6. セキュリティ設定の基本（SecurityConfigなど）

OAuth2認証を機能させるためには、SecurityConfigというJavaクラスでセキュリティのルールを定義する必要があります。これはSpring Securityの挙動を細かく制御するために欠かせない構成要素です。

以下は、@Controllerを使用した場合の基本的なSecurityConfigの例です。


package com.example.oauth2demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
import org.springframework.context.annotation.Bean;

@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/", "/login", "/css/**", "/js/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .loginPage("/login")
            );
        return http.build();
    }
}

authorizeHttpRequests() メソッドでは、特定のURL（例：トップページやログイン画面）を誰でもアクセス可能に設定します。

anyRequest().authenticated() の部分では、それ以外のすべてのリクエストに対して認証を必須としています。

oauth2Login() メソッドでは、OAuth2によるログインの設定を行い、カスタムログインページのパスを指定しています。

このSecurityConfigを定義することで、Spring Boot OAuth2導入時の基本的なセキュリティ動作が実現できます。

また、@Configurationと@Beanを活用することで、設定を柔軟かつ明確に分離できます。これにより、後から機能を追加しやすくなるメリットもあります。

7. 認可後のリダイレクト処理の実装方法（成功時・失敗時の制御）

Spring BootでOAuth2認証を行った後、ユーザーが認可サーバーからアプリケーションに戻ってきた際のリダイレクト処理をカスタマイズすることで、より使いやすい画面遷移が実現できます。特に、認証に成功した場合と失敗した場合で異なるページにリダイレクトする制御が必要となります。

OAuth2のデフォルト設定では、成功後にルートパス「/」にリダイレクトされますが、独自のページを表示させたい場合はOAuth2AuthenticationSuccessHandlerやAuthenticationFailureHandlerを実装します。

以下は、認証成功後にトップページにリダイレクトし、失敗した場合は再びログインページに戻す例です。


package com.example.oauth2demo.handler;

import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.security.core.Authentication;
import org.springframework.security.web.authentication.AuthenticationFailureHandler;
import org.springframework.security.web.authentication.AuthenticationSuccessHandler;
import org.springframework.stereotype.Component;
import java.io.IOException;

@Component
public class OAuth2LoginHandler implements AuthenticationSuccessHandler, AuthenticationFailureHandler {

    @Override
    public void onAuthenticationSuccess(HttpServletRequest request, HttpServletResponse response,
                                        Authentication authentication) throws IOException {
        response.sendRedirect("/home");
    }

    @Override
    public void onAuthenticationFailure(HttpServletRequest request, HttpServletResponse response,
                                        org.springframework.security.core.AuthenticationException exception)
            throws IOException, ServletException {
        response.sendRedirect("/login?error");
    }
}

このハンドラをSecurityConfigで設定することで、認証後のリダイレクト先を自由に制御できます。


.oauth2Login(oauth2 -> oauth2
    .loginPage("/login")
    .successHandler(oAuth2LoginHandler)
    .failureHandler(oAuth2LoginHandler)
);

このようにすることで、ユーザーの操作に応じて適切な画面遷移を実現できます。特に、Spring Boot 認可リダイレクトに関する設定はSEO的にも重要なキーワードとなるため、導入方法をしっかり押さえましょう。

8. @Controllerを使ったログイン画面・トップ画面の表示方法

ここでは、@Controllerを用いてログインページとトップページを作成する流れを解説します。Spring BootのMVCパターンを活用し、Thymeleafテンプレートを使って画面を描画します。

まず、ログインページ用のLoginControllerを作成します。@Controllerを使用することで、HTMLファイルをビューとして返すことができます。


package com.example.oauth2demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class LoginController {

    @GetMapping("/login")
    public String login() {
        return "login";
    }

    @GetMapping("/home")
    public String home() {
        return "home";
    }
}

次に、src/main/resources/templates 配下に login.html と home.html を配置します。以下は login.html の例です。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ログイン</title>
</head>
<body>
    <h2>ログインページ</h2>
    <a href="/oauth2/authorization/google">Googleでログイン</a>
</body>
</html>

同様に、home.html ではログイン後のユーザー名を表示することも可能です。Thymeleafの${#authentication.name}を使うことで、認証されたユーザー情報を簡単に取得できます。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ホーム</title>
</head>
<body>
    <h2>ようこそ、[[${#authentication.name}]]さん！</h2>
</body>
</html>

この構成により、@ControllerとThymeleafを組み合わせたSpring Boot OAuth2 動作確認がしやすくなります。

9. 実際にアプリを起動して動作を確認する手順（Pleiades使用）

最後に、アプリケーションを起動し、OAuth2認証の動作を確認する手順をまとめます。Pleiadesを使用するため、Eclipse上での実行方法も解説します。

まず、プロジェクトをクリーンビルドします。Pleiadesの「プロジェクト」メニューから「クリーン」を選択し、Gradleの依存関係が正しく適用されていることを確認します。

次に、Spring Bootアプリケーションとして実行を選択し、コンソールにStarted Applicationというメッセージが出れば起動は成功です。

ブラウザを開き、http://localhost:8080/login にアクセスします。Googleログインリンクが表示されるので、クリックするとGoogleの認証ページにリダイレクトされます。

Googleアカウントで認証を完了すると、アプリケーションの/homeページに戻り、ユーザー名が表示されます。この一連の流れが正しく動作すれば、Spring Boot OAuth2 動作確認が成功したことになります。

認証に失敗した場合、/login?errorに戻され、再度ログインを試みるよう促されます。これにより、ユーザーはスムーズに再認証を行うことができます。

ここまでの実装により、Spring Boot 認可リダイレクトや@Controllerを用いた画面構築が完了し、OAuth2の基本フローが理解できたはずです。動作確認ではログやコンソール出力を活用し、想定通りに画面遷移が行われるかを細かくチェックすると良いでしょう。

まとめ

Spring BootでOAuth2を導入する全体像の振り返り

ここまで、Spring BootでOAuth2を導入する方法について、基礎知識から実装、動作確認までを段階的に見てきました。OAuth2は単なるログイン機能ではなく、「ユーザーの大切な認証情報を安全に扱うための仕組み」であり、現代のWebアプリケーション開発では欠かせない存在です。特に、GoogleやGitHubなど外部サービスと連携するケースでは、OAuth2の理解がそのままセキュリティ設計の理解につながります。

Spring Bootでは、Spring SecurityとOAuth2 Clientを組み合わせることで、複雑に見える認証フローを比較的シンプルに構築できます。依存関係の追加、application.ymlの設定、SecurityConfigの定義といった一連の作業は、最初こそ戸惑うものの、流れを理解すれば再利用しやすい構成になっています。

OAuth2導入で重要となる設計の考え方

OAuth2導入時に大切なのは、「とりあえず動かす」ことではなく、「どこで何が起きているのか」を意識することです。ユーザーがログインボタンを押した瞬間から、認可サーバーへのリダイレクト、アクセストークンの取得、認証済みユーザーとしての戻り処理まで、すべてが一連の流れとしてつながっています。

特にSpring Boot OAuth2では、SecurityConfigでのURL制御や、認証成功・失敗時のリダイレクト処理がアプリの使い勝手を大きく左右します。ログイン後にどの画面へ遷移させるのか、認証エラー時にどう案内するのかといった点は、ユーザー体験と直結します。技術的な正しさだけでなく、実際の利用シーンを想定した設計が重要です。

サンプルコードで整理するOAuth2設定のポイント

以下は、本記事で学んだ内容を踏まえた、OAuth2ログイン設定の基本例です。SecurityConfigの中でOAuth2ログインを有効化し、画面遷移を明示的に制御することで、動作の把握がしやすくなります。


@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/login", "/css/**").permitAll()
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .loginPage("/login")
                .defaultSuccessUrl("/home", true)
            );
        return http.build();
    }
}

このように設定することで、Spring Boot OAuth2認証の基本的な流れが明確になります。どのURLが誰でもアクセス可能で、どこから認証が必要なのかを整理しておくことは、後から機能追加や仕様変更を行う際にも大きな助けとなります。

先生と生徒の振り返り会話

生徒：「OAuth2って難しそうだと思っていましたけど、流れで見ると意外と整理できますね。」

先生：「そうだね。Spring BootとSpring Securityが裏側を支えてくれるから、全体像を理解することが大切なんだ。」

生徒：「application.ymlとSecurityConfigの役割もはっきりしました。」

先生：「設定ファイルとJavaクラスの役割分担を意識できると、OAuth2導入がぐっと楽になるよ。」

生徒：「ログイン成功後や失敗時の画面遷移も、自分で制御できるのが分かって安心しました。」

先生：「その理解があれば、Spring Boot OAuth2を使った実務開発でも十分対応できるはずだよ。」