From 79470fe5a1398a0f53d79cf863087055993ccdc6 Mon Sep 17 00:00:00 2001 From: tedepstein Date: Fri, 5 Apr 2019 09:08:15 -0400 Subject: [PATCH 1/4] Referencing issue #513. Clarify the spec to accommodate OAuth schemes where scope may be unspecified (optional scope) or where scope is not used at all. --- versions/3.0.3.md | 41 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index b1abb2223a..35f261e11d 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -3286,12 +3286,14 @@ Field Name | Type | Applies To | Description authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. +scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. If scope is optional, the map MAY include an entry with an empty string as its key to represent the default scope. If scope is not used in the authorization scheme, the map MAY be empty. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### OAuth Flow Object Examples +###### OAuth Flows with Required Scope + ```JSON { "type": "oauth2", @@ -3331,6 +3333,41 @@ flows: read:pets: read your pets ``` +###### OAuth Flows with Unspecified and Optional Scope + +```JSON +{ + "type": "oauth2", + "flows": { + "implicit": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "scopes": {} + }, + "authorizationCode": { + "authorizationUrl": "https://example.com/api/oauth/dialog", + "tokenUrl": "https://example.com/api/oauth/token", + "scopes": { + "write:pets": "modify pets in your account", + "": "default scope provides read-only access" + } + } + } +} +``` + +```yaml +type: oauth2 +flows: + implicit: + authorizationUrl: https://example.com/api/oauth/dialog + scopes: {} + authorizationCode: + authorizationUrl: https://example.com/api/oauth/dialog + tokenUrl: https://example.com/api/oauth/token + scopes: + write:pets: modify pets in your account + "" : default scope provides read-only access +``` #### Security Requirement Object @@ -3346,7 +3383,7 @@ When a list of Security Requirement Objects is defined on the [OpenAPI Object](# Field Pattern | Type | Description ---|:---:|--- -{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. +{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, and the list MAY be empty if authorization does not require a specified scope. For other security scheme types, the array MUST be empty. ##### Security Requirement Object Examples From 0e189448a593baa7850118173d213c8c298393c2 Mon Sep 17 00:00:00 2001 From: tedepstein Date: Fri, 5 Apr 2019 09:45:20 -0400 Subject: [PATCH 2/4] Removed the provision for default scope represented as empty string. This introduces some ambiguities in the Security Requirement Object that would need to be addressed. --- versions/3.0.3.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 35f261e11d..1d97b15f79 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -3286,13 +3286,13 @@ Field Name | Type | Applies To | Description authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. If scope is optional, the map MAY include an entry with an empty string as its key to represent the default scope. If scope is not used in the authorization scheme, the map MAY be empty. +scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. If scope is not required or not specified in the authorization scheme, the map MAY be empty. This object MAY be extended with [Specification Extensions](#specificationExtensions). ##### OAuth Flow Object Examples -###### OAuth Flows with Required Scope +###### OAuth Flows with Defined Scopes ```JSON { @@ -3333,7 +3333,7 @@ flows: read:pets: read your pets ``` -###### OAuth Flows with Unspecified and Optional Scope +###### OAuth Flows with Optional or Unspecified Scope ```JSON { @@ -3346,10 +3346,7 @@ flows: "authorizationCode": { "authorizationUrl": "https://example.com/api/oauth/dialog", "tokenUrl": "https://example.com/api/oauth/token", - "scopes": { - "write:pets": "modify pets in your account", - "": "default scope provides read-only access" - } + "scopes": {} } } } @@ -3364,9 +3361,7 @@ flows: authorizationCode: authorizationUrl: https://example.com/api/oauth/dialog tokenUrl: https://example.com/api/oauth/token - scopes: - write:pets: modify pets in your account - "" : default scope provides read-only access + scopes: {} ``` #### Security Requirement Object From 1700e2f3b3c3ae1913ab4b9237ce71ad1bb01767 Mon Sep 17 00:00:00 2001 From: Ted Epstein Date: Wed, 12 Feb 2020 15:25:19 -0500 Subject: [PATCH 3/4] For #513, adjusting language and removing examples For #513, adjusting language and removing examples as suggested by @webron. --- versions/3.0.3.md | 33 +-------------------------------- 1 file changed, 1 insertion(+), 32 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 1d97b15f79..e385e2bdbb 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -3286,7 +3286,7 @@ Field Name | Type | Applies To | Description authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. -scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. If scope is not required or not specified in the authorization scheme, the map MAY be empty. +scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty. This object MAY be extended with [Specification Extensions](#specificationExtensions). @@ -3333,37 +3333,6 @@ flows: read:pets: read your pets ``` -###### OAuth Flows with Optional or Unspecified Scope - -```JSON -{ - "type": "oauth2", - "flows": { - "implicit": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "scopes": {} - }, - "authorizationCode": { - "authorizationUrl": "https://example.com/api/oauth/dialog", - "tokenUrl": "https://example.com/api/oauth/token", - "scopes": {} - } - } -} -``` - -```yaml -type: oauth2 -flows: - implicit: - authorizationUrl: https://example.com/api/oauth/dialog - scopes: {} - authorizationCode: - authorizationUrl: https://example.com/api/oauth/dialog - tokenUrl: https://example.com/api/oauth/token - scopes: {} -``` - #### Security Requirement Object Lists the required security schemes to execute this operation. From 6a04a1495fe768907c38330b77305ef864aa3f3b Mon Sep 17 00:00:00 2001 From: Ron Date: Wed, 12 Feb 2020 13:54:23 -0700 Subject: [PATCH 4/4] removed unnecessary example header --- versions/3.0.3.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index e385e2bdbb..7808943032 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -3292,8 +3292,6 @@ This object MAY be extended with [Specification Extensions](#specificationExtens ##### OAuth Flow Object Examples -###### OAuth Flows with Defined Scopes - ```JSON { "type": "oauth2",