[Feature Request] - Allow payload definition for JWT schema

[ugurcemozturk]

Is your feature request related to a problem?

Yes. The clients will be able to know what they expect within the payload of the JWT. It will save time to parse the payload on the client-side.

Describe the solution you'd like

In the security schemas sections, the developer should be able to provide the JWT payload as another sub-schema.
Something like:

 securitySchemes:
    AppJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
            payload: '#/components/schemas/AppJwtPayload'
  schemas:
    AppJwtPayload:  
      type: object
      properties:
        userId:
          type: string

Thanks.

[ioggstream]

I'm unsure if

bearerFormat: JWT
  payload: bar

is valid yaml.

[ugurcemozturk]

Do you mean not a valid yml or openApi spec?

[ioggstream]

it's not valid yaml.

python -c '
import yaml;
yaml.load("""
a: 1
 b: 2
""")
'

yaml.scanner.ScannerError: mapping values are not allowed here
  in "<string>", line 3, column 3:
     b: 2

[DavidePastore]

I'd like to see this kind of feature available. Maybe the schema could be something like this:

securitySchemes:
  AppJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      properties:
            header: '#/components/schemas/AppJwtHeader'
            payload: '#/components/schemas/AppJwtPayload'
  schemas:
    AppJwtPayload:  
      type: object
      properties:
        userId:
          type: string
    AppJwtHeader:
      type: object
      properties:
        alg:
          type: string
        typ:
          type: string

Here I'm using different schemas for the header and the payload. I used the properties field name, but I think you could even find a better alternative if it doesn't fit your needs.

[ioggstream]

@DavidePastore iiuc in your proposal, properties applies to a securityScheme object, so it will be valid for all schemes.

A standard JWT json representation is described in https://tools.ietf.org/html/rfc7515#section-7.2.1 and probably that would be the correct way to define a JWT schema, eg.

  AppJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      x-jwt-schema:
        $ref: '#/component/schemas/JWTSchema'

Still I don't have a way to describe in a standard way the requirements, which can be impacted not only by the schema but on the validation specifications, eg. see https://github.com/zalando/connexion/blob/master/examples/openapi3/jwt/openapi.yaml#L45

[DavidePastore]

HI @ioggstream. Yes, you got the point. Can I help in some ways to add the JWT definition (header and payload) support?

[ioggstream]

@DavidePastore I think we should find a suitable way to extend the SecurityScheme. I spent some time trying to do it with mutualTLS but without great results :) I'd start reading some of the issues https://github.com/OAI/OpenAPI-Specification/search?q=securityschemes&type=issues and once there's a proposal we can ping the other folks.

[ioggstream]

@darrelmiller do you perceive any interest in this topic?

[jdesrosiers]

I'm not sure this solves your problem, but checkout the third example from a section of the 2020-12 JSON Schema, which is supported in OpenAPI 3.1.

[ioggstream]

Thanks @jdesrosiers! The point now is how to associate the JWT syntax to a securityScheme.

[ovdienkonikolai]

Hello, @MikeRalphson! I would like to use this feature. Can I help with the implementation in any way?