Template paths in tokenUrl parameter of security definition

[deefactorial]

I'm running into an issue with the spec.

https://github.com/swagger-api/validator-badge/issues/73

It seems that template paths are not allowed in the tokenUrl parameter of security definitions.

my use case is:

securityDefinitions:
  oauth2PasswordSecurity:
    type: oauth2
    flow: password
    tokenUrl: 'https://example.com/V2/user/{user_id}/oauth/token'

I'm not sure if it's a bug in the 2.0 spec or a feature for next version. What would be the best way to deterministically describe template paths to clients ?

[deefactorial]

tokenUrl is type string and format uri why does format uri not support RFC 6570 URI Template ?

[whitlockjc]

URI Template strings themselves are not valid URIs (strictly). Some of the characters used in URI Templates are special characters in the URI specification and require being escaped. The reason the paths keys are allowed to use { and } without issue is because it does not use the uri format: https://github.com/OAI/OpenAPI-Specification/blob/master/schemas/v2.0/schema.json#L173

There are a number of other places in the issue tracker where tokenization of the Swagger specification is being requested so don't take my explaining "why" as us not being willing to support it.

[webron]

@deefactorial - the real question here is - do you just want to describe it as a templated path? If so, you can easily do so by escaping the URL according to the regular URI escaping rules.

If you expect an added functionality, such that the user should be able to specify the value for the templated path, then it would be a feature request for the next version. I've never really seen before the example where an OAuth2 token URL is personalized to the user - normally there's one end point for such requests. If you could provide more details as to why you chose to implement it this way (as it seems uncommon), it would help us in assessing it for the future. Of course, it could be a very common practice which I'm not aware of, and in that case I'd ask to see some references to usage out there or references to public documentation suggesting this form of implementation.

[deefactorial]

I understand that this is uncommon way of describing this particular end point. Since working with swagger to define my API I have re-factored the way I describe my end points. I find the easiest way to explain my model is to push primary key data into the path. the 'user_id' in my example is just one of those primary key data elements that needs to be known prior to posting to the API end point. without that information you can't post to the end point. It's more of a convention I use for my API.

I think the best way for me to write this in my API is to escape the template path and provide a vendor extension pointer to the operation id of the oauth end point in my API.

Something like this:

securityDefinitions:
  oauth2PasswordSecurity:
    type: oauth2
    flow: password
    tokenUrl: 'https://example.com/V2/user/%7Buser_id%7D/oauth/token'
    x-token-operation-id: oauth2tokenPost

With this I have a valid swagger definition, and if clients want more information on how to use the end point they can reference the operation id.

[webron]

Right, though that takes away from the ability to automate the process easily. Still doable, but just not as easy. However, there are so many design options out there...

I'm not sure if it would make sense to support it in the next version, but I'll mark it up for discussion.

[fehguy]

Parent issue #585

[darrelmiller]

I think doing password flow to obtain tokens this way is fairly unusual. Considering the additional complexity introduced by templating URLs, I don't think we can address this in 3.0.

[deus-x-machina]

Btw, templates do not work in server part of relative tokenUrl either.

For example

servers:
  - url: https://{customer}.example.com
    variables:
      customer:
        default: demo

...

securitySchemes:
    Oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /token
          scopes: {}

resolves to token url 'https://%7Bcustomer%7D.example.com/token'.

[MikeRalphson]

@deus-x-machina that sounds like an issue with the specific tool you're using - not the spec.

[hellmelt]

We have a system with a perimeter server, which passes requests to a farm of back-end servers. Each back-end server belongs to a specific tenant, and in the API we add the tenant name to the URLs in order to know which back-end to send the request to. In this scenario, we would like to also pass the authentication request on to the correct back-end system. I.e., the URL would look like

tokenUrl: https://www.frontend.com/{tenant}/token

So in this scenario I don't find it odd to have a parameter in the tokenUrl. I really hope this feature will be added.

[dkirrane]

This is a requirement for me for Keycloak multi-tenancy using realms. But also the keycloak server is different than the application server (we are using Kubernetes ingress host based routing).

So, I need similar functionality to the OpenAPI servers section. For example, I need to parameterize the tokenURL like this:

  securitySchemes:

    keycloak:
      type: oauth2
      description: This API uses OAuth 2
      flows:
        clientCredentials:
          tokenUrl: {protocol}://{server}:{port}/auth/realms/{realm}/protocol/openid-connect/token
          variables:
            protocol:
              enum:
                - 'http'
                - 'https'
              default: 'http'
            server:
              default: 'keycloak.company.com'
            port:
              enum:
                - '80'
                - '443'
              default: '80'
            realm:
              default: 'myTenant'              
          scopes: {}

[rupamkhaitan]

Btw, templates do not work in server part of relative tokenUrl either.

For example

servers:
  - url: https://{customer}.example.com
  variables:
    customer:
      default: demo

...

