Initial proposal for New Security Schemes #2582

whitlockjc · 2021-05-19T22:07:36Z

This purpose of this proposal is to rethink how Security Schemes are defined in OpenAPI. This proposal would separate the credential location(s) from the Security Scheme type and would allow for complete control over dictating where the credential(s) are provided for a Security Scheme. This proposal will add a generic way to retrieve a credential from anywhere in a request, and allow any Security Scheme to dictate where its supported credential(s) are instead of relying on OpenAPI-supported conventions/opinions. This proposal also separates the credential location(s) details from the other configurations associated with the Security Scheme (like JWKS details for JWT).

proposals/005_New_Security_Definitions.md

MikeRalphson

Basically I feel this proposal is attempting to do several things (and gets caught up trying to be backwards compatible as well):

allow (some) credentials in body and path
allow JWTs with some type-specific config
genericise credential locations and config

It's not clear to me why all these things are or need to be combined.

MikeRalphson · 2021-05-24T07:47:23Z

proposals/005_New_Security_Definitions.md

+
+[Security Schemes](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object)
+_(formerly known as "Security Definitions")_ provide a way to describe the security scheme(s) used by your API.
+Unfortunately, the _types_ supported by OpenAPI are not only limited but they often tie the credential location to the


Unfortunately, the types supported by OpenAPI ... often tie the credential location to the Security Scheme type

Can you expand on why this is "unfortunate"? Type apiKey can already be located in any of query, header,cookie, and arguably if you try to put your Bearer token anywhere other than in an Authorization header, you are not doing oAuth2.

