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

新人

「先輩、OAuth2ってよく聞きますけど、実際何をする仕組みなんですか？」

先輩

「OAuth2は、インターネット上で安全に認可を行うための標準的なプロトコルだよ。パスワードを相手に渡さずに、アプリケーションに必要なアクセス権を付与できるんだ。」

新人

「なるほど！じゃあスコープっていうのは何ですか？」

先輩

「スコープは、OAuth2で許可するアクセス範囲を指定するためのものだね。どのデータにどこまでアクセスできるかを細かく決められるんだ。」

新人

「それってSpring Securityでも設定できるんですか？」

先輩

「もちろんだよ。じゃあまずはOAuth2の仕組みとスコープの基本を解説していこう。」

1. OAuth2とは？（基本的な説明と認可の仕組み）

OAuth2（オーオースツー）は、ユーザーが自分の認証情報（IDやパスワード）を直接アプリケーションに渡さずに、安全に認可を行うためのプロトコルです。GoogleやGitHubなどの外部サービスと連携する際によく利用され、特定の機能やデータへのアクセスを安全に制御できます。

この仕組みでは、クライアントアプリケーションが「リソースサーバー」にアクセスするために「アクセストークン」を利用します。アクセストークンは認可サーバーによって発行され、どの範囲までアクセスできるかが記録されています。

Spring Securityを使うと、このOAuth2のフローを簡単に実装できます。開発環境としては、PleiadesをインストールしてGradleで構築し、依存関係はPleiadesのチェック機能で追加します。コントローラは必ず@Controllerを使用し、@RestControllerは使いません。

例えば、Spring SecurityでOAuth2ログインを設定するには、以下のようなJavaコードを用意します。


@Controller
public class LoginController {

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

このように@Controllerを使ってログインページを表示し、Spring Securityの設定ファイルでOAuth2のクライアント情報を登録することで、安全な認可処理が可能になります。

2. スコープ（Scope）とは何か？（役割と基本概念）

スコープとは、OAuth2において「どの範囲の権限を許可するか」を定義するためのパラメータです。例えば、Google APIでは「email」スコープを指定すればメールアドレス情報にアクセスでき、「profile」スコープを指定すればプロフィール情報にアクセスできます。

スコープは認可リクエスト時に指定し、認可サーバーが発行するアクセストークンにそのスコープ情報が含まれます。これにより、リソースサーバーはトークンに基づきアクセス制御を行います。

Spring Securityでスコープを利用する場合、セキュリティ設定クラスで指定することができます。例えば、特定のスコープを持つユーザーだけがアクセスできるエンドポイントを設定するコードは以下の通りです。


@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/userinfo").hasAuthority("SCOPE_profile")
                .anyRequest().authenticated()
            )
            .oauth2Login();
        return http.build();
    }
}

この設定では、/userinfoエンドポイントにアクセスできるのは「SCOPE_profile」というスコープを持つユーザーだけになります。スコープ名の前にはSCOPE_が自動的に付与される点がポイントです。

このようにスコープを正しく設定することで、最小限の権限でアプリケーションを運用でき、セキュリティリスクを減らせます。初心者の方も、スコープの考え方を理解すれば、OAuth2の権限管理がより明確になります。

3. 権限（Authority）とは何か？（ユーザー権限とスコープの違い）

OAuth2における権限（Authority）は、ユーザーやクライアントアプリケーションが実行できる操作やアクセスできる機能を定義するものです。Spring Securityでは、この権限情報をもとにアクセス制御を行い、特定のURLや機能へのアクセスを許可または拒否します。

スコープと権限は似ていますが、用途が異なります。スコープは「どの範囲のリソースにアクセスできるか」を示し、権限は「アプリケーション内でどの操作ができるか」を定義します。例えば、スコープがemailであればメール情報へのアクセスを意味し、権限がROLE_ADMINであれば管理者専用の操作が可能になります。

Spring Securityでは、OAuth2のスコープはSCOPE_プレフィックスを持つ権限として自動的にマッピングされます。つまり、スコープも権限の一種として扱えるため、同じ仕組みでアクセス制御を設定できます。

この違いを理解することで、OAuth2を利用したアプリケーションでより細やかなアクセス制御が可能になります。

4. Spring Securityでスコープと権限を設定する方法

Spring Securityでは、Javaコードまたは設定ファイルでスコープと権限の両方を柔軟に設定できます。Pleiades環境でGradleを使用する場合は、まずspring-boot-starter-securityとspring-boot-starter-oauth2-clientの依存関係を追加します。依存関係はPleiadesのチェック機能から選択して追加できます。

設定の基本は、HttpSecurityオブジェクトを使用してURLごとに必要な権限やスコープを指定することです。以下は、特定のエンドポイントにスコープと権限を設定する例です。


@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .requestMatchers("/profile").hasAuthority("SCOPE_profile")
                .anyRequest().authenticated()
            )
            .oauth2Login();
        return http.build();
    }
}

