生成 AI で機密クライアントを連携する

このページは、生成 AI を使って 機密クライアント で OAuth 2.1 / OpenID Connect（OIDC）サインインを連携したいデベロッパ向けです。プロトコルを体系的に学んでいなくても、この手順で基礎連携まで進められます。

全体は 4 ステップです：

1. このページのプロンプトを AI に渡す。
2. AI が出力した Redirect URI（リダイレクト URI） を、Swaymoon デベロッパの識別子ウィザードに登録する（機密クライアントを選ぶ）。
3. ポータルが発行した client_id と client_secret をサーバーの環境変数に設定する。
4. アプリを起動し、「Swaymoon アカウントでサインイン」 ボタンをテストする。

このページのプロンプトは、シークレットを保管できるサーバーランタイムがあるアプリ向けです。プロジェクトが純 HTML、静的サイト、ブラウザのみなら、「生成 AI で非機密クライアントを連携する」と「Python の最小実行例」を読んでください。client_secret を捏造しないでください。

アーキテクチャが不明なら、プロンプトは AI に先に確認させます。従来バックエンド、API Route、Serverless Function、BFF（Backend for Frontend）など、client_secret を安全に置けるランタイムがあるか。

重要なセキュリティ

client_secret は機密クライアントの認証資格情報です。サーバーにだけ置いてください。AI に送らず、フロントのコード、クライアントから見える環境変数、Git リポジトリにも書かないでください。非機密クライアントには client_secret は発行されません。

ステップ 1：プロンプトを AI に渡す

AI コーディングツールでプロジェクトを開き、次のプロンプトをすべてコピーします。

プロンプトに実資格情報を足す必要はありません。AI は先にコード実装を終え、そのあと登録する Redirect URI を出すべきです。

現在のプロジェクトに「Swaymoon アカウント」サインインを連携し、コード変更と必要なテストまで直接完了してください。

操作の目標：
- 適切なサインインページに「Swaymoon アカウントでサインイン」ボタンを追加する。
- ユーザーがボタンを選ぶと、Swaymoon 公式ページへ行ってサインインする。
- 成功後は現在のアプリに戻り、サインイン状態を維持する。

先にプロジェクトのデプロイとランタイム形態を確認してください：
- サーバー、API Route、Serverless Function、BFF があり client_secret を安全に保管できるなら、機密クライアントとして続ける。
- 純 HTML、純静的サイト、またはトークン交換がブラウザでしかできない純 SPA なら：機密クライアントを使わない。ポータルの非機密クライアント（clientType=public、認証方式 none）にし、client_secret なしの PKCE トークン交換で実装する（「生成 AI で非機密クライアントを連携する」「Python の最小実行例」を参照）。
- どの場合も client_secret をブラウザやフロントのコードに置かない。

連携設定：
- Issuer：https://api-passport.swaymoon.com
- Discovery：https://api-passport.swaymoon.com/.well-known/openid-configuration
- フロー：Authorization Code + PKCE（S256）
- サーバーがあるときのクライアント認証：client_secret_basic（機密クライアント）。フロントのみのときは none（非機密クライアント。フォームに client_id + code_verifier。refresh_token なし）
- ID Token 署名アルゴリズム：ES256
- サインイン入口は優先して：GET /auth/swaymoon
- コールバック入口は優先して：GET /auth/swaymoon/callback
- 既定では openid だけを申請する。この製品が本当に必要なときだけ email や具体的なプロフィール細目（name、picture など）を足す。まとめた profile で全部取らない。

