auth0-java-mvc-common

Auth0 Java MVC 共通インテグレーション

com.auth0:mvc-auth-commons を使用して、Java Servlet の Web アプリケーションに Auth0 認証を追加します。認可 URL の構築とコールバックの処理を行う AuthenticationController を提供し、セッションベースの認証、Organizations、複数のカスタムドメインをサポートします。

---

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

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

取得したバージョンを、以下にハードコードされているバージョンの代わりに、すべての依存関係の行で使用してください。API 呼び出しに失敗した場合は、1.12.0 を使用してください。

前提条件

• Java 8 以降（Java 17 以降を推奨）
• javax.servlet 3 以降に対応した Servlet コンテナー（Tomcat、Jetty など）
• Maven 3.6 以降、または Gradle 7 以降
• Auth0 の Regular Web Application が設定済みであること
• Auth0 のセットアップがまだの場合は、まず auth0-quickstart スキルを使用してください

使用しないケース

ユースケース	推奨スキル
自動設定を使用する Spring Boot Web アプリケーション	Spring Boot のログインを自動設定するには、Spring Boot + Okta starter を使用してください
Spring Boot REST API（ステートレス JWT）	JWT Bearer トークンを検証するには、auth0-springboot-api を使用してください
シングルページアプリケーション	クライアント側の認証には、auth0-react、auth0-vue、または auth0-angular を使用してください
モバイルアプリケーション	ネイティブモバイルアプリには、auth0-android または auth0-swift を使用してください
マシン間の API 呼び出し	サーバー間通信には、Auth0 Management API SDK を使用してください

---

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

エージェントへの指示： 認証情報の値（ドメイン、クライアント ID、クライアントシークレット）を自分で記述したり、復唱したりしないでください。ユーザーのプロンプトに Auth0 の認証情報がすでに含まれている場合は、認証情報について質問せず、.env ファイルに値を設定するようユーザーに案内してください。変数名とファイルパスを提示し、実際の値は使わず、プレースホルダー（<YOUR_DOMAIN>、<YOUR_CLIENT_ID>、<YOUR_CLIENT_SECRET>）を使用してください。回答内で認証情報を繰り返すことは絶対に避けてください。

シークレットの取り扱いに関するルール：

• Auth0 CLI の出力から client_secret を取得したり、解析したりしないでください。
• Write ツールや Edit ツールを使って、実際の認証情報の値をファイルに書き込まないでください。常にプレースホルダーを使用し、実際の値に置き換えるようユーザーに案内してください。
• .env ファイルは読み込まないでください（既存のシークレットがコンテキストに漏れるのを防ぐため）。
• .env が .gitignore に含まれていることを必ず確認してください。含まれていない場合は、自動的にエントリーを追加してください。

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

Gradle（build.gradle）：

implementation 'com.auth0:mvc-auth-commons:1.12.0'

Maven（pom.xml）：

<dependency>
    <groupId>com.auth0</groupId>
    <artifactId>mvc-auth-commons</artifactId>
    <version>1.12.0</version>
</dependency>

2. Auth0 アプリケーションを作成する

Auth0 で Regular Web Application（SPA または Native ではありません）が必要です。

停止してください。先に進む前に、ユーザーに質問してください。

次の質問をそのまま尋ね、ほかの作業は何もせずに回答を待ってください。

"Auth0 アプリケーションをどのように作成しますか？

1. 自動 — Auth0 CLI コマンドを実行してアプリケーションを作成し、値を設定に自動で書き込みます。
2. 手動 — Auth0 Dashboard（または auth0 apps create）で自分でアプリケーションを作成し、Domain、Client ID、Client Secret を提示します。

どちらにしますか？（1 = 自動／2 = 手動）"

ユーザーが回答するまで、セットアップ手順を進めないでください。手動をデフォルトとして選択しないでください。

ユーザーが「自動」を選択した場合は、 セットアップガイド に従って、Auth0 CLI の手順をすべて実施してください。自動の手順では設定が書き込まれるため、以下のステップ 3 は省略して、ステップ 4 に進んでください。

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

手動でのアプリケーション作成に関するクイックリファレンス：

# Using Auth0 CLI
auth0 apps create \
  --name "My Java Web App" \
  --type regular \
  --callbacks http://localhost:3000/callback \
  --logout-urls http://localhost:3000