securitySchemes:
  Oauth2:
    type: oauth2
    flows:
      clientCredentials:
        tokenUrl: /token
        scopes: {}

resolves to token url 'https://%7Bcustomer%7D.example.com/token'.

Is there any way to read the template varaible in the client auth pop up window? With the swagger-ui-dist NPM module this is not reading the variable defined in the servers url and its creating trouble for us too

[hkosova]

@rupamkhaitan Swagger UI issue that you mentioned is tracked here: https://github.com/swagger-api/swagger-ui/issues/4740

[yesmarket]

I posted this question on SO a while back -

Good to see other people are thinking about something similar.

One thing to keep in mind regarding the server templating; if you're using an external IDP (e.g. Auth0, Okta, etc), the IDP base URL would not be the same as the service/endpoint base URLs... this has implications for using the existing servers element, which is already used for templating of the service/endpoint base URLs...

[cachescrubber]

We have a dedicated Keycloak instance for our prod, stage and test Environment. The Server section does support this nicely using ServerVariables. So +1 for this enhancement from my side.

[gkgeorgiev]

We have a dedicated Keycloak instance for out prod, stage and test Environment. The Server section does support this nicely using ServerVariables. So +1 for this enhancement from my side.

Exact same case for my team as well! A vote from me as well.

[MikeRalphson]

Exact same case for my team as well! A vote from me as well.

Please use the GitHub reactions functionality on the original post. We can track that, whereas positive comments we can't.

[halungge]

What is the state on this one? I think the templateing functionality really is need for multitenancy application and support of different environments both mentioned above.

[lucasvdh]

Still waiting on this feature. Would be greatly appreciated!

My swagger-ui page can only be used to view my api documentation at the moment and it can't be used to interact with the api if someone has credentials.

[thofil73]

I would also appreciate this feature, because I cannot use swagger-ui to interact with my different environments, which are DEV/STAGING/PROD:

servers:

• url: https://server.com/dev
• url: https://server.com/staging
• url: https://server.com/

tokenUrl: /o/token/

IMHO, the token endpoint should not be absolute, but relative to the selected server URL (analogous to the API endpoints), i.e. in my case: https://server.com/dev/o/token https://server.com/staging/o/token https://server.com/o/token

...just because authentication/authorization can be different in each environment.

[iristich]

I would also appreciate this feature, because I cannot use swagger-ui to interact with my different environments, which are DEV/STAGING/PROD:

servers:

• url: https://server.com/dev
• url: https://server.com/staging
• url: https://server.com/

tokenUrl: /o/token/

IMHO, the token endpoint should not be absolute, but relative to the selected server URL (analogous to the API endpoints), i.e. in my case: https://server.com/dev/o/token https://server.com/staging/o/token https://server.com/o/token

...just because authentication/authorization can be different in each environment.

Exact same issue in here.

[anderson-marques]

Same issue here. Multiples servers (per environment) that communicate with different authorization servers (also per environment). I would like to have something like this:

securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "https://{env}.authorization-server.bla/oauth2/token"
             variables:
                 env:
                    enum:
                        - 'dev'
                        - 'prod'
          scopes:
            my-things-api.read: read-only (get)
            my-things-api.write: write-only (put, post, patch)
            my-things-api.all: read-write (get, post, put, patch, and delete)
      description: This API uses OAuth 2 with the client clientCredentials grant flow.

The only alternative I found was to declare multiple security schemes with the same flow. What would be impossible if it was the case of a tenant.

[PierreFritsch]

To formalize the implicit requirement appearing in @dkirrane's and @anderson-marques's comments:

For parameterizing the tokenUrl et al. in the OAuth Flow object, it would feel most natural to me to have a variables object there, which would be working like the Server Variable Object used to define the variables of the url in the Server object.

[dchicchon]

Has this issue been resolved yet? I also am having the issue of being unable to use variables in my tokenUrl

[AlejandroPOcz]

Same here! 😄 I'm trying to specify different environments in the TokenURL section.

[srgg]

is there any ETA for that?

[FH-Inway]

Would also like to see this option in the specification.

[saleynik]

+1

[jgongo]

+1

[jgongo]

IMHO, the token endpoint should not be absolute, but relative to the selected server URL (analogous to the API endpoints)

This only makes sense when you are implementing yourself both the resource server and the authorisation server and they sit under the same domain. If you are putting them in different domains, or simply using a third-party authorisation server (like Auth0), the authorisation and token endpoints won't be relative to the server URLs.

[handrews]

I am fairly certain that if this is to be addressed, it will be done in OAS 4 Moonwalk under the separation of concerns principle, specifically separating API descriptions and deployments. This is a major redesign of what's currently handled with the Servers Object and various bits related to security.

Since it seems pretty unlikely that such a complex change would make it into a 3.x, I'm going to mark this as "moved to Moonwalk" and encourage joining the discussion over there.