OpenID Connect Discovery

OpenID Connect (OIDC) は、OAuth 2.0 プロトコルの上に構築された ID レイヤーであり、Google や Azure Active Directory など、一部の OAuth 2.0 プロバイダーがサポートしています。これは、クライアントアプリケーションがユーザーを認証し、ユーザー名やメールなどのユーザーに関する情報（「クレーム」）を取得できるようにするサインインフローを定義します。ユーザーの ID 情報は、ID トークンと呼ばれる安全な JSON Web Token (JWT) でエンコードされます。OpenID Connect は、OpenID サーバーがそのメタデータを既知の URL（通常は以下の URL）で公開する、OpenID Connect Discovery と呼ばれるディスカバリメカニズムを定義しています。

https://server.com/.well-known/openid-configuration

この URL は、OpenID/OAuth エンドポイント、サポートされているスコープとクレーム、トークンの署名に使用される公開鍵、その他の詳細の JSON リストを返します。クライアントは、この情報を使用して OpenID サーバーへのリクエストを構築できます。フィールド名と値は、OpenID Connect Discovery Specification で定義されています。以下は返されるデータの例です。

1
{
2
  "issuer": "https://example.com/",
3
  "authorization_endpoint": "https://example.com/authorize",
4
  "token_endpoint": "https://example.com/token",
5
  "userinfo_endpoint": "https://example.com/userinfo",
6
  "jwks_uri": "https://example.com/.well-known/jwks.json",
7
  "scopes_supported": ["pets_read", "pets_write", "admin"],
8
  "response_types_supported": ["code", "id_token", "token id_token"],
9
  "token_endpoint_auth_methods_supported": ["client_secret_basic"],
10
  ...,
11
}

OpenID Connect Discovery の記述

OpenAPI 3.0 では、OpenID Connect Discovery を次のように記述できます。

1
openapi: 3.0.4
2
---
3
# 1) Define the security scheme type and attributes
4
components:
5
  securitySchemes:
6
    openId: # <--- Arbitrary name for the security scheme. Used to refer to it from elsewhere.
7
      type: openIdConnect
8
      openIdConnectUrl: https://example.com/.well-known/openid-configuration
9

10
# 2) Apply security globally to all operations
11
security:
12
  - openId: # <--- Use the same name as specified in securitySchemes
13
      - pets_read
14
      - pets_write
15
      - admin

最初のセクション components/securitySchemes は、セキュリティスキームタイプ (openIdConnect) とディスカバリエンドポイントの URL (openIdConnectUrl) を定義します。OAuth 2.0 とは異なり、securitySchemes で利用可能なスコープをリストする必要はありません。クライアントは代わりにディスカバリエンドポイントからそれらを読み取ることになっています。次に、security セクションは選択したセキュリティスキームを API に適用します。API 呼び出しに必要な実際のスコープはここにリストする必要があります。これらはディスカバリエンドポイントによって返されるスコープのサブセットである場合があります。異なる API 操作が異なるスコープを必要とする場合、グローバルではなく操作レベルで security を適用できます。これにより、各操作に関連するスコープをリストできます。

1
paths:
2
  /pets/{petId}:
3
    get:
4
      summary: Get a pet by ID
5
      security:
6
        - openId:
7
          - pets_read
8
      ...
9

10
    delete:
11
      summary: Delete a pet by ID
12
      security:
13
        - openId:
14
          - pets_write
15
      ...

相対 Discovery URL

openIdConnectUrl は、サーバー URL に対して相対的に指定できます。例えば、次のようにです。

1
servers:
2
  - url: https://api.example.com/v2

1
components:
2
  securitySchemes:
3
    openId:
4
      type: openIdConnect
5
      openIdConnectUrl: /.well-known/openid-configuration

相対 URL は RFC 3986 に従って解決されます。上記の例では、_https://api.example.com/.well-known/openid-configuration_ に解決されます。

Swagger UI のサポート

OpenID Connect Discovery のサポートは、Swagger UI v. 3.38.0 および Swagger Editor 3.14.8 で追加されました。

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください