openapi: 3.1.0 info: title: OpenID Connect API description: >- OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol. It allows clients to verify the identity of end-users based on the authentication performed by an authorization server, and to obtain basic profile information about the end-user in an interoperable and REST-like manner. This specification covers the core OIDC endpoints including discovery, token, userinfo, and JWKS. version: '1.0' contact: name: OpenID Foundation url: https://openid.net/ license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 servers: - url: https://{issuer} description: OpenID Connect Provider variables: issuer: default: example.com description: The OIDC issuer domain paths: /.well-known/openid-configuration: get: operationId: getDiscovery summary: OpenID Connect Discovery description: >- Returns the OpenID Provider Configuration Information document, which contains metadata about the OpenID Provider including its issuer, supported endpoints, scopes, response types, and other capabilities. tags: - Discovery responses: '200': description: OpenID Provider Configuration Information content: application/json: schema: $ref: '../json-schema/oidc-discovery.json' /authorize: get: operationId: authorize summary: Authorization Endpoint description: >- Performs authentication of the end-user. The authorization endpoint is used to interact with the resource owner and obtain an authorization grant. The endpoint handles the authentication flow and redirects back to the client with an authorization code or tokens depending on the response type. tags: - Authentication parameters: - name: response_type in: query required: true description: >- The value must include 'code' for the Authorization Code Flow, 'id_token' for the Implicit Flow, or 'code id_token' for the Hybrid Flow. schema: type: string enum: - code - id_token - id_token token - code id_token - code token - code id_token token - name: client_id in: query required: true description: The client identifier issued during registration. schema: type: string - name: redirect_uri in: query required: true description: >- The redirection URI to which the response will be sent. Must exactly match one of the redirection URIs registered for the client. schema: type: string format: uri - name: scope in: query required: true description: >- Space-delimited list of scopes. Must include 'openid' to indicate an OIDC request. May also include 'profile', 'email', 'address', and 'phone'. schema: type: string - name: state in: query required: false description: >- An opaque value used by the client to maintain state between the request and callback. Recommended for CSRF protection. schema: type: string - name: nonce in: query required: false description: >- A string value used to associate a client session with an ID Token and to mitigate replay attacks. Required for implicit flow. schema: type: string - name: prompt in: query required: false description: >- Space-delimited list of values that specifies whether the authorization server prompts the end-user for reauthentication and consent. schema: type: string enum: - none - login - consent - select_account - name: login_hint in: query required: false description: >- A hint to the authorization server about the login identifier the end-user might use. schema: type: string - name: acr_values in: query required: false description: >- Requested Authentication Context Class Reference values. schema: type: string - name: code_challenge in: query required: false description: >- PKCE code challenge derived from the code verifier. schema: type: string - name: code_challenge_method in: query required: false description: Code challenge method used to derive the code challenge. schema: type: string enum: - plain - S256 responses: '302': description: >- Redirect to the client redirect_uri with authorization code or tokens in the query string or fragment. '400': description: Invalid request parameters. '401': description: Authentication failed. /token: post: operationId: getToken summary: Token Endpoint description: >- Exchanges an authorization code, refresh token, or client credentials for an access token and optionally a refresh token and ID token. The token endpoint is used by the client to obtain tokens after receiving an authorization code from the authorization endpoint. tags: - Token requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - grant_type properties: grant_type: type: string description: The type of grant being presented. enum: - authorization_code - refresh_token - client_credentials code: type: string description: The authorization code received from the authorization endpoint. redirect_uri: type: string format: uri description: The redirect URI used in the authorization request. client_id: type: string description: The client identifier. client_secret: type: string description: The client secret. refresh_token: type: string description: The refresh token for obtaining a new access token. scope: type: string description: The requested scope. code_verifier: type: string description: PKCE code verifier that was used to generate the code challenge. responses: '200': description: Successful token response containing access token and optionally ID token. content: application/json: schema: type: object required: - access_token - token_type properties: access_token: type: string description: The access token issued by the authorization server. token_type: type: string description: The type of token issued, typically 'Bearer'. enum: - Bearer expires_in: type: integer description: The lifetime in seconds of the access token. refresh_token: type: string description: A refresh token that can be used to obtain new access tokens. id_token: type: string description: >- A JSON Web Token (JWT) that contains claims about the authentication event and the end-user. scope: type: string description: The scope of the access token. '400': description: Invalid request, such as an invalid grant or unauthorized client. content: application/json: schema: type: object properties: error: type: string enum: - invalid_request - invalid_client - invalid_grant - unauthorized_client - unsupported_grant_type - invalid_scope error_description: type: string /userinfo: get: operationId: getUserInfo summary: UserInfo Endpoint description: >- Returns claims about the authenticated end-user. The caller must present a valid access token obtained through OIDC authentication. The claims returned depend on the scopes granted during authorization. tags: - UserInfo security: - bearerAuth: [] responses: '200': description: Claims about the authenticated end-user. content: application/json: schema: $ref: '../json-schema/oidc-userinfo-response.json' '401': description: Missing or invalid access token. '403': description: Insufficient scope for the requested claims. post: operationId: postUserInfo summary: UserInfo Endpoint (POST) description: >- Returns claims about the authenticated end-user using a POST request. Functionally identical to the GET variant. tags: - UserInfo security: - bearerAuth: [] responses: '200': description: Claims about the authenticated end-user. content: application/json: schema: $ref: '../json-schema/oidc-userinfo-response.json' '401': description: Missing or invalid access token. '403': description: Insufficient scope for the requested claims. /.well-known/jwks.json: get: operationId: getJwks summary: JSON Web Key Set Endpoint description: >- Returns the JSON Web Key Set (JWKS) containing the public keys used by the OpenID Provider to sign tokens. Clients use these keys to verify the signatures of ID tokens and other signed artifacts. tags: - JWKS responses: '200': description: JSON Web Key Set containing the provider's public keys. content: application/json: schema: type: object required: - keys properties: keys: type: array description: Array of JSON Web Key objects. items: type: object required: - kty - use - kid properties: kty: type: string description: The key type (e.g., RSA, EC). use: type: string description: The intended use of the key (sig or enc). enum: - sig - enc kid: type: string description: A unique identifier for the key. alg: type: string description: The algorithm intended for use with the key. n: type: string description: The modulus value for an RSA public key (Base64urlUInt-encoded). e: type: string description: The exponent value for an RSA public key (Base64urlUInt-encoded). x: type: string description: The x coordinate for an EC public key. 'y': type: string description: The y coordinate for an EC public key. crv: type: string description: The curve for an EC key. x5c: type: array description: X.509 certificate chain. items: type: string x5t: type: string description: X.509 certificate SHA-1 thumbprint. /end-session: get: operationId: endSession summary: End Session Endpoint description: >- Initiates the logout process. The end-user is redirected to this endpoint to log out of the OpenID Provider. Supports RP-Initiated Logout as defined in the OIDC Session Management specification. tags: - Session parameters: - name: id_token_hint in: query required: false description: The ID token previously issued to the client. schema: type: string - name: post_logout_redirect_uri in: query required: false description: The URI to redirect to after logout. schema: type: string format: uri - name: state in: query required: false description: Opaque value for maintaining state between request and callback. schema: type: string responses: '302': description: Redirect to the post-logout redirect URI or a default page. components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: OAuth 2.0 Bearer Token obtained through OIDC authentication. tags: - name: Discovery description: OpenID Connect Discovery endpoints for provider metadata. - name: Authentication description: Endpoints for authenticating end-users and obtaining authorization grants. - name: Token description: Token endpoint for exchanging authorization codes for tokens. - name: UserInfo description: Endpoint for retrieving claims about the authenticated end-user. - name: JWKS description: JSON Web Key Set endpoint for token signature verification. - name: Session description: Session management endpoints including logout.