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

新人

「Spring Securityで細かいアクセス制御をしたいんですが、URLじゃなくてメソッド単位で制限することってできますか？」

先輩

「それなら、@PreAuthorizeや@PostAuthorizeを使ったメソッドレベルのアクセス制御がぴったりだよ。」

新人

「URLで制御するのとは何が違うんですか？どっちが便利なんでしょうか？」

先輩

「それじゃ、Spring Securityのメソッドレベル制御について詳しく解説していこうか！」

1. Spring Securityにおけるメソッドレベルのセキュリティとは？

Spring Securityでは、Webアプリケーションに対してさまざまなレベルのアクセス制御を行うことができますが、その中でも特に柔軟なのがメソッドレベルでのセキュリティ制御です。

メソッドレベルの制御とは、特定のJavaメソッドに対して直接、アクセス権限を付けることができる機能で、代表的なアノテーションには@PreAuthorizeや@PostAuthorizeがあります。

たとえば、管理者しかアクセスできない処理に対して、次のようにメソッドの上に制限をつけることが可能です。


@Controller
public class AdminController {

    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping("/admin")
    public String adminPage() {
        return "admin";
    }
}

このように、メソッドごとに直接アクセス制御を付けることで、より粒度の細かいセキュリティ設定が実現できます。

この仕組みは、ビジネスロジックに基づいた条件で制御したいときに特に効果を発揮します。

たとえば、「この処理はログインしているユーザーが自分自身のデータに対してのみ実行できるようにしたい」といったシナリオにも対応可能です。

Spring Security メソッドレベルで検索されることが多いのも、この柔軟さに注目が集まっている証拠です。

2. なぜメソッドレベルでのアクセス制御が必要なのか（URL制御との違い）

Spring Securityの基本的なアクセス制御は、URLパターンに対してアクセス権限を設定するものです。

