> ## Documentation Index
> Fetch the complete documentation index at: https://translations.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Hono アプリケーションにログイン機能を追加する

> この Quickstart では、Auth0 認証を使用して Hono アプリケーションを保護する方法を説明します。手順に従って、Hono アプリにログイン、ログアウト、保護されたルートを追加します。

export const HowToSchema = () => <script type="application/ld+json">
    {'{"@context":"https://schema.org","@type":"HowTo"}'}
  </script>;

export const AuthCodeGroup = ({children, dropdown}) => {
  const [processedChildren, setProcessedChildren] = useState(children);
  useEffect(() => {
    let unsubscribe = null;
    function init() {
      unsubscribe = window.autorun(() => {
        const processChildren = node => {
          if (typeof node === "string") {
            let processedNode = node;
            for (const [key, value] of window.rootStore.variableStore.values.entries()) {
              const escapedKey = key.replaceAll(/[.*+?^${}()|[\]\\]/g, (String.raw)`\$&`);
              processedNode = processedNode.replaceAll(new RegExp(escapedKey, "g"), value);
            }
            return processedNode;
          } else if (Array.isArray(node)) {
            return node.map(processChildren);
          } else if (node && node.props && node.props.children) {
            return {
              ...node,
              props: {
                ...node.props,
                children: processChildren(node.props.children)
              }
            };
          }
          return node;
        };
        setProcessedChildren(processChildren(children));
      });
    }
    if (window.rootStore) {
      init();
    } else {
      window.addEventListener("adu:storeReady", init);
    }
    return () => {
      window.removeEventListener("adu:storeReady", init);
      unsubscribe?.();
    };
  }, [children]);
  return <CodeGroup dropdown={dropdown}>{processedChildren}</CodeGroup>;
};

<HowToSchema />

<Callout icon="pencil" color="#FFC107" iconType="solid">
  このQuickstartは現在**ベータ版**です。ぜひフィードバックをお寄せください！
</Callout>

