Request to update the bearer token help text

[neongrau]

when having

components:
  securitySchemes:
    Bearer:
      description: |
        # Token based authentication Header
        Authenticate and then copy the token into this field without the "Bearer " prefix.
      type: http
      scheme: bearer

The leading "Bearer " part is actually optional. So the fixed text saying it needs to be prefixed is a bit misleading. There are some variants that need it. Though the above example does not.

Not really much of a problem. I just noticed that a previous UI i used required omitting the prefix and openapi-explorer states it's needed, while it's not.

[wparad]

What's the context here?

[neongrau]

[wparad]

The Bearer is absolutely required by the OAuth Bearer Token RFC Specification. If your API doesn't require it then that's up to you, but technically not compliant with the OAuth Bearer tokens.

If you don't need the Bearer part, then technically this isn't OAuth, it's just an API key, and of course whatever semantics make sense there for your service should be used.

But as the text there actually matches the specification, it makes sense not to change this, unless the spec changes.

I hope that makes sense.

[neongrau]

no not really

securityDefinitions:
  APIKey:
    type: apiKey
    name: Authorization
    in: header

^ requires you to prefix with Bearer

while my example with the UI from https://swagger.io

having the prefix would result in Bearer Bearer .... as the prefix is implied when using scheme: bearer

[wparad]

I don't understand. Is the problem just the words here? Or is there a problem with the functionality of the Explorer? Or a problem expressing correctly using the openapi specification what your server can do?

It's not clear to me what we are talking about.

Yet the scheme drives the prefix, which is exactly what the text from the Explorer says:

The Authorization Header contains the word Bearer followed by the token.

That is correct, so I assume there is a problem with the functionality somewhere, right?

[neongrau]

Yeah it's just text. The scheme definition implies the Bearer prefix must not be added while the text always claims it's required.

Though actually at some place openapi-explorer does handle it. So it works, while unclear why.

[wparad]

text always claims it's required.

The text says that:

the Bearer text must be present in the Authorization header.

This is correct.

I think the misunderstanding is that you are reading that text it and maybe interpreting it as:

The `Bearer text must be present in the token in the Authorization header

Does that make sense or is the problem somewhere else?

[neongrau]

Fact is with scheme: bearer it is not only NOT required but actually mustn't be added. So the text is wrong in this case. And oddly it shouldn't work though it does.

[wparad]

If you have a bearer token, then you must send this:

Authorization: ${Bearer} ${Token}. The text above says this same thing, correct?

The scheme must be added into the Authorization header.

[neongrau]

Yes sure. Though having the need to add "Bearer " is something of a nuisance.

Though OpenAPI added "scheme: bearer" where you only have to supply the token without a prefix. This is new and simplified.

But openapi-explorer doesn't recognize this. It always demands the prefix.

This means you have to use the wrong format instead of the correct one. But only in text. As something in between fixes the problem. While other UIs would fail here.

Yeah it's a bit strange. It works, but it shouldn't!