oauth2_endpoints_polymorphism.yml

openapi: '3.0.2'
info:
  title: OAuth2 Token Endpoint Components with Polymorphism(oneOf property)
  version: '1.0'
  description: |-
    [OpenAPI Spec 3.0 - Composition and Inheritance (Polymorphism)](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#schemaComposition)

    **Please, make sure that your tools supports polymorphism. This example contains new features not highly adopted yet. Check at least `oneOf` property support. I wouldn't use it myself because most of the OpenAPI tools have issues with polymorphism now, but this example may be useful in forseeable future.**

    This document omits authorization endpoint on purpose. I don't know how to describe it with OAS3 since endpoint response isn't JSON(html page). If you have any suggestion please submit an issue to this repo.

    Quote from [RFC 6749 - The OAuth2.0 Authorization Framework - 2.3.1. Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1):

    > Including the client credentials in the request-body using the two parameters is **NOT RECOMMENDED** and **SHOULD** be limited to clients unable to directly utilize the HTTP Basic authentication scheme (or other password-based HTTP authentication schemes).
    > The parameters can only be transmitted in the request-body and **MUST NOT** be included in the request URI.
servers:
  - url: https://server.example.com/
paths:
  /token:
    post:
      tags:
        - OAuth2
      summary: Obtain access token.
      externalDocs:
        description: RFC 6749 - The OAuth2.0 Authorization Framework
        url: https://tools.ietf.org/html/rfc6749#section-4.1.3
      operationId: obtainAccessTokenViaCodeGrant
      requestBody:
        $ref: '#/components/requestBodies/TokenRequestBody'
      responses:
        '200':
          $ref: '#/components/responses/OAuth2TokenSuccessResponse'
        '4XX':
          $ref: '#/components/responses/OAuth2TokenErrorResponse'
      security:
        - ClientPasswordHttpBasic: []
components:
  schemas:
    Token:
      title: Token
      description: |-
        Access Token

        [The OAuth2.0 Authorization Framework - 1.4. Access Token](https://tools.ietf.org/html/rfc6749#section-1.4)

        Access tokens are credentials used to access protected resources.  An access token is a string representing an authorization issued to the client.  The string is usually opaque to the client.  Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server.
      type: object
      required:
        - access_token
        - token_type
      properties:
        access_token:
          description: |-
            The access token issued by the authorization server.
          type: string
          example: 2YotnFZFEjr1zCsicMWpAA
        token_type:
          description: |-
            The type of the token issued as described in [Section 7.1](https://tools.ietf.org/html/rfc6749#section-7.1).  Value is case insensitive.
          type: string
          example: Bearer
        expires_in:
          description: |-
            **RECOMMENDED**. The lifetime in seconds of the access token.  For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated. If omitted, the authorization server SHOULD provide the expiration time via other means or document the default value.
          type: integer
          example: 3600
        refresh_token:
          description: |-
            The refresh token, which can be used to obtain new access tokens using the same authorization grant as described in [Section 6](https://tools.ietf.org/html/rfc6749#section-6).
          type: string
          example: tGzv3JOkF0XG5Qx2TlKWIA
        scope:
          description: |-
            **OPTIONAL**, if identical to the scope requested by the client; otherwise, **REQUIRED**.  The scope of the access token as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).
          type: string
          example: 'read write'
    TokenError:
      title: TokenError
      description: |-
        [The OAuth2.0 Authorization Framework - 5.2. Error Response](https://tools.ietf.org/html/rfc6749#section-5.2)
      type: object
      required:
        - error
      properties:
        error:
          description: |-
            A single ASCII [[USASCII](https://tools.ietf.org/html/rfc6749#ref-USASCII)] error code from the following:
            | Error Code| Description |
            |-----------|-------------|
            | invalid_request | The request is missing a required parameter, includes an unsupported parameter value (other than grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed. |
            | invalid_client | Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).  The authorization server MAY return an HTTP 401 (Unauthorized) status code to indicate which HTTP authentication schemes are supported.  If the client attempted to authenticate via the "Authorization" request header field, the authorization server MUST respond with an HTTP 401 (Unauthorized) status code and include the "WWW-Authenticate" response header field matching the authentication scheme used by the client. |
            | invalid_grant | The provided authorization grant (e.g., authorization code, resource owner credentials) or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client. |
            | unauthorized_client | The authenticated client is not authorized to use this authorization grant type. |
            | unsupported_grant_type | The authorization grant type is not supported by the authorization server. |
            | invalid_scope | The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner. |
          type: string
          enum:
            - invalid_request
            - invalid_client
            - invalid_grant
            - unauthorized_client
            - unsupported_grant_type
            - invalid_scope
          example: invalid_client
        error_description:
          description: |-
            Human-readable ASCII [[USASCII](https://tools.ietf.org/html/rfc6749#ref-USASCII)] text providing additional information, used to assist the client developer in understanding the error that occurred.
          type: string
          example: Client authentication failed
        error_uri:
          description: |-
            A URI identifying a human-readable web page with information about the error, used to provide the client developer with additional information about the error.
          type: string
          example: 'http://example.test/client_authentication_failed.html'
    ClientCredentialsGrant:
      type: object
      required:
        - grant_type
      properties:
        grant_type:
          description: |-
            Value **MUST** be set to "client_credentials".
          type: string
          example: client_credentials
        scope:
          description: |-
            The scope of the access request as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).
          type: string
          example: read write
    CodeGrant:
      type: object
      required:
        - grant_type
        - code
      properties:
        grant_type:
          description: |-
            Value **MUST** be set to "authorization_code".
          type: string
          example: authorization_code
        code:
          description: |-
            The authorization code received from the authorization server.
          type: string
          example: SplxlOBeZQQYbYS6WxSbIA
        redirect_uri:
          description: |-
            **REQUIRED**, if the "redirect_uri" parameter was included in the authorization request as described in Section [4.1.1](https://tools.ietf.org/html/rfc6749#section-4.1.1), and their values **MUST** be identical.
          type: string
          example: 'https://client.example.com/cb'
        client_id:
          description: |-
            **REQUIRED**, if the client is not authenticating with the authorization server as described in Section [3.2.1](https://tools.ietf.org/html/rfc6749#section-3.2.1).
          type: string
          example: s6BhdRkqt3
    PasswordGrant:
      type: object
      required:
        - grant_type
        - username
        - password
      properties:
        grant_type:
          description: |-
            Value **MUST** be set to "password".
          type: string
          example: password
        username:
          description: |-
            The resource owner username.
          type: string
          example: johndoe
        password:
          description: |-
            The resource owner password.
          type: string
          example: A3ddj3w
        scope:
          description: |-
            The scope of the access request as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).
          type: string
          example: read write
    RefreshGrant:
      type: object
      required:
        - grant_type
        - refresh_token
      properties:
        grant_type:
          description: |-
            Value **MUST** be set to "refresh_token".
          type: string
          example: refresh_token
        refresh_token:
          description: |-
            The refresh token issued to the client.
          type: string
          example: tGzv3JOkF0XG5Qx2TlKWIA
        scope:
          description: |-
            The scope of the access request as described by [Section 3.3](https://tools.ietf.org/html/rfc6749#section-3.3).  The requested scope **MUST NOT** include any scope not originally granted by the resource owner, and if omitted is treated as equal to the scope originally granted by the resource owner.
          type: string
          example: read write
  responses:
    OAuth2TokenSuccessResponse:
      description: |-
        Successful Response.

        [The OAuth2.0 Authorization Framework - 5.1. Successful Response](https://tools.ietf.org/html/rfc6749#section-5.1)

        The authorization server issues an access token and optional refresh token, and constructs the response by adding the following parameters to the entity-body of the HTTP response with a 200 (OK) status code.
      headers:
        Cache-Control:
          schema:
            type: string
            example: no-store
        Pragma:
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Token'
    OAuth2TokenErrorResponse:
      description: |-
        Error Response.

        [The OAuth2.0 Authorization Framework - 5.2. Error Response](https://tools.ietf.org/html/rfc6749#section-5.2)

        The authorization server responds with an HTTP 400 (Bad Request) status code (unless specified otherwise) and includes the following parameters with the response.

        Values for the "error" parameter **MUST NOT** include characters outside the set %x20-21 / %x23-5B / %x5D-7E.
      headers:
        Cache-Control:
          schema:
            type: string
            example: no-store
        Pragma:
          schema:
            type: string
            example: no-cache
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TokenError'
  requestBodies:
    TokenRequestBody:
      description: |-
        Access token request body
      content:
        application/x-www-form-urlencoded:
          schema:
            oneOf:
              - $ref: '#/components/schemas/ClientCredentialsGrant'
              - $ref: '#/components/schemas/CodeGrant'
              - $ref: '#/components/schemas/PasswordGrant'
              - $ref: '#/components/schemas/RefreshGrant'
            discriminator:
              propertyName: grant_type
              mapping:
                client_credentials: '#/components/schemas/ClientCredentialsGrant'
                authorization_code: '#/components/schemas/CodeGrant'
                password: '#/components/schemas/PasswordGrant'
                refresh_token: '#/components/schemas/RefreshGrant'
      required: true
  securitySchemes:
    ClientPasswordHttpBasic:
      description: |-
        Clients in possession of a client password MAY use the HTTP Basic authentication scheme as defined in [[RFC2617](https://tools.ietf.org/html/rfc2617)] to authenticate with the authorization server.

        Use "client_id" as username and "client_secret" as password.

        [RFC 6749 - 2.3.1. Client Password](https://tools.ietf.org/html/rfc6749#section-2.3.1)
      type: http
      scheme: Basic