security; add new securityScheme type of mutualTLS #1764

MikeRalphson · 2018-11-28T13:57:51Z

I'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:

denial of the request
prompt of a user or requiring of a special option
configuring client TLS libraries

But hey, we can always add it later.

cmheazel · 2018-11-28T23:13:08Z

@MikeRalphson That was next on my list. Thanks for beating me to the punch.

darrelmiller · 2018-12-06T14:25:37Z

versions/3.1.0.md

@@ -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.


I'm all for this proposal in general. I would like to discuss this last item a bit in today's call.

@darrelmiller @MikeRalphson

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

ioggstream · 2018-12-17T18:20:53Z

What did you agree for the other bits, eg. #1004 (comment)?

About the self-signed:

having mutualTLS is more important that deciding all the bits, so I support this PR.
we can move it to another issue, as this is a most debeated one: I strongly agree with @simo5 comments, especially
- Trusted or Untrusted. There's no Self-Signed.

ioggstream

Agree on adding mutualTLS

ioggstream · 2018-12-17T18:24:59Z

versions/3.1.0.md

@@ -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).


ioggstream · 2018-12-17T18:25:07Z

versions/3.1.0.md


 ##### 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"`.


MikeRalphson · 2019-02-06T09:57:33Z

PR pared back to just adding mutualTLS as a new securityScheme type (omitting the widening of security scopes to non-oAuth types), as discussed.

ioggstream

LGTM as discussed in the last TSC :)

whitlockjc

LGTM

earth2marsh · 2019-02-07T17:21:28Z

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.

webron · 2019-02-07T17:24:55Z

Looks like we have the votes on the call from the @OAI/tsc, merging!

earth2marsh

approved per today's TSC call

MikeRalphson mentioned this pull request Dec 4, 2018

API Key authentication should allow scopes to be defined. #1366

Closed

darrelmiller reviewed Dec 6, 2018

View reviewed changes

ioggstream approved these changes Dec 17, 2018

View reviewed changes

This was referenced Jan 7, 2019

TSC Open Meeting, January 10th 2019 #1799

Closed

TSC Open Meeting, January 17th 2019 #1804

Closed

ioggstream mentioned this pull request Jan 24, 2019

TSC Open Meeting - January 24th, 2019 #1803

Closed

MikeRalphson mentioned this pull request Jan 24, 2019

TSC Open Meeting, January 31st 2019 #1814

Closed

security; add mutualTLS securityScheme type

d27bb1c

MikeRalphson force-pushed the v3.1-mutualTLS branch from f6ab922 to d27bb1c Compare February 6, 2019 09:51

MikeRalphson changed the title ~~security; mutualTLS and non-oauth2 scopes~~ security; add new securityScheme type of mutualTLS Feb 6, 2019

MikeRalphson mentioned this pull request Feb 6, 2019

security; widen use of scopes array to other securityScheme types #1829

Merged

ioggstream approved these changes Feb 6, 2019

View reviewed changes

whitlockjc approved these changes Feb 7, 2019

View reviewed changes

webron merged commit a76dad5 into OAI:v3.1.0-dev Feb 7, 2019

ioggstream mentioned this pull request Feb 11, 2019

[OpenAPI.Next Proposal] Add client certificate to authentication methods #1004

Closed

earth2marsh self-assigned this Mar 19, 2020

earth2marsh self-requested a review March 19, 2020 16:23

earth2marsh reviewed Mar 19, 2020

View reviewed changes

lynshi mentioned this pull request Dec 17, 2020

Pluggable Auth policy follow up items microsoft/CCF#2032

Closed

4 tasks

pdconant mentioned this pull request May 17, 2023

spectral:oas ruleset doesn't recognize mutualTLS option for security scheme stoplightio/spectral#2476

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

security; add new securityScheme type of mutualTLS #1764

security; add new securityScheme type of mutualTLS #1764

MikeRalphson commented Nov 28, 2018 •

edited

Loading

cmheazel commented Nov 28, 2018

darrelmiller Dec 6, 2018

ioggstream Jan 18, 2019

ioggstream commented Dec 17, 2018 •

edited

Loading

ioggstream left a comment •

edited

Loading

ioggstream Dec 17, 2018

ioggstream Dec 17, 2018

MikeRalphson commented Feb 6, 2019

ioggstream left a comment

whitlockjc left a comment

earth2marsh commented Feb 7, 2019 •

edited

Loading

webron commented Feb 7, 2019

earth2marsh left a comment

security; add new securityScheme type of mutualTLS #1764

security; add new securityScheme type of mutualTLS #1764

Conversation

MikeRalphson commented Nov 28, 2018 • edited Loading

cmheazel commented Nov 28, 2018

darrelmiller Dec 6, 2018

Choose a reason for hiding this comment

ioggstream Jan 18, 2019

Choose a reason for hiding this comment

ioggstream commented Dec 17, 2018 • edited Loading

ioggstream left a comment • edited Loading

Choose a reason for hiding this comment

ioggstream Dec 17, 2018

Choose a reason for hiding this comment

ioggstream Dec 17, 2018

Choose a reason for hiding this comment

MikeRalphson commented Feb 6, 2019

ioggstream left a comment

Choose a reason for hiding this comment

whitlockjc left a comment

Choose a reason for hiding this comment

earth2marsh commented Feb 7, 2019 • edited Loading

webron commented Feb 7, 2019

earth2marsh left a comment

Choose a reason for hiding this comment

MikeRalphson commented Nov 28, 2018 •

edited

Loading

ioggstream commented Dec 17, 2018 •

edited

Loading

ioggstream left a comment •

edited

Loading

earth2marsh commented Feb 7, 2019 •

edited

Loading