<Note>
  **前提条件:**

  * **Node.js** 20 LTS 以降
  * **npm** 10+ または **yarn** 1.22+ または **pnpm** 8+
  * 任意: **[jq](https://jqlang.org/)** - Auth0 CLI のセットアップ用、および安全なシークレットを生成するための **openssl**
  * Hono プロジェクトでは Hono >= 3.x を使用してください (ピア依存関係)
</Note>

<div id="get-started">
  ## はじめに
</div>

この Quickstart では、`@auth0/auth0-hono` を使って Hono アプリケーションを保護するための、最小限かつ推奨される方法を紹介します。内容は、リポジトリで推奨されているパターン、つまり環境変数ベースの設定、`app.use(auth0(...))` ミドルウェア、そして必要なルートだけを保護するための `requiresAuth()` に沿っています。

<Steps>
  <Step title="新しいHonoアプリケーションを作成" stepNumber={1}>
    create-hono ユーティリティを使って、新しい Hono アプリケーションを作成します。

    ```shellscript theme={null}
    npm create hono@latest auth0-hono-app && cd auth0-hono-app
    ```

    `nodejs` テンプレートを選択
  </Step>

  <Step title="依存関係をインストールする" stepNumber={2}>
    Auth0のミドルウェアをインストールします。

    ```shellscript theme={null}
    npm install @auth0/auth0-hono
    ```

    このクイックスタートでは、`.env` ファイルから環境変数を読み込むために `dotenv` パッケージを使用します。

    `dotenv` をローカルにインストールするには:

    ```shellscript theme={null}
    npm install -D dotenv
    ```

    あるいは、依存関係を追加したくない場合は、node's `--env-file` フラグを使ってプロセス起動時に env ファイルを読み込むこともできます。これにより、`dotenv` のインストールやインポートを省略できます。

    `package.json` の `start` スクリプトを次のように変更します。

    ```json theme={null}
      "scripts": {
        "start": "node --env-file=.env dist/index.js"
      }
    ```
  </Step>

  <Step title="Auth0 アプリケーションを作成する" stepNumber={3}>
    Auth0 テナントに Auth0 アプリケーション (Regular Web Application) を作成し、**Domain**、**Client ID**、**Client Secret** をプロジェクトの環境変数として設定します。
    CLI コマンドを実行して Auth0 アプリを自動的に設定することも、Auth0 Dashboard から手動で設定することもできます。

    <Tabs>
      <Tab title="CLI">
        プロジェクトのルートディレクトリで次のシェルコマンドを実行し、Auth0 アプリを作成して `.env` ファイルを生成します。

        <CodeGroup>
          ```shellscript Mac theme={null}
          # Auth0 CLI をインストール（まだインストールしていない場合）
          brew tap auth0/auth0-cli && brew install auth0

          # Auth0 アプリを設定し、.env ファイルを生成
          auth0 qs setup --app --type regular --framework hono --port 3000 --name "My Hono App"
          ```

          ```powershell Windows theme={null}
          # Auth0 CLI をインストール（まだインストールしていない場合）
          scoop bucket add auth0 https://github.com/auth0/scoop-auth0-cli.git
          scoop install auth0

          # Auth0 アプリを設定し、.env ファイルを生成
          auth0 qs setup --app --type regular --framework hono --port 3000 --name "My Hono App"
          ```
        </CodeGroup>

        <Note>
          このコマンドにより、次の処理が行われます。

          1. 認証済みかどうかを確認します (必要に応じてログインを求めます)
          2. `http://localhost:3000` 用に設定された Auth0 Regular Web Application を作成します
          3. `AUTH0_DOMAIN`、`AUTH0_CLIENT_ID`、`AUTH0_CLIENT_SECRET`、`AUTH0_SESSION_ENCRYPTION_KEY`、`BASE_URL` を含む `.env` ファイルを生成します
        </Note>
      </Tab>

      <Tab title="Dashboard">
        手動で設定する手順:

        1. [Auth0 Dashboard](https://manage.auth0.com/dashboard/) に移動します
        2. アプリケーション → アプリケーションを作成 → **Regular Web Application**
        3. アプリの設定で以下を設定します:

        **Allowed Callback URLs**

        ```
        http://localhost:3000/auth/callback
        ```

        **Allowed Logout URLs**

        ```
        http://localhost:3000
        ```

        4. プロジェクトのルートに `.env` ファイルを作成し、以下の値を設定します:

        ```env theme={null}
        AUTH0_DOMAIN=YOUR_AUTH0_DOMAIN
        AUTH0_CLIENT_ID=YOUR_AUTH0_CLIENT_ID
        AUTH0_CLIENT_SECRET=YOUR_AUTH0_CLIENT_SECRET
        APP_BASE_URL=http://localhost:3000
        AUTH0_SESSION_ENCRYPTION_KEY=your_32_char_min_secret
        # API の場合は任意
        AUTH0_AUDIENCE=YOUR_API_IDENTIFIER
        ```

        注: `AUTH0_SESSION_ENCRYPTION_KEY` は 32 文字以上である必要があります。生成するには `openssl rand -hex 32` を使用してください。
      </Tab>
    </Tabs>
  </Step>

  <Step title="Auth0 ミドルウェアで Hono Webサーバーをセットアップする" stepNumber={4}>
    `index.ts` ファイル内の初期テンプレートを、次の例に置き換えてください。このコード例では、環境変数を自動的に読み込む設定不要の構成を示しており、デフォルトで公開ルートを持つ `auth0()` ミドルウェアと、`requiresAuth()` を使用する保護されたルートを作成します。

    ```typescript ./src/index.ts wrap lines theme={null}
    // src/index.ts
    import { serve } from '@hono/node-server';
    import { Hono } from 'hono';
    import { auth0, requiresAuth, Auth0Error, type OIDCEnv } from '@auth0/auth0-hono';

    const app = new Hono<OIDCEnv>();

    // ゼロ設定: AUTH0_DOMAIN、AUTH0_CLIENT_ID、AUTH0_CLIENT_SECRET、
    // APP_BASE_URL、AUTH0_SESSION_ENCRYPTION_KEY を環境変数から読み込む
    app.use(
      auth0({
        authRequired: false, // デフォルトで公開、特定のルートを保護
      })
    );

    // 公開ルート
    app.get('/', (c) => c.text('Public — no login required'));

    // 保護されたルート
    app.use('/profile/*', requiresAuth());

    app.get('/profile', (c) => {
      const user = c.var.auth0.user;
      return c.json({ message: 'Protected profile', user });
    });

    // エラーハンドリング
    app.onError((err, c) => {
      if (err instanceof Auth0Error) {
        return c.json({ error: err.code, error_description: err.description }, err.status);
      }
      return c.json({ error: 'Internal server error' }, 500);
    });

    const port = Number(process.env.PORT) || 3000;
    serve({ fetch: app.fetch, port }, (info) => {
      console.log(`Server is running on http://localhost:${info.port}`);
    });
    ```
  </Step>

  <Step title="アプリを起動する" stepNumber={5}>
    サーバーを起動し、`http://localhost:3000`を開きます。

    ```shellscript theme={null}
    npm run dev
    ```
  </Step>
