security; add new securityScheme type of mutualTLS #1764
Conversation
|
@MikeRalphson That was next on my list. Thanks for beating me to the punch. |
versions/3.1.0.md
Outdated
| @@ -3340,7 +3340,7 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](# | |||
|
|
|||
| Field Pattern | Type | Description | |||
| ---|:---:|--- | |||
| <a name="securityRequirementsName"></a>{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MUST be empty. | |||
| <a name="securityRequirementsName"></a>{name} | [`string`] | Each name MUST correspond to a security scheme which is declared in the [Security Schemes](#componentsSecuritySchemes) under the [Components Object](#componentsObject). If the security scheme is of type `"oauth2"` or `"openIdConnect"`, then the value is a list of scope names required for the execution. For other security scheme types, the array MAY contain a list of role names which are required for the execution, but are not otherwise defined or exchanged in-band. | |||
There was a problem hiding this comment.
I'm all for this proposal in general. I would like to discuss this last item a bit in today's call.
There was a problem hiding this comment.
As we're adding support for custom securitySchemes #1812
I suggest to:
mutualTLS during TSC Open Meeting - January 24th, 2019 #1803 (I'll attend ;))|
What did you agree for the other bits, eg. #1004 (comment)? About the
|
| @@ -3165,12 +3165,12 @@ animals: | |||
| #### <a name="securitySchemeObject"></a>Security Scheme Object | |||
|
|
|||
| Defines a security scheme that can be used by the operations. | |||
| Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). | |||
| Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2's common flows (implicit, password, application and access code) as defined in [RFC6749](https://tools.ietf.org/html/rfc6749), and [OpenID Connect Discovery](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06). | |||
versions/3.1.0.md
Outdated
|
|
||
| ##### Fixed Fields | ||
| Field Name | Type | Applies To | Description | ||
| ---|:---:|---|--- | ||
| <a name="securitySchemeType"></a>type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`. | ||
| <a name="securitySchemeType"></a>type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`, `"mutualTLS"`. |
f6ab922 to
d27bb1c
Compare
|
PR pared back to just adding |
|
LGTM. Another benefit of signaling mTLS is that from the docs perspective you can inform about the security model. That's great. I would expect that the client on-boarding process would provide info on acquiring a cert, and I'd wonder if we should consider an externalDocs link for security schemes in a future PR? One more observation (which has no real bearing on this PR, I just find it interesting) is that most security schemes are observable in transit, such as from an API gateway. It would seem that mTLS wouldn't be observable as a requirement. |
|
Looks like we have the votes on the call from the @OAI/tsc, merging! |
Refs #1004
and #1366 & #1393I'm still personally of the opinion a property which hints that the server may present a self-signed certificate would be useful to allow any or all of the following interactions:
But hey, we can always add it later.