Support describing security keys in OAS

Often times when interacting with APIs, security keys are involved. From a JWT perspective, keys are used for encrypting, signing and verifying tokens. In issue #1464, keys are used for encrypting and signing requests/responses. I would like to propose that we officially support describing security keys in OAS, starting with JSON Web Keys.

Shooting from the hip, here is a first-pass example:

# ...
components:
  keys:
    # Keys taken from Google's OIDC Discover Document (https://accounts.google.com/.well-known/openid-configuration)
    google-oauth-v3-1:
      description: "JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/0"
      type: JWK
      metadata:
        kid: 0905d6f9cd9b0f1f852e8b207e8f673abca4bf75
        e: AQAB
        kty: RSA
        alg: RS256
        n: yyeEmeK35F8P54ozfpsF79n59ZsOrcZdxQWsxrzm0qjdA5r_b-be-cQnWAw_2AoGdeWHX-Cz7uPFDMdEwzLGlpv3SELi34h8PkzjyO7xlbhsNs-ICnqUyUTA7CovKtpJ47PjiQnXcaRNCFUQbli8VlEqbVLuqFjC98igICpNYR-iiVIm0VCFtkq0p8vf1yQ493Pnx2Bm8fUx6SkeJ7wKPWQq_K4e6ZH40JWLk6c1U9W5qPKeckevdNLrdZY5lsTZ5zrRvuRBoIeZfp9bKSZGMtEja4xSCDKLrkcpb4qf6Ywx9rsZ4b8eHSLpVvUzNsj3GS7qK5flHzoccovhPVBbbQ
        use: sig
    google-oauth-v3-2:
      description: "JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/1"
      type: JWK
      metadata:
        kid: a4313e7fd1e9e2a4ded3b292d2a7f4e519574308
        e: AQAB
        kty: RSA
        alg: RS256
        n: lO3_QoRd_D8UHAjFcdg0_8GOiLyWo4Viiy8cDLNGf8T1eQlqqhPYZmvGOPhyILWZ9FInOXT9AzH5KPfeOnMEzy4TqfGLtdcAlufqALe_qusmq7SSNIVfSw5iPZjzXk3BXjzoFNZLfqsoqheGzek-sJV1Ti5JQQ2hRPSZQhba9xVn6G8Uxr5ugVhHQ25P6HL4acjhuvpSPEFn7tivEIhWZEL35CeqHelf-48WA4PLzRVvfFMS-hW6erjX7uxT9mj8uT7zGl41_zBd9lMn2CQeP3aLDeQFoFaLaX2NZctRASErz6H9MIXQngM1piKnc84hmify-ZAsPpBcxw7heFpYRw
        use: sig
# ...

As you can see, each key has three common properties:

• description: A human-readable description of the key
• type: The type of the key (One could argue that JSON Web Keys are capable of describing any key and only JSON Web Keys should be supported but for now, this value would be free-form and it would be tooling specific as to how the values are validated.)
• metadata: This is the information describing the key based on the key type (This field must be free-form to allow for future expansion)

Once we have a common way to describe security keys, you have the ability to reference them using JSON References to use. Here are two examples:

Signed Reqeusts/Responses (#1464)

# ...
keys:
  payment-signing-key:
    description: The payment signing JSON Web Key
    type: JWK
    metadata:
      kty: EC
      crv: P-256
      x: PxlJQu9Q6dOvM4LKoZUh2XIe9-pdcLkvKfBfQk11Sb0
      y: 6IDquxrbdq5ABe4-HQ78_dhM6eEBUbvDtdqK31YfRP8
# ...
  @context: https://example.com/paymentStandard/pay,
  amount: 255.00
  currency: USD
  signature:
    # Likely unnecessary as the key describes its algorithm
    alg": ES256
    jwk:
      $ref: "#/components/keys/payment-signing-key"
    val": "RSLmFihg8QmXxM .... N0lGIdSEYvMMLTL8hEaYV9kW6A"
# ...

JWT-based Security Scheme

Note: This example uses a JWT-based Security Scheme that DOES NOT exist yet and is only for example purposes. There is an ongoing discussion about supporting JWT for security in OAS but this is not indicative of what will be supported if/when a decision is made.

# ...
components:
  keys:
    # Keys taken from Google's OIDC Discovery Document (https://accounts.google.com/.well-known/openid-configuration)
    google-oauth-v3-1:
      description: "JSON Web Key used by Google for signing JWTs: https://www.googleapis.com/oauth2/v3/certs#/keys/0"
      type: JWK
      metadata:
        kid: 0905d6f9cd9b0f1f852e8b207e8f673abca4bf75
        e: AQAB
        kty: RSA
        alg: RS256
        n: yyeEmeK35F8P54ozfpsF79n59ZsOrcZdxQWsxrzm0qjdA5r_b-be-cQnWAw_2AoGdeWHX-Cz7uPFDMdEwzLGlpv3SELi34h8PkzjyO7xlbhsNs-ICnqUyUTA7CovKtpJ47PjiQnXcaRNCFUQbli8VlEqbVLuqFjC98igICpNYR-iiVIm0VCFtkq0p8vf1yQ493Pnx2Bm8fUx6SkeJ7wKPWQq_K4e6ZH40JWLk6c1U9W5qPKeckevdNLrdZY5lsTZ5zrRvuRBoIeZfp9bKSZGMtEja4xSCDKLrkcpb4qf6Ywx9rsZ4b8eHSLpVvUzNsj3GS7qK5flHzoccovhPVBbbQ
        use: sig
# ...
security:
  google-oath:
    type: http
    scheme: bearer
    bearerFormat: JWT
    jwk:
      $ref: '#/components/keys/google-oauth-v3-1'
# ...

Now that we have some examples, let’s get the conversation started.

[fosrias]

@whitlockjc I think you need to expand your example to include the following (oneOf jwk or jwks_uri):

security:
  jwks-oath:
    type: http
    scheme: bearer
    bearerFormat: JWT
    jwks_uri: https://example.com/.well-known/jwks.json

This then works with Oauth2 providers that use JWTs and enables using JWKs with remote look up for key rotation.

[whitlockjc]

I realize that we want to make this forward thinking and not lock ourselves into one implementation but JSON Web Keys (JWK) allow for describing all key types I interact with. So my question is can’t we treat JWK as the description format for security keys and go from there?