search

OAI / OpenAPI-Specification

The OpenAPI Specification Repository
https://openapis.org
Apache License 2.0
28.91k stars 9.07k forks source link

The URL for token validation is missing in security definition #621

Closed slavaschmidt closed 8 months ago

slavaschmidt commented 8 years ago

Parent issue #585

[background] Play-swagger is an open-source project aiming to implement a code generation framework for server-side part of the API with is described by swagger specification. Currently we are implementing security support and have following issue. [/background]

It is possible to define four different OAuth2 flows, each with different attributes like tokenURL and authorisationURL. In my understanding there URLs required in order to be able to generate a client code and not relevant for the resource server. The resource server is expected to validate received OAuth2 token in some way which is outside of the scope of the OAuth2 specification but usually implemented like a URL to which a token can be POSTed or GETed. In order to be able to generate the resource server code, we need a possibility to specify how the token should be validated. It seems that it is sufficient to have an additional parameter, like x-token-validation-url which can be assigned a URL which is then used by the resource server to validate the token. Our implementation is build in the way that if it recognises that the URL is a template url, it issues a GET request (this is done for backward compatibility), otherwise it issues a POST request as specified in https://tools.ietf.org/html/rfc7662

Do you think we understand the semantics of the Swagger specification correctly with our assumption that both tokenUrl and authorisationUrl are related to the client side?

Do you think it might be feasible to include the validation url for the resource side in the standard?

ePaul commented 8 years ago

I agree that both tokenUrl and authorizationUrl are meant for use by the client, not by the server.

I would say that the token validation URL (which is used just by the server, not by the client) is basically not a part of the API definition. As you describe, it is not even actually defined in the OAuth2 spec.

Instead, it is a part of the server configuration, just like a database URL or similar.

Using a vendor extension which is (potentially) used just by server generators might be a solution, but it is still exposing the URI to the client if both are using the same API definition document. I would therefore prefer not to add anything like this in the next version of the specification.

slavaschmidt commented 8 years ago

@ePaul Thanks for the quick feedback and clarification. I understand your reasoning very well and completely agree with that. We'll use vendor extension for our needs.

Do you think it is correct to say that swagger specification is biased towards client-side of the API?

handrews commented 8 months ago

The original question was answered years ago, and while the later philosophical question is interesting, I don't think we need to keep this open 8 years later to track it.

However, if anyone wants to discuss the balance of OpenAPI client vs server features, I'd suggest the Moonwalk (OAS 4) discussions as the most useful venue.