連携の概要

Swaymoon アカウントで、サイトやアプリにサインインを連携できます。Swaymoon アカウントは OAuth 2.1 と OpenID Connect に準拠した IdP です。ユーザーが公式ドメインでサインインと認可を終えると、アプリは認可コードをトークンに交換し、ユーザー情報を読めます。

このページは「Swaymoon デベロッパ」→「ガイド」→「識別子」にあります。クライアントの登録と管理は デベロッパポータル を使い、同ディレクトリの「登録と設定」を先に読んでください。

デベロッパ向けドキュメントを見るには、ドキュメントサイト右上のデベロッパモードをオンにしてください。

ドキュメント一覧

この「識別子」ディレクトリ：

環境とエンドポイント

ローカル連携では Issuer は多くの場合 http://127.0.0.1:10001 です。実際の値は環境変数に従ってください。常にディスカバリ文書の URL を正として扱い、変わりうるパスをハードコードしないでください。

よく使うプロトコルエンドポイント（接頭辞は Issuer）：

ID Token の署名は ES256（楕円曲線）です。ポータルは 3 種類のクライアントをサポートし、いずれも PKCE 必須（S256）です：

推奨する連携手順

sequenceDiagram
  participant App as あなたのアプリ
  participant Browser as ユーザーのブラウザ
  participant Passport as アカウント

  App->>Browser: 302 で認可エンドポイントへ（PKCE 付き）
  Browser->>Passport: サインイン（必要な場合）
  Browser->>Passport: 権限に同意
  Passport->>Browser: 302 で redirect_uri?code= へ
  Browser->>App: authorization code を渡す
  App->>Passport: POST token（code + verifier。機密は Basic、JWT は client_assertion も）
  Passport->>App: access_token + id_token（機密と JWT は refresh_token も）
  App->>Passport: GET UserInfo
  Passport->>App: ユーザークレーム

1. デベロッパポータル で「登録と設定」に従い識別子を登録し、機密、非機密、または JWT アサーションを選びます。機密クライアントは一度だけ表示される client_secret を安全に保管してください。JWT アサーションは公開鍵だけをポータルへ提出し、秘密鍵はサーバーに残します。
2. 「認可コードと PKCE」に従い認可コードフローを実装します（PKCE 必須）。
3. id_token を検証し（Issuer、audience、署名、有効期限）、Access Token で UserInfo を呼び出します。
4. アカウントが返す sub を自前ユーザーの主キーにします（pairwise。詳細は「トークンとユーザー情報」）。

設計の要点（先に読む）

• 認可コード + PKCE：ポータルアプリは code_challenge を省略できません。
• 機密クライアント：トークン交換時は HTTP Basic（client_id / client_secret）を使い、あわせて code_verifier を送ります。
• 非機密クライアント：client_secret はありません。トークン交換時はフォームに client_id と code_verifier を送ります。「あることにしたシークレット」をフロントに書かないでください。「生成 AI で非機密クライアントを連携する」と「Python の最小実行例」を参照。
• JWT アサーションクライアント：client_secret はありません。トークン交換時はフォームに client_id、code_verifier、秘密鍵で署名した client_assertion（ES256）を送ります。ポータルは公開鍵だけを保存します。秘密鍵はアップロードせず、フロントにも置かないでください。概念と取捨は「登録と設定」、リクエスト形式は「認可コードと PKCE」を参照。
• 同意ページ：ユーザーは毎回認可ページで明示確認します（黙ってスキップしません）。openid は常に必須。email とプロフィール細目は必須・任意・申請なしにできます。必須にするときはポータルで理由とプライバシーポリシーが必要です。権限が変わると、ユーザーは追加 / 削減の対照を見ます。すでに本番の古いクライアントはこのためコードを変えなくて構いません。新規クライアントは最新の「権限と同意」に従ってください。
• Pairwise sub：同一ユーザーでもデベロッパチームが違えば sub は異なり、各チーム内では安定します。メールを唯一の主キーにしないでください。
• メールクレーム：email が付与されているとき、UserInfo は連絡可能なメールを返します。ユーザーは通常メールかプライバシーメール（中継アドレス。実メールは渡されません）を選べます。どちらも通常メールとして扱ってください。アカウントの主キーは sub です。

コンプライアンスとブランド

• サインインと認可は公式アカウントドメインへ遷移させてください。偽のログインページを自作してパスワードを集めないでください。
• 業務に必要な最小の scope だけを要求してください。
• アカウントとデベロッパポータルの「利用規約」「濫用防止ポリシー」を守ってください。デベロッパ連携の問い合わせは hello@swaymoon.com です。

次のステップ：「登録と設定」のあと、「認可コードと PKCE」を実装してください。