実装要件：
1. 現在のフレームワークに合い、保守されている OIDC クライアントライブラリを優先し、Discovery でプロトコルエンドポイントを取る。
2. サーバーで state、nonce、PKCE の code_verifier を生成して保存し、コールバックで厳密に検証する。
3. トークン交換はサーバーだけで SWAYMOON_CLIENT_ID と SWAYMOON_CLIENT_SECRET を使う。
4. JWKS で ID Token の ES256 署名を検証し、iss、aud、exp、iat、nonce も検証する。
5. サーバーで UserInfo を呼び、そこの sub が ID Token の sub と一致することを確認する。
6. sub でローカルユーザーを検索または作成する。email をユーザー主キーにしない。トークンの scope でプロフィールフィールドを解釈する。未認可項目は既定のプレースホルダであり実データではない。
7. このアプリ自身の安全なサインインセッションを作る。ブラウザが保存するのは HttpOnly と妥当な SameSite を付けたアプリセッション Cookie だけ。Swaymoon のトークンは保存しない。本番で HTTPS のときは Secure 必須。
8. サインイン後の遷移先はサイト内相対パスまたは信頼できる許可リストだけ。オープンリダイレクトを避ける。
9. localStorage、sessionStorage、通常 Cookie、ログ、エラーページ、テストスナップショットにシークレットやトークンを保存しない。
10. NEXT_PUBLIC_、VITE_、NUXT_PUBLIC_、PUBLIC_ などの公開変数プレフィックスでシークレットを保存しない。
11. 実値を含まない .env.example を作り、ローカルのシークレットファイルが .gitignore されていることを確認する。
12. 実 client_secret を会話に送れと私に求めない。

完了後、明確で実行できる連携手順を出してください：
1. 「次の行をそのまま Swaymoon デベロッパポータルにコピーしてください」と書き、ローカル開発用の完全な Redirect URI を単独で出力する。
2. 本番で登録すべき完全な Redirect URI。正式ドメインがまだ分からないなら、置き換える部分を明示する。
3. サーバーで設定すべき環境変数と、現在のフレームワークまたはデプロイ基盤のどこに書くか。変数名だけ示し、シークレット値は出さない・推測しない。
4. プロジェクトの起動方法、サインインボタンの見つけ方、1 回のテストの進め方。
5. 変更したファイル。

AI がコード変更を終えたら、次のような出力を探します：

次の行をそのまま Swaymoon デベロッパポータルにコピーしてください：
http://127.0.0.1:3000/auth/swaymoon/callback

上のアドレスは例です。ポートとパスは、AI が現在のプロジェクトに合わせて出した結果に従ってください。

ステップ 2：Redirect URI を登録する

Redirect URI とは？

Redirect URI はデベロッパポータルのウィザードの「リダイレクト URI」で、OAuth クライアントにあらかじめ登録するコールバックエンドポイントです。ユーザーが Swaymoon アカウントで認証と認可確認を終えると、認可サーバーはブラウザをこのアドレスへリダイレクトし、code や state などの認可応答を付けます。

Redirect URI は通常、AI がアプリのバックエンドに作ったコールバックルートに対応し、普通のホームではありません。そのルートが認可応答の検証、トークン交換、アプリセッション作成、サインイン後ページへのリダイレクトを担います。

Redirect URI は通常、アプリ Origin とコールバックパスです。Origin は scheme、host、port を含みます。例：https://app.example.com または http://127.0.0.1:3000。

アプリ Origin + /auth/swaymoon/callback

例：

プロジェクトのルートと待受ポートから AI が出した完全な Redirect URI を優先し、自分で推測しないでください。

完全一致の要件

認可リクエストの redirect_uri は、デベロッパポータルの登録値と 1 文字単位で一致する必要があります。この検証は、認可コードが未登録アドレスへ送られるのを防ぎます。次の差はすべて別 URI です：

• http:// と https:// は違う；
• 127.0.0.1 と localhost は違う；
• ポート 3000 と 3001 は違う；
• 末尾 / の有無も違うことがあります。

したがって AI が出した URI をそのままコピーし、手で直さないでください。AI がローカルと本番を別々に出したなら、デベロッパポータルにそれぞれ登録してください。

デベロッパポータルでの記入

