Java Springboot API

この Quickstart は現在 Beta です。ぜひフィードバックをお寄せください！

AI を使って Auth0 を統合する

Claude Code、Cursor、GitHub Copilot などの AI コーディングアシスタントを使えば、Agent Skills を使って数分で Auth0認証を自動的に追加できます。インストール:

npx skills add auth0/agent-skills --skill auth0

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

Add Auth0 JWT authentication to my Spring Boot API

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

前提条件: 始める前に、以下がインストールされていることを確認してください。

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

Java バージョンの互換性: この Quickstart は Java 17+ および Spring Boot 3.2+ で動作します。

はじめましょう

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

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

このQuickstart向けに、新しい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

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'
}

Auth0 APIを設定する

次に、Auth0 テナントで新しい API を作成し、プロジェクトに設定を追加します。CLIコマンドを実行して自動的に行う方法と、Auth0 Dashboardから手動で行う方法のいずれかを選択できます。

CLI
Dashboard

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

Mac/Linux
Windows (PowerShell)

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

$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"

始める前に、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

Auth0 Dashboard → アプリケーション → APIs に移動します
Create API を選択します
API の詳細を入力します。
- Name: My Spring Boot API
- Identifier: https://my-springboot-api (これが Audience になります)
- Signing Algorithm: RS256
Create を選択します
application.yml の YOUR_AUTH0_DOMAIN を、Test タブにある Domain (例: your-tenant.auth0.com) に置き換えます
application.yml の YOUR_AUTH0_API_IDENTIFIER を、Identifier に置き換えます。例: https://my-springboot-api

Domain には https:// を含めないでください。ドメイン名のみを指定します。例: your-tenant.auth0.comAudience (API 識別子) は API を一意に識別する値で、有効な URI であれば任意のものを使用できます。公開されている URL である必要はありません。

認証を設定する

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();
    }
}

公開エンドポイントと保護されたエンドポイントを作成する

認証をテストするための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()
        ));
    }
}

APIを実行する

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

./mvnw spring-boot:run

Gradle:

./gradlew bootRun

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

チェックポイントこれで、Auth0 で保護された API が localhost 上で正常に動作しているはずです。

高度な使用方法

保護された API の呼び出し

アクセストークンを使って、保護されたエンドポイントをテストします。1. クライアント認証情報フローを使用して、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 アプリケーションを作成し、その 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 - 無効な audience

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

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

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

401 Unauthorized - 無効な発行者

問題: トークンの発行者のバリデーションに失敗します。解決策: Domain が正しく、https:// を含んでいないことを確認してください。https:// なしのドメインを使用します。

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

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

設定値が見つかりません

問題: アプリケーションが設定エラーのため起動に失敗します。解決策: application.yml の構造とプロパティ名を確認してください。auth0 セクションに domain と audience の値が含まれていることを確認します。

# ✅ 正しい構造
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 リージョンのテナント向け

認可ポリシーでスコープが機能しない

問題: スコープベースの認可ポリシーが常に失敗します。解決策: access token に必要なスコープが含まれていることを確認してください。トークンをリクエストする際は、スコープを指定します。

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 の設定でも定義されていることを確認してください (Auth0 Dashboard → APIs → Your API → Permissions) 。

追加リソース

SDKドキメント

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

コード例

豊富なコード例と連携パターン

DPoPドキュメント

Proof-of-Possessionによるセキュリティ強化について詳しく学ぶ

Spring Securityリファレンス

Spring Securityの公式ドキュメント

Auth0 Dashboard

Auth0 APIやアプリケーションを管理

コミュニティフォーラム

Auth0 Communityでサポートを受ける

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

すべての機能を網羅した完全なサンプルアプリケーションを、SDK リポジトリで利用できます。

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

公開エンドポイントと保護されたエンドポイント、DPoP のサポート、豊富な例が含まれています

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

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

# src/main/resources/application.yml をAuth0の設定で更新してください
# 次に実行してください:
./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

Quickstarts

Auth0 の概要

Auth0 を設定する

アプリケーション

はじめましょう

高度な使用方法

よくある問題

追加リソース

SDKドキメント

コード例

DPoPドキュメント

Spring Securityリファレンス

Auth0 Dashboard

コミュニティフォーラム

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

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

​はじめましょう

​高度な使用方法

​よくある問題

​追加リソース

SDKドキメント

コード例

DPoPドキュメント

Spring Securityリファレンス

Auth0 Dashboard

コミュニティフォーラム

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

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

はじめましょう

高度な使用方法

よくある問題

追加リソース

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