Java Spring Boot API

保護されたエンドポイントを持つ Spring Boot API に Auth0 JWT 認証を追加する

このクイックスタートは現在 ベータ版 です。ぜひフィードバックをお寄せください。

AI を使って Auth0 を統合する

Claude Code、Cursor、GitHub Copilot などの AI コーディングアシスタントを使用している場合は、agent skills を使って、数分で Auth0 認証を自動的に追加できます。

インストール:

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-springboot-api

次に、AI アシスタントに次のように依頼します。

Add Auth0 JWT authentication to my Spring Boot API

AI アシスタントは、Auth0 API の作成、認証情報の取得、Auth0 Spring Boot API SDK 依存関係の追加、application.yml の設定、JWT 検証と保護されたエンドポイントを備えた SecurityFilterChain の実装を自動的に行います。agent skills の完全なドキュメント →

前提条件: 開始する前に、次のものがインストールされていることを確認してください。

• JDK 17+: Spring Boot 3.2+ との互換性のため
• Maven 3.6+ または Gradle 7+: 依存関係管理のため
• 使用する IDE (IntelliJ IDEA、Eclipse、または Java をサポートする VS Code)

Java バージョンの互換性: このクイックスタートは Java 17+ および Spring Boot 3.2+ に対応しています。

​

はじめに

このクイックスタートでは、Spring Boot API に Auth0 JWT 認証を追加する方法を説明します。Auth0 Spring Boot API SDK を使用して、保護されたエンドポイントを持つ安全な API を構築します。

1. 新しいプロジェクトを作成

   このクイックスタート用の新しい Spring Boot API プロジェクトを作成します。

   Spring Initializr を使用する場合:

   curl -L https://start.spring.io/starter.zip \
       -d dependencies=web,security \
       -d javaVersion=17 \
       -d name=auth0-api \
       -d artifactId=auth0-api \
       -d packageName=com.example.auth0api \
       -o auth0-api.zip
   
   mkdir auth0-api && unzip auth0-api.zip -d auth0-api && cd auth0-api
   

   または、Maven で手動作成します。

   mvn archetype:generate \
       -DgroupId=com.example \
       -DartifactId=auth0-api \
       -DarchetypeArtifactId=maven-archetype-quickstart \
       -DinteractiveMode=false
   
   cd auth0-api
   
2. Auth0 SDK を追加

   Auth0 Spring Boot API SDK を、プロジェクトの依存関係に追加します。

   Maven (pom.xml):

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

   Gradle (build.gradle) ：

   dependencies {
       implementation 'com.auth0:auth0-springboot-api:1.0.0-beta.0'
   }
   
