メインコンテンツへスキップ
このクイックスタートは現在 ベータ版 です。ぜひフィードバックをお寄せください。

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から手動で行う方法のいずれかを選択できます。
Auth0 API を作成し、application.yml ファイルを更新するには、プロジェクトのルートディレクトリで次のシェルコマンドを実行します。
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
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 上で完全に動作しているはずです。

​
高度な使い方

アクセストークンを使用して、保護されたエンドポイントをテストします。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'
エンドポイントで、追加のユーザー情報やトークンクレームにアクセスします。
@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 (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 を参照してください。

​
よくある問題

問題: 有効なトークンを使用していても、API から 401 が返されます。解決策: auth0.audience が Auth0 API 識別子と完全に一致していることを確認してください。トークン内の audience クレームは、この値と一致している必要があります。
# ❌ 誤り
auth0:
  audience: "my-api"

# ✅ 正しい
auth0:
  audience: "https://my-springboot-api"
問題: トークンの発行元の検証に失敗します。解決策: ドメインが正しく、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 リージョンのテナント用
問題: スコープベースの認可ポリシーが常に失敗します。解決策: アクセストークンに必要なスコープが含まれていることを確認してください。トークンをリクエストするときは、スコープを指定します。
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