始める · Issuary

issuaryを通じてユーザーを認証したいアプリケーションは、まず OAuth/OIDC クライアントとして登録する必要があります。クライアント登録は config.yamlの clients セクションでできます。

# config.yaml
clients:
  - id: my-app
    name: My Application
    client_id: my-app-client-id
    client_secret: my-app-client-secret
    redirect_uris:
      - https://myapp.example.com/callback
    response_types:
      - code
    grant_types:
      - authorization_code
      - refresh_token
    scope: openid profile email

設定項目

アイテム	必須	説明
`id`	O	クライアントの内部一意の識別子です。
`name`	O	ユーザーに表示されるアプリケーション名です。同意画面に見えます。
`logo_uri`	X	同意画面に表示されるロゴ画像 URLこれです。
`client_id`	O	OAuth リクエストで使用するパブリッククライアント識別子です。
`client_secret`	△	クライアントシークレットです。機密クライアント（サーバー側アプリ）でのみ必要で、公開クライアント（SPA/モバイル)では省略します。
`redirect_uris`	O	認証後にリダイレクトできる許可 URL リストです。
`response_types`	O	許可する OAuth 応答タイプです。一般的に `code`を使用します。
`grant_types`	O	許可する OAuth 認可タイプです。
`scope`	O	許可する OAuth スコープ（空白で区切り）です。

機密クライアント vs 公開クライアント

OAuthでは、クライアントを2つのタイプに分けます。

機密クライアント(Confidential Client)

サーバー側でシークレットを安全に保管できるアプリケーションです。 client_secretを設定し、トークン交換時にシークレットを一緒に送信します。

Next.js、Express、Spring Bootなどのサーバーサイドアプリ
client_secretこの必須

clients:
  - id: web-server-app
    name: Web Server App
    client_id: web-server-client
    client_secret: ${WEB_SERVER_SECRET}
    redirect_uris:
      - https://myapp.com/api/callback
    response_types:
      - code
    grant_types:
      - authorization_code
      - refresh_token
    scope: openid profile email

パブリッククライアント (Public Client)

クライアント側のコードでシークレットを安全に保持できないアプリケーションです。 client_secretを省略し、代わりに PKCE を使用してセキュリティを確保します。

React SPA, Vue SPA、モバイルアプリなど
client_secret 省略

clients:
  - id: spa-app
    name: Single Page App
    client_id: spa-client
    redirect_uris:
      - https://myapp.com/callback
    response_types:
      - code
    grant_types:
      - authorization_code
      - refresh_token
    scope: openid profile email

OIDC Discovery

登録されたクライアントアプリケーションは issuaryの OIDC Discoveryエンドポイントを使用して、認証に必要な情報を自動的にインポートできます。

{server.public_origin}/.well-known/openid-configuration

このエンドポイントは認証、トークン、ユーザー情報、 JWKS などのエンドポイント URLを返します。ほとんど OIDC クライアントライブラリは URLだけで自動設定が可能です。

次のステップ

クライアントを登録した後、実際のアプリケーションに連動する方法については、次のガイドを参照してください。

Next.js 連動 - サーバーサイドアプリ(機密クライアント)
React SPA 連動 - クライアントサイドアプリ(パブリッククライアント)

権限への同意と自社アプリ

ログイン・登録画面にはアプリや権限のバナーを表示しません。認証と必須規約への同意が完了した後、クライアントに戻る直前に、必要な場合だけ OAuth の権限への同意を求めます。

通常のクライアントでは skip_consent を省略するか false にし、通常は prompt も省略します。一度承認した権限は、同じか少ないスコープの後続リクエストで再利用します。追加の権限や同意の撤回がある場合は再承認が必要です。

自社アプリには、登録された権限を管理者が事前承認する skip_consent: true を設定できます。

clients:
  - id: first-party-web
    name: First-party Web App
    client_id: first-party-web
    redirect_uris:
      - https://app.example.com/callback
    response_types: [code]
    grant_types: [authorization_code, refresh_token]
    scope: openid profile email offline_access
    skip_consent: true

この例はパブリッククライアントなので S256 PKCE が必要です。機密クライアントには client_secret も設定します。

事前承認は登録済みのスコープにのみ適用され、許可された offline_access も含みます。ログイン、メール認証、必須の二要素認証、必須規約、リダイレクト URI と PKCE の検証は省略しません。Device Authorization のデバイス承認も必要です。

認証リクエスト	動作
`prompt` なし	セッション、既存の承認、サーバーポリシーに応じて必要な画面を表示します。
`prompt=login`	再認証します。同意はクライアントポリシーに従います。
`prompt=consent`	事前承認されたアプリでも明示的な同意を求めます。
`prompt=none`	画面を表示せず、処理できなければ `login_required`、`consent_required`、`interaction_required` などを返します。

事前承認ではユーザーの同意レコードを作成しません。設定を無効にすると後続の認証リクエストは実際のユーザー同意に基づいて処理され、同意がなければ画面を表示します。ユーザー同意の撤回は管理者の事前承認を解除しません。設定変更で既存のトークンは失効しないため、必要に応じてトークン失効やクライアント管理機能を使います。

オフラインアクセス

Authorization Code Flow では、事前承認、prompt=consent、または有効な既存のオフラインアクセス同意がある場合に offline_access を保持します。Issuary は明示的なオフライン同意を撤回まで継続する承認として扱います。同意画面は不在時のアクセスと、撤回まで権限が継続することを説明します。

承認の根拠がなければ offline_access を除外し、残りのスコープで処理を続けます。認可コードを返さないリクエストでも除外します。同意画面、保存する同意、認可コード、トークン応答は有効なスコープを使用します。offline_access が承認され、クライアントが refresh_token grant を許可している場合のみ refresh token を発行します。

通常のアプリが初めてオフラインアクセスを求める場合は prompt=consent を使用します。明示的な承認後は prompt を省略できます。事前承認された自社アプリは初回から省略できます。

OIDC の同意と承認とオフラインアクセスを参照してください。