3. Auth0 API を設定する

   次に、Auth0テナントで新しいAPIを作成し、その設定をプロジェクトに追加します。

   CLIコマンドを実行して自動的に行う方法と、Dashboardから手動で行う方法のいずれかを選択できます。

   CLI

   Auth0 API を作成し、application.yml ファイルを更新するには、プロジェクトのルートディレクトリで次のシェルコマンドを実行します。

   Mac/Linux

   AUTH0_API_NAME="My Spring Boot API" && \
   AUTH0_API_IDENTIFIER="https://my-springboot-api" && \
   brew tap auth0/auth0-cli && \
   brew install auth0 && \
   auth0 login --no-input && \
   auth0 apis create -n "${AUTH0_API_NAME}" -i "${AUTH0_API_IDENTIFIER}" --offline-access --token-lifetime 86400 --signing-alg RS256 --json > auth0-api-details.json && \
   DOMAIN=$(auth0 tenants list --json | jq -r '.[] | select(.active == true) | .name') && \
   AUDIENCE=$(jq -r '.identifier' auth0-api-details.json) && \
   mkdir -p src/main/resources && \
   printf 'auth0:\n  domain: %s\n  audience: %s\n\nspring:\n  application:\n    name: auth0-api\n' "$DOMAIN" "$AUDIENCE" > src/main/resources/application.yml && \
   rm auth0-api-details.json && \
   echo "✅ application.yml created with your Auth0 API details:" && \
   cat src/main/resources/application.yml
   

   Windows (PowerShell)

   $ApiName = "My Spring Boot API"
   $ApiIdentifier = "https://my-springboot-api"
   $latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/auth0/auth0-cli/releases/latest"
   $latestVersion = $latestRelease.tag_name
   $version = $latestVersion -replace "^v"
   Invoke-WebRequest -Uri "https://github.com/auth0/auth0-cli/releases/download/${latestVersion}/auth0-cli_${version}_Windows_x86_64.zip" -OutFile ".\auth0.zip"
   Expand-Archive ".\auth0.zip" .\
   [System.Environment]::SetEnvironmentVariable('PATH', $Env:PATH + ";${pwd}")
   auth0 login --no-input
   auth0 apis create -n "$ApiName" -i "$ApiIdentifier" --offline-access --token-lifetime 86400 --signing-alg RS256 --json | Set-Content -Path auth0-api-details.json
   $Domain = (auth0 tenants list --json | ConvertFrom-Json | Where-Object { $_.active -eq $true }).name
   $Audience = (Get-Content -Raw auth0-api-details.json | ConvertFrom-Json).identifier
   New-Item -ItemType Directory -Force -Path "src\main\resources"
   @"
   auth0:
     domain: "$Domain"
     audience: "$Audience"
   
   spring:
     application:
       name: auth0-api
   "@ | Set-Content "src\main\resources\application.yml"
   Remove-Item auth0-api-details.json
   Write-Output "✅ application.yml created with your Auth0 API details:"
   Get-Content "src\main\resources\application.yml"
   

   Dashboard

   始める前に、src/main/resources/application.yml ファイルに Auth0 の設定を追加します。

   src/main/resources/application.yml

   auth0:
     domain: "YOUR_AUTH0_DOMAIN"
     audience: "YOUR_AUTH0_API_IDENTIFIER"
   
   spring:
     application:
       name: auth0-api
   

   1. Auth0 Dashboard → Applications → APIs に移動します
   2. Create API を選択します
   3. API の詳細を入力します。
      • Name: My Spring Boot API
      • Identifier: https://my-springboot-api (これがオーディエンスになります)
      • Signing Algorithm: RS256
   4. Create を選択します
   5. application.yml の YOUR_AUTH0_DOMAIN を、テストタブの Domain で置き換えます (例: your-tenant.auth0.com)
   6. application.yml の YOUR_AUTH0_API_IDENTIFIER を Identifier で置き換えます。例: https://my-springboot-api。

   Domain には https:// を含めないでください。ドメインとリージョンのみを使用します。例: your-tenant.auth0.com。

   Audience (API Identifier) は API の一意の識別子であり、有効な URI であれば任意の値を指定できます。一般公開された URL である必要はありません。

4. 認証を設定する

   Auth0 JWT 認証を有効にするセキュリティ構成クラスを作成します。src/main/java/com/example/auth0api/SecurityConfig.java を作成します。

   src/main/java/com/example/auth0api/SecurityConfig.java

   package com.example.auth0api;
   
   import com.auth0.spring.boot.Auth0AuthenticationFilter;
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.security.config.annotation.web.builders.HttpSecurity;
   import org.springframework.security.config.http.SessionCreationPolicy;
   import org.springframework.security.web.SecurityFilterChain;
   import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;
   
   @Configuration
   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/private").authenticated()
                   .anyRequest().permitAll())
               .addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)
               .build();
       }
   }
   
