Subdomain parameter in oauth2 authorizationUrl

[lucasvdh]

Q&A (please complete the following information)

• OS: Windows
• Browser: chrome
• Version: 81.0.4
• Method of installation: npm
• Swagger-UI version: latest
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Swagger/OpenAPI definition:

openapi: 3.0.0
info:
  title: My API
  version: ""
paths:
  /item:
    get:
      responses:
        200:
          $ref: '#/components/responses/PaginatedItems'
        400:
          $ref: '#/components/responses/BadRequest'
        401:
          $ref: '#/components/responses/Unauthorized'
      summary: List all resources
      description: Get a paginated list of all items.
      tags:
        - Item
      parameters:
        - $ref: '#/components/parameters/JsonHeader'
        - $ref: '#/components/parameters/PerPage'
        - $ref: '#/components/parameters/Page'
      security:
        - oauth2:
            - item:index
tags:
  - name: Item
servers:
  - url: https://{subdomain}.mydomain.com/api
    variables:
      subdomain:
        default: test
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://{subdomain}.mydomain.com/api/oauth/authorize
          tokenUrl: https://{subdomain}.mydomain.com/api/oauth/access_token
          scopes:
            'item:index': Index items
  schemas:
    Pagination:
      type: object
      properties:
        total:
          type: number
          description: Total number of objects
        count:
          type: number
          description: Object on this page
        per_page:
          type: number
          description: Object per page
        current:
          type: number
          description: Current page number
        total_pages:
          type: number
          description: Total number of pages
        links:
          type: object
          description: Array of meta links
          properties:
            self:
              type: string
              description: Link to the current page
            first:
              type: string
              description: Link to the first page
            prev:
              type: string
              description: Link to the previous page
            next:
              type: string
              description: Link to the next page
            last:
              type: string
              description: Link to the last page
    Item:
      type: object
      properties:
        id:
          type: number
          description: Id of the item
        name:
          type: string
          description: The name of the item
    Unauthorized:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
          description: The type of error
        error_description:
          type: string
          description: A detailed description of the error
      description: An authorized action
    BadRequest:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
      description: A bad request
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequest'
          examples:
            UnauthorizedScopeExample:
              $ref: '#/components/examples/BadScopeRequestExample'
            UnauthorizedExample:
              $ref: '#/components/examples/BadRequestExample'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Unauthorized'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedExample'
    PaginatedItems:
      description: A paginated collection of the item resource
      headers: {}
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Item'
              meta:
                $ref: '#/components/schemas/Pagination'
          examples:
            PaginatedAddressExample:
              $ref: '#/components/examples/PaginatedItemsExample'
  examples:
    BadRequestExample:
      summary: 400 No access token
      description: Your request is missing required oauth paramenters, check that the access_token is passed correctly
      value:
        error: invalid_request
        error_description: The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the "access token" parameter.
    BadScopeRequestExample:
      summary: 400 Invalid scope(s)
      description: Your access token doesn't have the correct scopes. You will probably need to request a new one which includes the scope(s) for this endpoint.
      value:
        success: false
        error:
          code: 400
          message: Invalid scope(s) provided
    PaginatedItemsExample:
      summary: 200 OK
      value:
        data:
          - id: 4
            name: item
        meta:
          pagination:
            total: 1
            count: 1
            per_page: 15
            current: 1
            total_pages: 1
            links: []
  parameters:
    PerPage:
      name: perPage
      in: query
      description: The maximum number of objects to return
      required: false
      example: "25"
      schema:
        type: integer
        default: 15
    Page:
      name: page
      in: query
      description: The page number
      required: false
      example: "1"
      schema:
        type: integer
        default: 1
    JsonHeader:
      name: Accept
      in: header
      description: Provide the desired response type. If this is not provided error messages might be rendered as a generic 500 html page.
      required: true
      example: application/json
      schema:
        type: string
        enum:
          - application/json

Swagger-UI configuration options:
Default editor at https://editor.swagger.io/

Screenshots

Change the subdomain variable:

Not reflected in the authorizationUrl:

How can we help?

Why isn't the changed subdomain variable reflected in the authorizationUrl?

[hkosova]

@lucasvdh

          authorizationUrl: https://{subdomain}.mydomain.com/api/oauth/authorize
          tokenUrl: https://{subdomain}.mydomain.com/api/oauth/access_token

The authorizationUrl and tokenUrl values themselves don't support {variables}, that's why those placeholders aren't replaced.

Since your OAuth authorization server is the same as the API server, what you can do is define these endpoints relative to the API server so that they will "inherit" the computed subdomain:

servers:
  - url: https://{subdomain}.mydomain.com/api
    variables:
      subdomain:
        default: test
...
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /api/oauth/authorize   # <----
          tokenUrl: /api/oauth/access_token        # <----

The effort to support this approach in Swagger UI is tracked in #3992, so I'll close this issue in favor of #3992. Please track the other issue to get notified when this functionality becomes available in Swagger UI.

[lucasvdh]

@FilippoVigani thanks for the explanation!