Openapi-specification: OpenAPI 3: add support for Token authentication

[collimarco]

I have a Rails application that uses the following standard for authentication:

Authorization: Token token="ACCESS_TOKEN"

Currently this authentication method is not supported by the spec.

However the OpenAPI should support this method because is a standard and moreover it is widely used in production - see Rails' authenticate_or_request_with_http_token for example.

[epastorino]

I have the same problem. I'm using django-rest-framework with token authentication.
OpenAPI should support this method, I agree.
Meanwhile, I'm documenting my APIs using this workaround, inspired by this response from stackoverflow:

components:
  securitySchemes:
    Token:
      type: apiKey
      in: header
      name: Authorization
      description: Enter your token in the format **Token <token>**

[darrelmiller]

@collimarco @epastorino OpenAPI v3 does support any security scheme that uses the Authorization header.

components:
  securitySchemes:
    Token:
      type: http
      scheme: Token

[MikeRalphson]

@darrelmiller we link specifically to the section of RFC7235 which states:

The "Hypertext Transfer Protocol (HTTP) Authentication Scheme
Registry" defines the namespace for the authentication schemes in
challenges and credentials. It has been created and is now
maintained at http://www.iana.org/assignments/http-authschemes.

Which might imply OAS 3 only supports Basic, Bearer, Digest, HOBA, Mutual, Negotiate, OAuth, SCRAM-SHA-1, SCRAM-SHA-256, vapid - and (potentially more problematically) any schemes added to the registry in the future.

As to being "a standard", Token Access Authentication is only defined by an expired IETF draft.

[darrelmiller]

@MikeRalphson It's a tricky situation. What does support mean? Does it mean that all tools must provide a way to enter credentials for all the registered schemes? That seems like a tall order. I'd rather just state that OAS3 supports identifying any RFC7235 style auth scheme. Tools then get to pick which of the schemes they fully enable.

[MikeRalphson]

@darrelmiller yes, this came up on the TSC call 2018-03-02. I'll propose some wording clarification for v3.1.0

[epastorino]

@darrelmiller As @MikeRalphson said, OAS3 supports the schemes defined in RFC7235. Token scheme is not defined there and swagger editor doesn't recognize it. I tried to use your suggestion and I didn't get any syntax or definition errors, but if you click on "Authorize" you get "Token HTTP authentication: unsupported or missing scheme" and you can't authorize further requests.

I think it's a good call to support a standard like RFC7235, but it feels a bit odd that Token authentication
can't be used being the default authentication scheme in frameworks such as Rails an Django. I could just change the keyword "Token" for "Bearer" in the backend, but I won't do that for already productive environments.

From now on, I'll be switching to JWT anyway, so this will not be an issue to me anymore.

[darrelmiller]

@epastorino RFC7235 doesn't define any schemes, it just defines the framework for communicating auth requirements. All the auth schemes are defined in their own specs. Currently it is up to tooling to decide which schemes to support.

[epastorino]

Undestood. Thanks for the clarification, @darrelmiller !