この設定では、/admin/**は管理者権限を持つユーザーのみアクセスでき、/profileはprofileスコープを持つユーザーだけがアクセスできます。これにより、リソースへのアクセス範囲とアプリケーション内での操作権限を分離しつつ管理できます。

さらに、複数のスコープや権限を組み合わせて指定することも可能で、柔軟な制御が実現できます。

5. 実際のコード例（@Controllerを使用した例）

ここでは、@Controllerを使ってOAuth2認証後にスコープや権限を利用する簡単な例を示します。この例では、ログインしたユーザーの情報とスコープを画面に表示します。


@Controller
public class UserInfoController {

    @GetMapping("/userinfo")
    public String userInfo(Model model, OAuth2AuthenticationToken authentication) {
        Map<String, Object> attributes = authentication.getPrincipal().getAttributes();
        Collection<? extends GrantedAuthority> authorities = authentication.getAuthorities();

        model.addAttribute("attributes", attributes);
        model.addAttribute("authorities", authorities);
        return "userinfo";
    }
}

このコントローラでは、OAuth2認証によって取得したユーザー属性情報と付与された権限（スコープを含む）をModelに追加し、ビューで表示できるようにしています。ビュー側では、スコープや権限を確認することで、特定の機能を表示したり非表示にしたりできます。

例えば、ユーザー情報を表示するHTMLテンプレートは以下のように記述できます。


<!DOCTYPE html>
<html>
<body>
    <h3>ユーザー情報</h3>
    <div>
        <h4>属性情報</h4>
        <ul>
            <th:block th:each="entry : ${attributes}">
                <li>[[${entry.key}]] : [[${entry.value}]]</li>
            </th:block>
        </ul>
    </div>
    <div>
        <h4>権限（スコープ含む）</h4>
        <ul>
            <th:block th:each="auth : ${authorities}">
                <li>[[${auth.authority}]]</li>
            </th:block>
        </ul>
    </div>
</body>
</html>

このように、@Controllerを使った実装ではSpring MVCの機能をそのまま活用でき、OAuth2のスコープや権限情報を柔軟に画面表示や機能制御に利用できます。初心者でも理解しやすく、安全なアクセス制御を実装できるのがSpring Securityの大きな魅力です。

6. OAuth2で複数スコープを扱う方法

OAuth2では、一度の認可リクエストで複数のスコープを指定することができます。これにより、ユーザーがアプリケーションに対して許可するアクセス範囲を細かく定義できます。例えば、ユーザーのメール情報とプロフィール情報の両方にアクセスしたい場合は、スコープとしてemail profileを指定します。

複数スコープを扱う際のポイントは、各スコープが持つ意味を正しく理解し、必要最小限の組み合わせを選ぶことです。不要なスコープを付与すると、セキュリティリスクが高まる可能性があります。また、Spring Securityでは複数のスコープを権限として自動マッピングするため、それぞれにSCOPE_プレフィックスが付いた形で認識されます。

以下はSpring Securityで複数スコープを設定し、必要に応じてアクセス制御を行う例です。


@Configuration
@EnableWebSecurity
public class MultiScopeSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/email").hasAuthority("SCOPE_email")
                .requestMatchers("/profile").hasAuthority("SCOPE_profile")
                .anyRequest().authenticated()
            )
            .oauth2Login();
        return http.build();
    }
}

このように複数スコープを扱うことで、各エンドポイントごとに必要な権限を正確に設定できます。

7. 権限管理のベストプラクティス（最小権限の原則など）

OAuth2の権限管理において重要な考え方が「最小権限の原則」です。これは、ユーザーやアプリケーションに与える権限は必要最低限に留めるべきという考え方です。この原則を守ることで、意図しない情報漏洩や不正アクセスのリスクを軽減できます。

実装上のポイントとしては、まず必要なスコープと権限を明確に洗い出し、それ以外は付与しないことです。また、権限はできるだけ細かく分割して管理し、管理者や特権ユーザーにのみ付与するようにします。

さらに、定期的にスコープと権限の棚卸しを行い、不要になった権限は速やかに削除します。これにより、アプリケーションのセキュリティを高い状態で保つことができます。

Spring Securityでは、権限やスコープをコードベースで集中管理できるため、ベストプラクティスを実践しやすい環境が整っています。

8. 実際のアプリケーションでの活用例

実際の業務システムやWebアプリケーションでは、OAuth2のスコープと権限管理を組み合わせて安全なアクセス制御を行います。例えば、社内ポータルサイトで従業員の基本情報、勤怠データ、給与明細にアクセスする場合、それぞれに専用のスコープを割り当てます。

以下は、複数スコープを利用し、@Controllerでアクセス制御を実装する例です。


@Controller
public class EmployeeController {

    @GetMapping("/employee/profile")
    public String profile(Model model, OAuth2AuthenticationToken authentication) {
        if (authentication.getAuthorities().stream()
            .anyMatch(auth -> auth.getAuthority().equals("SCOPE_profile"))) {
            model.addAttribute("message", "プロフィール情報を表示します");
        } else {
            model.addAttribute("message", "アクセス権限がありません");
        }
        return "employee";
    }

    @GetMapping("/employee/payroll")
    public String payroll(Model model, OAuth2AuthenticationToken authentication) {
        if (authentication.getAuthorities().stream()
            .anyMatch(auth -> auth.getAuthority().equals("SCOPE_payroll"))) {
            model.addAttribute("message", "給与明細情報を表示します");
        } else {
            model.addAttribute("message", "アクセス権限がありません");
        }
        return "employee";
    }
}

このように、ユーザーが持つスコープを確認して機能を制御することで、アプリケーションのセキュリティを強化できます。

ビュー側では、取得したスコープや権限に基づいて表示内容を動的に切り替えることができます。例えば、Thymeleafテンプレートを利用して、権限がある場合のみ特定のリンクや情報を表示するといった実装が可能です。

OAuth2のスコープと権限管理は、正しく理解して運用することで非常に強力なセキュリティ機構となります。初心者の方も、まずは少ないスコープから設定を試し、徐々に複雑な管理へとステップアップすると理解が深まりやすいでしょう。