5. 公開エンドポイントと保護エンドポイントを作成する

   認証をテストするための API エンドポイントを作成します。src/main/java/com/example/auth0api/ApiController.java を作成します。

   src/main/java/com/example/auth0api/ApiController.java

   package com.example.auth0api;
   
   import com.auth0.spring.boot.Auth0AuthenticationToken;
   import org.springframework.http.ResponseEntity;
   import org.springframework.security.core.Authentication;
   import org.springframework.web.bind.annotation.GetMapping;
   import org.springframework.web.bind.annotation.RequestMapping;
   import org.springframework.web.bind.annotation.RestController;
   
   import java.util.Map;
   
   @RestController
   @RequestMapping("/api")
   public class ApiController {
   
       // パブリックエンドポイント - 認証不要
       @GetMapping("/public")
       public ResponseEntity<Map<String, String>> publicEndpoint() {
           return ResponseEntity.ok(Map.of(
               "message", "This endpoint is public - no authentication required"
           ));
       }
   
       // 保護されたエンドポイント - 認証が必要
       @GetMapping("/private")
       public ResponseEntity<Map<String, Object>> privateEndpoint(Authentication authentication) {
           Auth0AuthenticationToken auth0Token = (Auth0AuthenticationToken) authentication;
   
           return ResponseEntity.ok(Map.of(
               "message", "This endpoint requires authentication",
               "user", authentication.getName(),
               "scopes", auth0Token.getAuthorities()
           ));
       }
   }
   
6. API を起動する

   Spring Boot アプリケーションを起動します。

   Maven:

   ./mvnw spring-boot:run
   

   Gradle:

   ./gradlew bootRun
   

   API は http://localhost:8080 で実行中です (正確な URL はコンソール出力を確認してください) 。

チェックポイント

これで、Auth0 で保護された API が localhost 上で完全に動作しているはずです。

---

​

高度な使い方

保護されたAPIの呼び出し

アクセストークンを使用して、保護されたエンドポイントをテストします。

1. Client Credentials フローを使用して Auth0 からアクセストークンを取得します。

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials"}'

YOUR_CLIENT_ID と YOUR_CLIENT_SECRET を取得するには、Auth0 Dashboard で Machine to Machine Application を作成し、 API へのアクセスを認可します。

2. 公開エンドポイントをテストします (200 OK が返されるはずです) 。

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

3. 認証なしで保護されたエンドポイントをテストします (401 Unauthorized が返されるはずです) 。

curl http://localhost:8080/api/private

4. トークンを使用して保護されたエンドポイントを呼び出します。

curl http://localhost:8080/api/private \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

JWT クレームへのアクセス

エンドポイントで、追加のユーザー情報やトークンクレームにアクセスします。

@GetMapping("/profile")
public ResponseEntity<Map<String, Object>> getUserProfile(Authentication authentication) {
    Auth0AuthenticationToken auth0Token = (Auth0AuthenticationToken) authentication;
    Map<String, Object> claims = auth0Token.getAuthenticationContext().getClaims();

    return ResponseEntity.ok(Map.of(
        "userId", authentication.getName(),
        "email", claims.get("email"),
        "scope", claims.get("scope"),
        "issuer", claims.get("iss"),
        "audience", claims.get("aud")
    ));
}

スコープベースの認可

セキュリティをさらに強化するために、JWT スコープを使用したきめ細かなアクセス制御を実装します。

1. Auth0 API でスコープを定義します。

Auth0 Dashboard → APIs → Your API → Permissions で、スコープを追加します。

• read:users - ユーザーデータの読み取り
• write:users - ユーザーデータの書き込み
• admin - 管理者アクセス

2. 認可ポリシーを設定します。

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

アクセストークンをリクエストする際は、必要なスコープを含めます。

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","audience":"YOUR_AUDIENCE","grant_type":"client_credentials","scope":"read:users write:users admin"}'

DPoPによるセキュリティ強化

アクセストークンを暗号鍵に関連付けてトークンのセキュリティを強化するため、DPoP (Demonstration of Proof-of-Possession) を有効にします。

application.yml で DPoP サポートを設定します。

auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://my-springboot-api"
  dpopMode: ALLOWED # DISABLED、ALLOWED（デフォルト）、REQUIRED
  dpopIatOffsetSeconds: 300 # 5分（デフォルト）
  dpopIatLeewaySeconds: 60 # 1分の許容時間（デフォルト: 30秒）

DPoP モード:

• ALLOWED (デフォルト) : Bearer トークンと DPoP トークンの両方を受け入れます

• REQUIRED: DPoP トークンのみを受け入れ、Bearer トークンは拒否します

• DISABLED: 標準の JWT Bearer 検証のみ

  DPoP の詳細については、Auth0 DPoP Documentation を参照してください。

---

​

よくある問題

401 Unauthorized - 無効なオーディエンス

