-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As we're adding support for custom
securitySchemes #1812
I suggest to:
- strip off this line from the PR
- discuss only the
mutualTLS
during TSC Open Meeting - January 24th, 2019 #1803 (I'll attend ;)) - make a comprehensive discussion on "other security scheme types" which imho may be a broad definition in Custom Security Schemes #1812
What did you agree for the other bits, eg. #1004 (comment)? About the
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree on adding mutualTLS
@@ -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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1
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"`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1
f6ab922
to
d27bb1c
Compare
PR pared back to just adding |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM as discussed in the last TSC :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
LGTM
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! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
approved per today's TSC call
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.