OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification.
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
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:
Describing OpenID Connect Discovery
OpenAPI 3.0 lets you describe OpenID Connect Discovery as follows:
# 1) Define the security scheme type and attributes
openId: # <--- Arbitrary name for the security scheme. Used to refer to it from elsewhere.
# 2) Apply security globally to all operations
- openId: # <--- Use the same name as specified in securitySchemes
The first section,
, defines the security scheme type (
) and the URL of the discovery endpoint (
). Unlike OAuth 2.0, you do not need to list the available scopes in
– the clients are supposed to read them from the discovery endpoint instead.
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
on the operation level instead of globally. This way you can list the relevant scopes for each operation:
summary: Get a pet by ID
summary: Delete a pet by ID
Relative Discovery URL
can be specified relative to the server URL
, like so:
- url: https://api.example.com/v2
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