問題: 有効なトークンを使用していても、API から 401 が返されます。

解決策: auth0.audience が Auth0 API 識別子と完全に一致していることを確認してください。トークン内の audience クレームは、この値と一致している必要があります。

# ❌ 誤り
auth0:
  audience: "my-api"

# ✅ 正しい
auth0:
  audience: "https://my-springboot-api"

401 Unauthorized - 無効な発行元

問題: トークンの発行元の検証に失敗します。

解決策: ドメインが正しく、https:// が含まれていないことを確認してください。https:// プレフィックスなしのドメインを使用します。

# ❌ 誤り
auth0:
  domain: "https://your-tenant.auth0.com"

# ✅ 正しい
auth0:
  domain: "your-tenant.auth0.com"

設定値が見つかりません

問題: 設定エラーにより、アプリケーションの起動に失敗します。

解決策: application.yml の構造とプロパティ名を確認してください。auth0 セクションにドメインとオーディエンスの値が含まれていることを確認します。

# ✅ 正しい構造
auth0:
  domain: "your-tenant.auth0.com"
  audience: "https://your-api-identifier"

spring:
  application:
    name: auth0-api

フィルター順序の問題

問題: 設定が正しいにもかかわらず、認証が機能しません。

解決策: Auth0AuthenticationFilter が Spring Security チェーンに適切に組み込まれていることを確認してください。フィルターは UsernamePasswordAuthenticationFilter より前に追加する必要があります。

// ✅ 正しいフィルター順序
.addFilterBefore(authFilter, UsernamePasswordAuthenticationFilter.class)

ネットワーク接続の問題

問題: JWKS の取得に失敗するか、接続タイムアウトが発生します。

解決策: 企業のファイアウォールが Auth0 エンドポイントをブロックしている可能性があります。HTTPS アクセス用に Auth0 ドメインを許可リストに追加してください。

# 必要なファイアウォールルール（アウトバウンド HTTPS/443）
*.auth0.com
*.us.auth0.com  # US リージョンのテナント用
*.eu.auth0.com  # EU リージョンのテナント用
*.au.auth0.com  # AU リージョンのテナント用

認可ポリシーで Scopes が機能しない

問題: スコープベースの認可ポリシーが常に失敗します。

解決策: アクセストークンに必要なスコープが含まれていることを確認してください。トークンをリクエストするときは、スコープを指定します。

curl --request POST \
  --url https://YOUR_DOMAIN/oauth/token \
  --data '{"client_id":"...","client_secret":"...","audience":"...","grant_type":"client_credentials","scope":"read:users write:users admin"}'

また、Auth0 API の設定でスコープが定義されていることも確認してください (Dashboard → APIs → Your API → Permissions) 。

---

​

追加リソース

SDK ドキュメント

SDK の完全なドキュメントと API リファレンス

コード例

包括的なコード例と統合パターン

DPoP ドキュメント

proof-of-possession によるセキュリティ強化について確認する

Spring Security リファレンス

Spring Security の公式ドキュメント

Auth0 Dashboard

Auth0 の API とアプリケーションを管理する

コミュニティフォーラム

Auth0 コミュニティからサポートを受ける

---

​

サンプルアプリケーション

すべての機能を実演する完全なサンプルアプリケーションが、SDK リポジトリで公開されています。

プレイグラウンドアプリケーション

公開エンドポイントと保護されたエンドポイント、DPoP サポート、および包括的な サンプルが含まれています

クローンして実行します:

git clone https://github.com/auth0/auth0-auth-java.git
cd auth0-auth-java/auth0-springboot-api-playground

# Auth0の設定でsrc/main/resources/application.ymlを更新してください
# 次に実行してください:
./mvnw spring-boot:run

curl でのテスト:

# 公開エンドポイントをテスト
curl http://localhost:8080/api/public

# アクセストークンを取得（Auth0の認証情報に置き換えてください）
curl -X POST https://YOUR_DOMAIN/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://my-springboot-api",
    "grant_type": "client_credentials"
  }'

# Bearerトークンを使用して保護されたエンドポイントをテスト
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     http://localhost:8080/api/private