The point was more about separating the credential location(s) from the Security Scheme type. API Key is the closest to allowing free-form credential locations while others do not. I can see where some Security Schemes where these are locked down, like OAuth 2.0 (while it uses Bearer Tokens, I don't think it supports them being in all locations a Bearer Token could be represented), but this separation is really a flexibility thing than just trying to support JWT.

It would also be nice to have a way to describe a type not supported by OAS, where our locked-down types don't fit and a customer wants to still describe their security needs.

MikeRalphson · 2021-05-24T07:48:40Z

proposals/005_New_Security_Definitions.md

+* `type: http`: This will only work if your JWT is in a header and in a supported
+  [HTTP Auth](https://datatracker.ietf.org/doc/html/rfc7235#section-5.1) format
+
+OpenAPI being so opinionated about these kinds things does not serve any real benefit to anyone involved, and this


OpenAPI being so opinionated about these kinds things does not serve any real benefit to anyone involved

Unsure this is totally true. Tooling authors may appreciate the limited set of possibilities they have to support?

It's subjective for sure but is focusing on the tooling authors more important than the consumers of OpenAPI? I think with a clean implementation, it shouldn't be too hard to support something like this as a fellow tooling author to another.

MikeRalphson · 2021-05-24T07:49:26Z

proposals/005_New_Security_Definitions.md

+The bulk of this proposal is defining a way to separate the properties used to describe the credential(s) for a Security
+Scheme from the root properties of the Security Scheme.  This proposal will also allow you to define multiple
+credentials _(multiple locations, formats, ...)_ for the same Security Scheme for cases where you might support
+multiple formats/locations for effectively the same credential.  The new objects being suggested as part of this


These multiple locations, are they AND or OR?

I would suggest we do something like how the Security Requirements work now, which would allow for an AND or an OR. But in the case of having an AND of the same credential location, I can't think of a case where you'd say I want the same to credential to be supplied in multiple places at the same time.

MikeRalphson · 2021-05-24T07:54:02Z

proposals/005_New_Security_Definitions.md

+| Field Name | Type | Applies To | Description |
+| ---------- | ---- | ---------- | ----------- |
+| in | `string` | Any | **REQUIRED.** Specifies where in the request the credential is provided.  Valid values are: `body`, `cookie`, `header`, `path` and `query` |
+| format | `regex` | Any | Specifies the format of the credential.  Since in many cases, the credential is a subset of the raw value, `format` must be a regular expression that matches the complete value, and contains a single capturing group to match the actual value within the raw value. |


Rather than express how to retrieve the credential using a regex, it may be more OAS-like to provide a template for how the credential should be constructed. Thus

format: ^[B|b][E|e][A|a][R|r][E|e][R|r] (.*)$

would become something like:

format: Bearer {credential}

PS: Header names are case-insensitive, but the "Bearer" string is not, so this regex can be simplified.

I don't disagree. The main reason for using a regex example was to show how one might pick out a portion of a larger HTTP value, I'm not married to any specific implementation.

proposals/005_New_Security_Definitions.md

MikeRalphson · 2021-06-17T09:38:18Z

As a result of #2604 the filename for this proposal should change to use a dated prefix. Please could you update this PR to match? Apologies for the extra work.

whitlockjc · 2021-09-24T15:53:36Z

A few notes after presenting this to the Security SIG:

I could see a case where the Credential Object might also allow for a credential property in place of a credentials property.
I could see a case where OAS might have some pre-defined credential (or credential formats, like HTTP Auth)
There may be a case where we might need to allow for more JWT claims described for the jwt Security Scheme (I know on the backend this could be useful but seeing as this isn't the intent, I am not sure there is a case for this but it came up in the meeting so we'll wait for examples.)

I am migrating this PR from the spec repo to allow it to be iterated upon within the security SIG. [Original PR](OAI/OpenAPI-Specification#2582)

kinlane · 2021-10-08T17:30:27Z

I have republished @whitlockjc proposal within the security SIG, and copied the conversation thread from here over to an issue. We are going to work on the proposal over there in the security SIG repo, and when ready republish here as a formal proposal.

ioggstream

Added some preliminary notes.

ioggstream · 2022-02-01T14:27:53Z

proposals/2021-05-19-New-Security-Definitions.md

+      credentials:
+      - in: header
+        name: authorization
+        format: ^[B|b][E|e][A|a][R|r][E|e][R|r] (.*)$


if it's a regexp, I'd use pattern.

whitlockjc · 2022-09-21T18:32:17Z

I've dropped the ball on this, but since it's never been reasoned about, what should we do here?

handrews · 2024-01-29T23:59:39Z

Filed #3257 to revive and clarify our proposals process. Once we figure it out, we'll resolve this PR accordingly.

darrelmiller · 2024-02-22T17:36:06Z

Closing because the conversation is now happening in Moonwalk discussions OAI/sig-moonwalk#46

whitlockjc added the draft:proposal label May 19, 2021

whitlockjc force-pushed the proposal-new-security branch 2 times, most recently from c450fa2 to 0631cb9 Compare May 19, 2021 22:16

savage-alex reviewed May 20, 2021

View reviewed changes

proposals/005_New_Security_Definitions.md Outdated Show resolved Hide resolved

savage-alex reviewed May 20, 2021

View reviewed changes

proposals/005_New_Security_Definitions.md Outdated Show resolved Hide resolved

MikeRalphson suggested changes May 24, 2021

View reviewed changes

This comment was marked as abuse.

Sign in to view

whitlockjc force-pushed the proposal-new-security branch 3 times, most recently from 2671aff to 6d9ba00 Compare July 28, 2021 15:41

Initial proposal for New Security Schemes

0b586c8

whitlockjc force-pushed the proposal-new-security branch from 6d9ba00 to 0b586c8 Compare July 28, 2021 15:42

MikeRalphson added the security label Jul 30, 2021

kinlane added a commit to OAI/sig-security that referenced this pull request Oct 8, 2021

Migrating from Spec Repo

042528b

I am migrating this PR from the spec repo to allow it to be iterated upon within the security SIG. [Original PR](OAI/OpenAPI-Specification#2582)

kinlane mentioned this pull request Oct 8, 2021

Migrating from Spec Repo OAI/sig-security#2

Merged

ioggstream reviewed Feb 1, 2022

View reviewed changes

This was referenced May 10, 2022

Support for RAR OAI/sig-security#7

Open

Support for HTTP Signatures OAI/sig-security#8

Open

Support for GNAP OAI/sig-security#9

Open

handrews added the security: config The mechanics of severs and structure of security-related objects label Feb 1, 2024

handrews mentioned this pull request Feb 22, 2024

Open Community (TDC) Meeting, Thursday 22 February 2024 #3574

Closed

darrelmiller closed this Feb 22, 2024

handrews mentioned this pull request Feb 22, 2024

Add an initial draft for a proposal for an 'archetype' field for paths. #3369

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Initial proposal for New Security Schemes #2582

Initial proposal for New Security Schemes #2582

whitlockjc commented May 19, 2021 •

edited

Loading

MikeRalphson left a comment

MikeRalphson May 24, 2021

whitlockjc Jul 28, 2021

whitlockjc Jul 28, 2021

MikeRalphson May 24, 2021

whitlockjc Jul 28, 2021

MikeRalphson May 24, 2021

whitlockjc Jul 28, 2021

MikeRalphson May 24, 2021

whitlockjc Jul 28, 2021

This comment was marked as abuse.

This comment was marked as abuse.

MikeRalphson commented Jun 17, 2021

whitlockjc commented Sep 24, 2021

kinlane commented Oct 8, 2021 •

edited

Loading

ioggstream left a comment

ioggstream Feb 1, 2022

whitlockjc commented Sep 21, 2022

handrews commented Jan 29, 2024

darrelmiller commented Feb 22, 2024

Initial proposal for New Security Schemes #2582

Initial proposal for New Security Schemes #2582

Conversation

whitlockjc commented May 19, 2021 • edited Loading

MikeRalphson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as abuse.

This comment was marked as abuse.

MikeRalphson commented Jun 17, 2021

whitlockjc commented Sep 24, 2021

kinlane commented Oct 8, 2021 • edited Loading

ioggstream left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

whitlockjc commented Sep 21, 2022

handrews commented Jan 29, 2024

darrelmiller commented Feb 22, 2024

whitlockjc commented May 19, 2021 •

edited

Loading

kinlane commented Oct 8, 2021 •

edited

Loading