auth0-springboot-api

Auth0 Spring Boot API 統合

com.auth0:auth0-springboot-api を使用して JWT アクセストークンを検証し、Spring Boot API エンドポイントを保護します。自動構成、スコープベースの認可、組み込みの DPoP（RFC 9449）サポートを備えています。

---

エージェントへの指示： SDK のセットアップ手順を提示する前に、次のコマンドを実行して最新リリースのバージョンを取得してください。

gh api repos/auth0/auth0-auth-java/releases/latest --jq '.tag_name'

ハードコードされたバージョンの代わりに、依存関係の記述すべてで取得したバージョンを使用してください。API 呼び出しに失敗した場合（リリースがまだない場合など）は、1.0.0-beta.1 を使用してください。

前提条件

• Java 17 以降、Spring Boot 3.2 以降
• Maven 3.6 以降、または Gradle 7 以降
• Auth0 API が構成済みであること（Application ではなく、API リソースである必要があります）
• Auth0 の設定がまだの場合は、最初に auth0-quickstart スキルを使用してください

使用しないケース

ユースケース	推奨スキル
サーバーサイドレンダリングの Web アプリケーション（セッションを使用する Spring MVC）	ログイン UI を備えた Spring Boot Web アプリには auth0-java を使用してください
シングルページアプリケーション	クライアント側の認証には auth0-react、auth0-vue、または auth0-angular を使用してください
モバイルアプリケーション	ネイティブモバイルアプリには auth0-android または auth0-swift を使用してください
Spring を使用しない Java API	素の Spring Security には auth0-spring-security-api を使用してください

---

クイックスタートのワークフロー

エージェントへの指示： ユーザーのプロンプトに Auth0 の認証情報（ドメイン、オーディエンス）がすでに含まれている場合は、それらをそのまま使用し、ブートストラップスクリプトと認証情報に関する質問を省略してください。セットアップ方法の選択肢を提示するのは、認証情報がない場合に限ります。

1. SDK をインストールする

Gradle（build.gradle）：

implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.1'

Maven（pom.xml）：

<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>auth0-springboot-api</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>

2. Auth0 API を作成する

Auth0 に API（Application ではありません）が必要です。

停止して、先にユーザーに確認してください。

次の質問をそのまま尋ね、ほかの操作を行わずに回答を待ってください。

「Auth0 API リソースをどのように作成しますか？

1. 自動 — Auth0 CLI スクリプトを実行してリソースを作成し、値を application.yml に自動的に書き込みます。
2. 手動 — Auth0 Dashboard（または auth0 apis create）で API を作成し、Domain と Audience を教えてください。

どちらを希望しますか？（1 = 自動／2 = 手動）」

ユーザーが回答するまで、セットアップ手順に進まないでください。手動を既定にしないでください。

ユーザーが自動を選んだ場合は、完全な CLI スクリプトが記載されたセットアップガイドに従ってください。自動の手順では application.yml が書き込まれるため、以下のステップ 3 を省略し、ステップ 4 に直接進んでください。

ユーザーが手動を選んだ場合は、セットアップガイドの「手動セットアップ」セクションに従ってください。その後、ステップ 3 に進んでください。

手動で API を作成する際の簡易リファレンス：

# Using Auth0 CLI
auth0 apis create \
  --name "My Spring Boot API" \
  --identifier https://my-springboot-api

または、Auth0 Dashboard → Applications → APIs で手動作成します。

3. application.yml を構成する

auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://my-springboot-api"

重要： Domain に https:// を含めないでください。このライブラリが issuer URL を自動的に構成します。

application.properties を使用する場合：

auth0.domain=your-tenant.auth0.com
auth0.audience=https://my-springboot-api

4. Spring Security を構成する

@Configuration
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain apiSecurity(
            HttpSecurity http,
            Auth0AuthenticationFilter authFilter
    ) throws Exception {
        return http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public").permitAll()
                .requestMatchers("/api/protected").authenticated()
                .requestMatchers("/api/admin/**").hasAuthority("SCOPE_admin")
                .anyRequest().authenticated())
            .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
            .build();
    }
}

5. エンドポイントを保護する