たとえば、/admin/**にROLE_ADMINを付与するような設定をすることで、該当URL以下のすべてのリクエストに対して制御できます。

ですが、実際の開発現場では、URL単位では対応しきれない細かい制御が必要になることがあります。

具体的には、次のようなケースです：

同じURLでも、ログインユーザーによって制御を分けたい
戻り値の内容に応じてアクセス可否を決めたい
データベースの情報を元に、アクセスを判断したい

これらのケースでは、URL単位の制御では限界があり、メソッド単位でのセキュリティ制御が不可欠になります。

たとえば、以下のようにコントローラメソッドに制限を直接書くことで、より直感的で明確な制御が可能です。


@Controller
public class ProfileController {

    @PreAuthorize("authentication.name == #username")
    @PostMapping("/user/edit/{username}")
    public String editProfile(@PathVariable String username) {
        return "editProfile";
    }
}

この例では、「自分自身のプロフィールしか編集できない」ように制限しています。

これはURL単位の制御では難しいため、メソッドレベルのアクセス制御が必要になるわけです。

アクセス制御入門としてSpring Securityを学ぶ際には、まずこの違いをしっかり理解しておくことがとても重要です。

3. @PreAuthorizeの使い方とサンプルコード（実行前の権限チェック）

@PreAuthorizeは、メソッドが呼び出される前に指定した条件をチェックして、許可されない場合は処理を中断するためのアノテーションです。

たとえば、特定のロールを持つユーザーだけに処理を許可したい場合、次のように使います。


@Controller
public class AdminController {

    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping("/admin/setting")
    public String adminSetting() {
        return "adminSetting";
    }
}

このコードでは、ADMINロールを持っていないユーザーがこのメソッドを呼び出そうとすると、自動的にアクセスが拒否され、403 Forbiddenエラーが発生します。

条件式には、Spring Expression Language（SpEL）という表現方法が使えます。たとえば次のような条件も可能です：

hasAuthority('READ_PRIVILEGE')：特定の権限を持っているか
authentication.name == #username：ログインユーザーが引数と一致するか

次の例では、ログインユーザー自身のみが、自分の情報を変更できるようにしています。


@Controller
public class UserController {

    @PreAuthorize("authentication.name == #username")
    @PostMapping("/user/update/{username}")
    public String updateUser(@PathVariable String username) {
        return "updateComplete";
    }
}

このように@PreAuthorizeを使えば、ビジネスロジックに即した柔軟な制御が簡単に実現できます。

@PreAuthorize 使い方で調べると、多くのパターンが出てくるほど、実践的なシーンで多く使われています。

4. @PostAuthorizeの使い方とユースケース（実行後の結果に対する制御）

@PostAuthorizeは、メソッドが実行された後に、戻り値を元にアクセス権をチェックするアノテーションです。

たとえば、処理をいったん実行してから、その結果を見てユーザーに表示させるかどうかを判断したいケースに使います。

以下は@PostAuthorizeを使った代表的な例です。


@Controller
public class DocumentController {

    @PostAuthorize("returnObject.owner == authentication.name")
    @GetMapping("/doc/{id}")
    public Document getDocument(@PathVariable Long id) {
        return documentService.findById(id);
    }
}

このコードでは、findById()でドキュメントを取得した後、ログインユーザーがそのドキュメントのownerであるかを確認します。

一致しない場合は、その後の表示処理がブロックされ、403エラーになります。

@PreAuthorizeではアクセス前に条件を確認しますが、取得したオブジェクトを条件にしたい場合は@PostAuthorizeが便利です。

ユースケースとしては、次のような場面に向いています：

データの一部がユーザーごとに異なるとき
取得したデータに対してアクセス判定を行いたいとき
外部APIやDBとのやり取り後に検証したいとき

@PostAuthorize 例で検索すると、戻り値ベースの制御パターンを確認できます。実行後のロジックを活用したい場面ではぜひ使ってみましょう。

5. 権限チェックが失敗したときの403 Forbiddenエラーと対処法

@PreAuthorizeや@PostAuthorizeによるチェックに失敗した場合、Spring Securityは自動的に403 Forbiddenエラーを返します。

403エラーは、「認証済みだが、指定されたリソースに対するアクセス権限がない」ことを意味します。

たとえば、USERロールしか持たないユーザーが、@PreAuthorize("hasRole('ADMIN')")のメソッドを実行しようとすると、次のようなエラーページが表示されます。


Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.

There was an unexpected error (type=Forbidden, status=403).
Access is denied

このエラーを初心者でも扱いやすくするためには、以下の対応が効果的です：

403エラー専用のカスタム画面を作成する
アクセス権限不足の理由をメッセージで表示する
ログインユーザーのロールや属性を画面に反映させる

カスタムエラー画面の設定例は以下の通りです。


@Configuration
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .exceptionHandling(ex -> ex
                .accessDeniedPage("/access-denied")
            );
        return http.build();
    }
}

このように設定すると、403エラーが発生したときに/access-deniedページへ遷移させることができます。

そしてaccess-denied.htmlを用意すれば、ユーザーに対して丁寧な案内を表示できます。

403 Forbidden Spring Securityというキーワードで検索されることが多いように、初心者がつまずきやすいポイントでもあるため、早めに対策しておくことが大切です。

6. 実務でよく使うロール名と設計ルール（例：ROLE_ADMIN、ROLE_USERなど）

Spring Securityでアクセス制御を行う際には、ロール設計が非常に重要になります。ロールとは、ユーザーが持つ役割や権限を表す名前で、一般的にはROLE_というプレフィックスを付けて表現されます。

たとえば次のようなロール名が、実務でよく使われます。

ROLE_ADMIN：管理者用。システム全体の設定や管理操作を許可。
ROLE_USER：一般ユーザー用。通常のアプリケーション利用が可能。
ROLE_MANAGER：部署責任者など、特定の範囲での管理権限。

ロール名は自由に設計できますが、以下のルールを守ると保守性が高まります。

ロール名には大文字・アンダースコアを使う（例：ROLE_SUPPORT_STAFF）
用途が分かるような命名にする（例：ROLE_ORDER_EDITOR）
冗長なロールは作らず、粒度は業務単位で整理

また、ロールの設計には「職責ベースの設計」と「機能ベースの設計」があります。前者は役職ごとにロールを分け、後者は操作単位で分ける方法です。

実務ではこれらを組み合わせ、ROLE_ADMINにはROLE_USERも内包させるような設計が有効です。

7. メソッドレベルのセキュリティを使った設計例（ユーザー管理やデータ所有者制御など）

ここでは、実務でよくあるアクセス制御設計例を紹介しながら、@PreAuthorizeや@PostAuthorizeの使い方を応用する方法を見ていきましょう。

まずは「ユーザー管理画面」の例です。管理者だけがすべてのユーザー情報を閲覧・編集できるようにし、一般ユーザーは自分の情報だけを編集できるようにします。


@Controller
public class UserController {

    @PreAuthorize("hasRole('ADMIN')")
    @GetMapping("/admin/users")
    public String listAllUsers() {
        return "userList";
    }

    @PreAuthorize("hasRole('ADMIN') or authentication.name == #username")
    @PostMapping("/user/edit/{username}")
    public String editUser(@PathVariable String username) {
        return "editUser";
    }
}

このように条件を複数指定することで、ロールによる制御と所有者による制御を柔軟に組み合わせることができます。

次は「データ所有者制御」の例です。自分が登録したデータしか編集できないようにするパターンです。


@Controller
public class TaskController {

    @PostAuthorize("returnObject.owner == authentication.name")
    @GetMapping("/task/{id}")
    public Task getTask(@PathVariable Long id) {
        return taskService.findById(id);
    }
}

この例では、タスクの所有者だけが詳細画面を表示できます。取得後のオブジェクトの中身で判定するので、@PostAuthorizeが適しています。

実務では、上記のように所有者制御と管理者制御を組み合わせることで、柔軟かつ安全なアクセス設計が可能になります。

8. 本番環境でメソッドセキュリティを安全に運用するための注意点（保守性・柔軟性）

Spring Security 本番運用で注意すべき点は、セキュリティ設定の正確さだけでなく、保守性や柔軟性も大きな課題になります。

特に以下のような項目を意識して設計・運用することが重要です。

① 定数でロールを管理する

ロール名をハードコーディングすると、変更時に修正漏れが起きやすくなります。以下のように定数クラスを用意することで、ロール管理がしやすくなります。


public class Roles {
    public static final String ADMIN = "ROLE_ADMIN";
    public static final String USER = "ROLE_USER";
}

そしてアノテーションで使うときは、以下のように文字列で書かず、変数に置き換えます。

ただし、@PreAuthorizeの中では定数を直接使えないため、別の方法として共通メソッドを活用することも検討しましょう。

② アノテーションとサービスの分離

アクセス制御の条件が複雑になる場合は、@PreAuthorizeの中に複雑なSpEL式を詰め込むのではなく、サービスメソッドに判定処理を委譲する設計が有効です。


@PreAuthorize("@authService.canEditUser(#username)")

このように書けば、authServiceのメソッド内で自由にロジックを組めるため、可読性も保守性も向上します。

③ ロールと権限のマッピング管理

実運用では、ロールと個別の権限（読み取り・書き込み・削除など）を分離して管理する方が柔軟です。

たとえば、データベース上でロールごとの権限を定義し、ロールが増減しても権限の組み合わせで制御できるようにしておけば、コード修正なしで対応できる場合もあります。

④ 設計時のセキュリティレビュー

最も大切なのは、「本当にこの処理にこのユーザーがアクセスしてよいのか？」を設計段階で明確にすることです。

実装が進んだ後で制御を追加するのは手間が大きく、初期設計段階からセキュリティ要件を取り込むことが重要です。

とくに@PreAuthorizeや@PostAuthorizeを多用する場合は、一覧表にまとめてレビューすると効果的です。

Spring Security 本番運用では、日々の更新にも耐えうる柔軟な仕組みを構築することが求められます。

Spring Securityのメソッドレベル制御を完全解説！初心者向けアクセス制御ガイド