How to use Google ReCaptcha as "security"

[NonPolynomial]

Hi,

I have a path and have to secure it with either an API key or for browser clients with Google ReCaptcha, where the client recaptcha token is used within the request payload.

Payload

{
  "g-recaptcha-response": "recaptcha client token which has to be verified",
  // other payload data
}

OpenAPI YAML

openapi: 3.0.0

info:
  title: Test
  description: API
  version: 1.0.0

components:
  securitySchemes:
    ApiKey:
      type: apiKey
      name: X-Api-Key
      in: header

paths:
  /a/b/c:
    post:
      description: ABC
      security:
        - ApiKey: []
        - GoogleRecaptcha: [] # <--- how?!
      responses:
        "200":
          description: success
          content:
            application/json:
              example:
                status: ok

How do I define the security scheme for GoogleRecaptcha?

[ssoderberg]

I see this issue has been open for a while. Is there an accepted practice for supporting this? We have a similar need. We use authentication/authorization schemes in addition to the 4 that are currently defined in OpenAPI 3.0. They are also different than the mutualTLS type being supported in OpenAPI 3.1.

Our preference is not to co-opt one of the existing types but to be able to add another type cleanly within the OpenAPI spec for our APIs. Since the current OpenAPI schema uses well-defined properties for each security type and has a limited list of allowed types, would it be possible to augment with a type of custom and another object schema where users can add specification extensions to define the custom type(s) as needed?

This may look like

{
  "type": "custom",
  "x-customFlows": {
    "x-name": "AppCon",
    "permissions": {
      "write:pets": "modify pets in your account",
      "read:pets": "read your pets"
    }
  }
}

I would love to hear any suggestions on how we can fit a custom security type into OpenAPI 3.0 through the above augmentation or other alternatives.