</Steps>

<Check>
  **チェックポイント**

  Hono アプリは [http://localhost:3000](http://localhost:3000) で実行されているはずです。`/` ルートは公開されています。`/profile` にアクセスすると、ログイン (未認証の場合) にリダイレクトされ、認証に成功するとプロファイルデータが返されるはずです。
</Check>

<div id="troubleshooting">
  ## トラブルシューティング
</div>

<Accordion title="よくある問題">
  <Accordion title="コールバックURLまたはリダイレクトURLの不一致">
    原因: Auth0 Dashboard で設定した callback URL が、`APP_BASE_URL` とコールバックルートを組み合わせたURL (例: `http://localhost:3000/auth/callback`) と完全に一致していません。

    対処:

    1. `.env` の `APP_BASE_URL` の値を確認します。
    2. Auth0 Dashboard の Allowed Callback URLs に `http://localhost:3000/auth/callback` が含まれていることを確認します。
    3. 変更後、開発サーバーを再起動します。
  </Accordion>

  <Accordion title="セッションの復号 / JWEDecryptionFailed">
    原因: `AUTH0_SESSION_ENCRYPTION_KEY` が設定されていないか短すぎるか、古いシークレットの Cookie が残っている状態でこの値を変更した可能性があります。

    対処:

    * `AUTH0_SESSION_ENCRYPTION_KEY` が 32 文字以上であることを確認します。
    * キーを変更した後、localhost のブラウザー Cookie を削除します。
    * 開発サーバーを再起動します。
  </Accordion>

  <Accordion title="ルートが404になる（例: /auth/login が 404 を返す）">
    原因: ミドルウェアがインストールされていないか、ルート登録の後で設定されています。

    対処:

    * 認証に依存するルートより前に `app.use(auth0(...))` が実行されることを確認します。
    * パッケージがインストールされていることを確認します: `npm ls @auth0/auth0-hono`.
  </Accordion>

  <Accordion title="本番環境で環境変数が見つからない">
    原因: デプロイ先のプラットフォームで環境変数が提供されていないか、別の名前が使われています。

    対処:

    * ホスティングプロバイダーのダッシュボードで、この Quickstart で使用している名前に環境変数を対応付けます。
    * Cloudflare Workers の場合は、セッションや Cookie の処理がプラットフォームに対応していることを確認します。
  </Accordion>
</Accordion>

<div id="advanced-usage">
  ## 高度な使い方
</div>

* 選択的な保護: `app.use(auth0({ authRequired: false }))` を使うとルートはデフォルトで公開され、`app.use('/private/*', requiresAuth())` を使うと特定のパスだけを保護できます。
* サイレントログイン: `attemptSilentLogin()` ミドルウェアを使ってサイレント認証を試みることで、UX を向上させます。
* カスタムのログインフロー: `login({...})` を呼び出して、引き継ぐクエリパラメータ、`redirectAfterLogin`、またはサイレントログインのオプションをカスタマイズします。
* トークン管理: ミドルウェアでは、セッション経由でアクセストークンと ID トークンを利用できます。スコープは最小権限の原則に従って設定し、リフレッシュトークンは安全にローテーションしてください。

<div id="best-practices-security">
  ## ベストプラクティスとセキュリティ
</div>

* 機密情報をソース管理に含めず、環境変数を使用してください。
* 32文字以上の `AUTH0_SESSION_ENCRYPTION_KEY` を使用してください。
* 本番環境では、cookie の `secure` を `true` に設定し、適切な `sameSite` ポリシーを指定してください。
* トークンのスコープは必要最小限にし、API 用のアクセストークンをリクエストする場合にのみ audience を使用してください。
* 認証固有のエラーを適切に処理できるよう、`app.onError` で `Auth0Error` を捕捉してください。

***