OpenID Connect Discovery

OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers, such as Google and Azure Active Directory. It defines a sign-in flow that enables a client application to authenticate a user, and to obtain information (or “claims”) about that user, such as the user name, email, and so on. User identity information is encoded in a secure JSON Web Token (JWT), called ID token. OpenID Connect defines a discovery mechanism, called OpenID Connect Discovery, where an OpenID server publishes its metadata at a well-known URL, typically

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

This URL returns a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details. The clients can use this information to construct a request to the OpenID server. The field names and values are defined in the OpenID Connect Discovery Specification. Here is an example of data returned:

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
}

Describing OpenID Connect Discovery

OpenAPI 3.0 lets you describe OpenID Connect Discovery as follows:

1
openapi: 3.0.0
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

The first section, components/securitySchemes, defines the security scheme type (openIdConnect) and the URL of the discovery endpoint (openIdConnectUrl). Unlike OAuth 2.0, you do not need to list the available scopes in securitySchemes – the clients are supposed to read them from the discovery endpoint instead. The security section then applies the chosen security scheme to your API. The actual scopes required for API calls need to be listed here. These may be a subset of the scopes returned by the discovery endpoint. If different API operations require different scopes, you can apply security on the operation level instead of globally. This way you can list the relevant scopes for each operation:

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
      ...

Relative Discovery URL

openIdConnectUrl can be specified relative to the server URL, like so:

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

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

Relative URLs are resolved according to RFC 3986. In the example above, it will be resolved to https://api.example.com/.well-known/openid-configuration.

Swagger UI support

Support for OpenID Connect Discovery was added in Swagger UI v. 3.38.0 and Swagger Editor 3.14.8.

Did not find what you were looking for? Ask the community
Found a mistake? Let us know