または、Auth0 Dashboard → Applications → Applications → Create Application → Regular Web Applications で手動作成してください

3. 認証情報を設定する

認証情報は環境変数として保存してください（ソースコードにハードコードしないでください）。

export AUTH0_DOMAIN="your-tenant.auth0.com"
export AUTH0_CLIENT_ID="your-client-id"
export AUTH0_CLIENT_SECRET="your-client-secret"

または、.env ファイルを使用します（.gitignore に追加してください）。

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

エージェントへの指示： 実際の認証情報の値をファイルに書き込まないでください。代わりに、ユーザーに認証情報を使って .env を作成または更新するよう指示してください。プレースホルダーのみを含むテンプレートを提示してください。.env がまだ .gitignore に含まれていない場合は、必ず追加してください。ユーザーに 「以前に設定している場合は、.env に Auth0 のエントリーが重複していないか確認してください。」 と伝えてください。

Java は .env ファイルを自動的に読み込みません。System.getenv() が読み取るのは OS レベルの環境変数のみです。.env ファイルを生成する場合は、次のいずれかも必ず行ってください。（1）依存関係として dotenv-java を追加し、System.getenv() の代わりに Dotenv.load().get("AUTH0_DOMAIN") を使用する、または（2）サーバーの起動前に source .env を実行するようユーザーに指示する。.envファイルとSystem.getenv()の両方を、読み込みの仕組みなしで使用するコードを生成しないでください。値はnull` になります。

重要： ドメインに https:// を含めないでください。ライブラリが発行者 URL を自動的に構築します。

4. AuthenticationController を初期化する

シングルトンの AuthenticationController インスタンスを作成します。

import com.auth0.AuthenticationController;
import com.auth0.jwk.JwkProviderBuilder;
import com.auth0.jwk.JwkProvider;

public class Auth0Config {

    private static final AuthenticationController controller = createController();

    private static AuthenticationController createController() {
        String domain = System.getenv("AUTH0_DOMAIN");
        String clientId = System.getenv("AUTH0_CLIENT_ID");
        String clientSecret = System.getenv("AUTH0_CLIENT_SECRET");

        JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();

        return AuthenticationController.newBuilder(domain, clientId, clientSecret)
            .withJwkProvider(jwkProvider)
            .build();
    }

    public static AuthenticationController getAuthController() {
        return controller;
    }
}

5. ログインサーブレットを作成する

import com.auth0.AuthenticationController;
import com.auth0.AuthorizeUrl;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebServlet(urlPatterns = {"/login"})
public class LoginServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        AuthenticationController controller = Auth0Config.getAuthController();

        // Build callback URL — omit port for standard ports (80/443) to avoid
        // mismatch with the URL registered in Auth0 Dashboard, especially behind proxies.
        String scheme = request.getScheme();
        int port = request.getServerPort();
        String redirectUrl = scheme + "://" + request.getServerName()
            + ((port == 80 || port == 443) ? "" : ":" + port) + "/callback";

        AuthorizeUrl authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
            .withScope("openid profile email");

        response.sendRedirect(authorizeUrl.build());
    }
}

6. コールバックサーブレットを作成する

import com.auth0.AuthenticationController;
import com.auth0.IdentityVerificationException;
import com.auth0.Tokens;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebServlet(urlPatterns = {"/callback"})
public class CallbackServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        AuthenticationController controller = Auth0Config.getAuthController();

        try {
            Tokens tokens = controller.handle(request, response);

            request.getSession().setAttribute("accessToken", tokens.getAccessToken());
            request.getSession().setAttribute("idToken", tokens.getIdToken());

            response.sendRedirect("/dashboard");
        } catch (IdentityVerificationException e) {
            response.sendRedirect("/login?error=" + e.getCode());
        }
    }
}

7. 認証ミドルウェア（サーブレットフィルター）でルートを保護する

import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import java.io.IOException;

@WebFilter(urlPatterns = {"/dashboard/*", "/api/private/*"})
public class AuthenticationFilter implements Filter {

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) req;
        HttpServletResponse response = (HttpServletResponse) res;
        HttpSession session = request.getSession(false);

        if (session == null || session.getAttribute("idToken") == null) {
            response.sendRedirect("/login");
            return;
        }

        chain.doFilter(req, res);
    }

    @Override
    public void init(FilterConfig filterConfig) {}

    @Override
    public void destroy() {}
}

8. アプリケーションをテストする

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

./gradlew build

または mvn package を実行します。ビルドに失敗した場合は、原因を特定して修正してください。5〜6 回試しても解決しない場合は、AskUserQuestion を使って支援を求めてください。

1. アプリケーションを起動し、http://localhost:3000/login にアクセスします
2. Auth0 Universal Login ページにリダイレクトされます
3. ログイン後、コールバックサーブレットがレスポンスを処理し、/dashboard にリダイレクトします

---

よくある間違い

間違い	修正方法
ドメインに https:// が含まれている	your-tenant.auth0.com の形式のみを使用してください。スキームのプレフィックスは不要です
クライアントシークレットがソースコードにハードコードされている	環境変数または .env ファイルを使用し、.gitignore に追加してください
Regular Web ではなく SPA または Native アプリを作成した	Auth0 Dashboard で Regular Web Application を作成する必要があります
コールバック URL が一致しない	コード内のコールバック URL は、Auth0 Dashboard に登録されているものと完全に一致させる必要があります
openid スコープがない	ID トークンに必要なため、必ずスコープに openid を含めてください
IdentityVerificationException を処理していない	ログインエラーを表示できるよう、コールバックハンドラーでは必ずこの例外を捕捉してください
response_type=token を使用している	Regular Web アプリでは code フロー（デフォルト）を使用する必要があります。インプリシットフローは使用しないでください
ログアウト時にセッションが無効化されていない	Auth0 のログアウトにリダイレクトする前に request.getSession().invalidate() を呼び出してください

---

スコープとオーディエンスの設定

カスタムスコープ、API アクセストークンのオーディエンス、および Organizations のサポートについては、Integration Guide を参照してください。

---

複数のカスタムドメイン（MCD）

DomainResolver による、ユーザーを適切な Auth0 ドメインにルーティングする機能が組み込まれています。設定については、Integration Guide を参照してください。

---

関連スキル

• auth0-quickstart — Auth0 の基本設定とアカウント作成
• auth0-springboot-api — JWT Bearer トークンの検証を行う Spring Boot REST API

---

クイックリファレンス

コアクラス：

• AuthenticationController — メインのエントリーポイントです。認可 URL を構築し、コールバックを処理します
• AuthenticationController.Builder — newBuilder(domain, clientId, clientSecret) を使ってコントローラーを設定します
• AuthorizeUrl — /authorize URL パラメーターを設定するための Fluent ビルダーです
• Tokens — コールバックから取得するアクセストークン、ID トークン、リフレッシュトークンです
• IdentityVerificationException — エラーコードを含む認証エラーです
• DomainResolver — 複数のカスタムドメインをサポートするためのインターフェースです

ビルダーメソッド（AuthorizeUrl）：

• .withScope("openid profile email") — 要求するスコープを設定します
• .withAudience("https://my-api") — API アクセストークンを要求します
• .withOrganization("org_xxx") — 特定の組織に固定します
• .withInvitation("invite_xxx") — 組織への招待を受け入れます
• .withConnection("google-oauth2") — 特定の接続に直接進みます
• .withParameter("key", "value") — カスタム認可パラメーターを追加します

トークンへのアクセス（Tokens）：

• tokens.getAccessToken() — アクセストークン文字列
• tokens.getIdToken() — ID トークン（JWT）文字列
• tokens.getRefreshToken() — リフレッシュトークン（offline_access スコープを要求した場合）
• tokens.getExpiresIn() — トークンの有効期限（秒）
• tokens.getType() — トークンの種類（通常は "Bearer"）
• tokens.getDomain() — トークンを発行した Auth0 ドメイン
• tokens.getIssuer() — トークン発行者の URL

---

詳細ドキュメント

• セットアップガイド — Auth0 CLI による自動化、環境設定、シークレット管理
• 統合ガイド — 組織、MCD、カスタムスコープ、ログアウト、エラー処理、高度なパターン
• API リファレンス — 設定オプション、ビルダーメソッド、クレームのリファレンス、テスト用チェックリストの全詳細

---

参考資料

• Auth0 Java Web アプリ クイックスタート
• SDK GitHub リポジトリ
• Auth0 Universal Login
• 認可コードフロー
• Auth0 Organizations