1. Swaymoon デベロッパポータル にサインインします。
2. 識別子を開き、+ で「アプリ識別子を登録」ウィザードを開始します。
3. 説明：同意ページでユーザーが識別できる名前。サーバーがあるときは 機密クライアント を選びます。
4. アイコン：既定でも、アップロードして切り抜いて続けても構いません。
5. リダイレクト URI：AI が出した完全な Redirect URI を貼ります（ローカルと本番は別々に追加可）。
6. 機能：openid は必須のまま。連絡用メールが必要なときだけ email を設定（必須 / 任意 / 申請しない）。プロフィール細目も任意または必須（必須なら理由とプライバシーポリシー）。ユーザーはプライバシーメールを選ぶことがあります。あなたは通常の email として扱ってください。「権限と同意」を参照。
7. 確認のあと「登録」をクリックします。

作成成功後、ポータルはクライアント資格情報を出します（すぐに保存）：

• client_id：認可リクエストを始めるアプリを示す、公開の OAuth クライアント識別子；
• client_secret：機密クライアントの認証資格情報。作成時に一度だけ表示。すぐに安全に保存（非機密クライアントにはこのフィールドはありません）。

ステップ 3：クライアント資格情報を設定する

AI は多くの場合、次のような設定テンプレートをすでに作っています：

SWAYMOON_ISSUER=https://api-passport.swaymoon.com
SWAYMOON_CLIENT_ID=
SWAYMOON_CLIENT_SECRET=
SWAYMOON_REDIRECT_URI=

AI があなたのフレームワーク向けに出した説明に従い、実値をサーバーの環境変数に入れてください。

• ローカル開発では、通常 .gitignore 済みの .env.local などです。
• サイトをデプロイするときは、基盤の Environment Variables、Secrets、または「環境変数」設定ページです。
• SWAYMOON_REDIRECT_URI には、いま登録した完全な Redirect URI を入れます。
• AI がアプリセッション鍵も求めるなら、ローカル端末で指示されたコマンドで乱数を生成し、自分で環境変数に入れてください。生成結果を AI に送り返さないでください。

資格情報のセキュリティ

次はすべて禁止です：

• client_secret を AI の会話に貼らない；
• client_secret を HTML、React、Vue、その他フロントのファイルに書かない；
• NEXT_PUBLIC_、VITE_、NUXT_PUBLIC_、PUBLIC_ などのフロント公開変数に入れない；
• 実シークレット入りの .env を Git にコミットしない；
• Access Token、ID Token、Refresh Token を localStorage に保存しない。

AI が client_secret をフロントに書けと言うなら、その実装をやめ、サーバーまたは BFF でトークン交換してください。

ステップ 4：サインインをテストする

1. AI が出したコマンドでプロジェクトを起動します。
2. サインインボタンがあるページを開きます。
3. 「Swaymoon アカウントでサインイン」 を選びます。
4. Swaymoon 公式ページでサインインと認可を完了します。
5. ブラウザがあなたのアプリに戻り、サインイン済みと表示されます。

ユーザー側に必要なのはサインインボタン 1 つです。認可リダイレクト、コールバック検証、トークン交換、アプリセッション作成はすべてサーバーが行います。

<a href="/auth/swaymoon">Swaymoon アカウントでサインイン</a>

実際のボタンのコンポーネントとスタイルは、AI が現在のプロジェクト向けに生成します。上の HTML を手でコピーする必要はありません。

よくある質問

エラー文を AI に渡して調査を頼めますが、先にクライアント資格情報、トークン、完全なコールバッククエリを除いてください。code= や state= を含む完全なブラウザ URL は送らないでください。

プロトコルとパラメータの全体は「連携の概要」「認可コードと PKCE」「トークンとユーザー情報」「権限と同意」「例とトラブルシューティング」「Python の最小実行例」を読んでください。クライアント登録は同ディレクトリの「登録と設定」です。