@RestController
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/public")
    public ResponseEntity<Map<String, Object>> publicEndpoint() {
        return ResponseEntity.ok(Map.of("message", "Public endpoint - no token required"));
    }

    @GetMapping("/protected")
    public ResponseEntity<Map<String, Object>> protectedEndpoint(Authentication authentication) {
        Auth0AuthenticationToken token = (Auth0AuthenticationToken) authentication;
        return ResponseEntity.ok(Map.of(
            "user", authentication.getName(),
            "email", token.getClaim("email"),
            "scopes", token.getScopes()
        ));
    }
}

6. API をテストする

エージェントへの指示： すべてのコードを書いた後、ビルドが成功することを確認してください。

./gradlew bootRun

または ./mvnw spring-boot:run を実行してください。ビルドに失敗した場合は、原因を特定して修正してください。5〜6 回試しても失敗する場合は、AskUserQuestion を使用してサポートを求めてください。

公開エンドポイントをテストします：

curl http://localhost:8080/api/public

保護されたエンドポイントをテストします（アクセストークンが必要です）：

curl http://localhost:8080/api/protected \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Client Credentials フロー、または Auth0 Dashboard → APIs → Test タブからテストトークンを取得してください。

---

よくある間違い

間違い	修正方法
ドメインにhttps://が含まれている	your-tenant.auth0.com形式のみを使用してください。スキームのプレフィックスは不要です
AudienceがAPI Identifierと一致していない	Auth0 Dashboardで設定したAPI Identifierと完全に一致させる必要があります
Auth0でAPIではなくApplicationを作成している	Auth0 Dashboard → Applications → APIsでAPIリソースを作成する必要があります
SecurityConfigにaddFilterBeforeがない	Auth0AuthenticationFilterはUsernamePasswordAuthenticationFilterより前に追加する必要があります
アクセストークンではなくIDトークンを使用している	API認証にはIDトークンではなくアクセストークンを使用する必要があります
scopeクレームを誤った形式で確認している	スコープはSCOPE_がプレフィックスとして付いた権限に対応します。hasAuthority("SCOPE_read:data")を使用してください
Spring Bootの環境変数バインディング	プロパティ名の内部にアンダースコアを含むAUTH0_DOMAINではなく、AUTH0_DOMAINを使用してください。Springはハイフンを削除し、大文字と小文字を区別しません

---

スコープベースの認可

フィルターチェーン、@PreAuthorize、またはプログラムによるチェックを使ったスコープベースのアクセス制御の定義と適用については、Integration Guideを参照してください。

---

DPoPのサポート

RFC 9449に準拠した、組み込みのProof-of-Possessionトークンバインディングです。設定モード（DISABLED、ALLOWED、REQUIRED）については、Integration Guideを参照してください。

---

関連スキル

• auth0-quickstart — Auth0の基本設定とアカウント作成
• auth0-java — ログインUIを備えたSpring Boot Webアプリ（Regular Web Application）

---

クイックリファレンス

設定プロパティ（application.yml）：

• auth0.domain — Auth0テナントのドメイン。https://プレフィックスは不要です（必須）
• auth0.audience — Auth0 APIの設定にあるAPI Identifier（必須）
• auth0.dpop-mode — DPoPモード：DISABLED、ALLOWED（デフォルト）、REQUIRED
• auth0.dpop-iat-offset-seconds — DPoP証明の時間枠（デフォルト：300）
• auth0.dpop-iat-leeway-seconds — DPoP証明の許容時間（デフォルト：30）

ユーザークレーム（Auth0AuthenticationToken経由）：

• authentication.getName() — ユーザーID（subject／subクレーム）
• token.getClaim("email") — 名前を指定した任意のクレーム
• token.getClaims() — すべてのJWTクレームを含むMap<String, Object>
• token.getScopes() — Set<String>としてのスコープ

よくある使用例：

• ルートを保護 → requestMatchers("/path").authenticated()（ステップ4を参照）
• スコープの適用 → hasAuthority("SCOPE_read:data")または@PreAuthorize（Integration Guideを参照）
• DPoPトークンバインディング → Integration Guide
• APIリファレンス全体 → API Reference

---

詳細ドキュメント

• セットアップガイド — Auth0 CLIによる自動化、環境設定、シークレット管理
• インテグレーションガイド — スコープポリシー、DPoP、コントローラーパターン、エラー処理
• APIリファレンス — 設定オプション全般、クレームリファレンス、テストチェックリスト

---

参考資料

• Auth0 Java Spring Security APIクイックスタート
• SDK GitHubリポジトリ
• Spring Securityドキュメント
• アクセストークンガイド
• DPoP RFC 9449