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

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

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

前提条件:

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

​

はじめに

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

1. 新しいHonoアプリケーションを作成

   create-hono ユーティリティを使って、新しい Hono アプリケーションを作成します。

   npm create hono@latest auth0-hono-app && cd auth0-hono-app
   

   nodejs テンプレートを選択

2. 依存関係をインストールする

   Auth0のミドルウェアをインストールします。

   npm install @auth0/auth0-hono
   

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

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

   npm install -D dotenv
   

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

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

     "scripts": {
       "start": "node --env-file=.env dist/index.js"
     }
   
3. Auth0 アプリケーションを作成する

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

   CLI

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

   Mac

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

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

   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 ファイルを生成します

   Dashboard

   手動で設定する手順:

   1. Auth0 Dashboard に移動します
   2. アプリケーション → アプリケーションを作成 → Regular Web Application
   3. アプリの設定で以下を設定します:

   Allowed Callback URLs

   http://localhost:3000/auth/callback
   

   Allowed Logout URLs

   http://localhost:3000
   

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

   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 を使用してください。

4. Auth0 ミドルウェアで Hono Webサーバーをセットアップする

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

   ./src/index.ts

   // 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}`);
   });
   
5. アプリを起動する

   サーバーを起動し、http://localhost:3000を開きます。

   npm run dev
   

チェックポイント

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

​

トラブルシューティング

よくある問題

コールバック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. 変更後、開発サーバーを再起動します。

セッションの復号 / JWEDecryptionFailed

原因: AUTH0_SESSION_ENCRYPTION_KEY が設定されていないか短すぎるか、古いシークレットの Cookie が残っている状態でこの値を変更した可能性があります。

対処:

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

ルートが404になる（例: /auth/login が 404 を返す）

原因: ミドルウェアがインストールされていないか、ルート登録の後で設定されています。

対処:

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

本番環境で環境変数が見つからない

原因: デプロイ先のプラットフォームで環境変数が提供されていないか、別の名前が使われています。

対処:

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

​

高度な使い方

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

​

ベストプラクティスとセキュリティ

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

---