From 31ffe115d57a25da736b56bc198d22bb24930883 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 21 Oct 2016 20:50:16 -0400 Subject: [PATCH 01/10] Some fixes to the security definition object Corrected RFC reference. Clarified that URLs can be relative. Fixed basic auth example. --- versions/3.0.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index bbbfeb5548..3ea8f9602c 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -3004,12 +3004,11 @@ Field Name | Type | Validity | Description description | `string` | Any | A short description for security scheme. name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used. in | `string` | `apiKey` | **Required** The location of the API key. Valid values are `"query"` or `"header"`. -scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the Authorization header as per RFC 7234. -bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token should be formatted. -openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. +scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the Authorization header as per [RFC 7235](https://tools.ietf.org/html/rfc7235). +openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. Url may be relative to location of OpenAPI document. flow | `string` | `oauth2` | **Required.** The flow used by the OAuth2 security scheme. Valid values are `"implicit"`, `"password"`, `"application"` or `"accessCode"`. -authorizationUrl | `string` | `oauth2` (`"implicit"`, `"accessCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"application"`, `"accessCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. +authorizationUrl | `string` | `oauth2` (`"implicit"`, `"accessCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. +tokenUrl | `string` | `oauth2` (`"password"`, `"application"`, `"accessCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -3020,7 +3019,7 @@ This object can be extended with [Specification Extensions](#specificationExtens ```json { - "type": "scheme", + "type": "http", "scheme" : "basic" } ``` From bd4d7b190b6924ebff0528c37e7e397945b2765c Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 21 Oct 2016 20:50:56 -0400 Subject: [PATCH 02/10] Update to description of bearerFormat property --- versions/3.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/3.0.md b/versions/3.0.md index 3ea8f9602c..42089ccb06 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -3005,6 +3005,7 @@ Field Name | Type | Validity | Description name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used. in | `string` | `apiKey` | **Required** The location of the API key. Valid values are `"query"` or `"header"`. scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the Authorization header as per [RFC 7235](https://tools.ietf.org/html/rfc7235). +bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. Url may be relative to location of OpenAPI document. flow | `string` | `oauth2` | **Required.** The flow used by the OAuth2 security scheme. Valid values are `"implicit"`, `"password"`, `"application"` or `"accessCode"`. authorizationUrl | `string` | `oauth2` (`"implicit"`, `"accessCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. From 6aded08d56c1e7bb12c981b655896f7fc7e54d3f Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 28 Oct 2016 00:29:45 -0400 Subject: [PATCH 03/10] Added flow object --- versions/3.0.md | 125 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 100 insertions(+), 25 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 42089ccb06..7b64d20ce9 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -2968,11 +2968,14 @@ Field Pattern | Type | Description }, "petstore_auth": { "type": "oauth2", - "authorizationUrl": "http://swagger.io/api/oauth/dialog", - "flow": "implicit", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" + "flow": { + "implicit": { + "authorizationUrl": "http://swagger.io/api/oauth/dialog", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } } } } @@ -2985,17 +2988,18 @@ api_key: in: header petstore_auth: type: oauth2 - authorizationUrl: http://swagger.io/api/oauth/dialog - flow: implicit - scopes: - write:pets: modify pets in your account - read:pets: read your pets + flow: + implicit: + authorizationUrl: http://swagger.io/api/oauth/dialog + scopes: + write:pets: modify pets in your account + read:pets: read your pets ``` #### Security Scheme Object Allows the definition of a security scheme that can be used by the operations. -Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code). +Supported schemes are HTTP authentication, an API key (either as a header or as a query parameter) and OAuth2's common flows (implicit, password, application and access code). ##### Fixed Fields Field Name | Type | Validity | Description @@ -3006,11 +3010,8 @@ Field Name | Type | Validity | Description in | `string` | `apiKey` | **Required** The location of the API key. Valid values are `"query"` or `"header"`. scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the Authorization header as per [RFC 7235](https://tools.ietf.org/html/rfc7235). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. +flow | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. Url may be relative to location of OpenAPI document. -flow | `string` | `oauth2` | **Required.** The flow used by the OAuth2 security scheme. Valid values are `"implicit"`, `"password"`, `"application"` or `"accessCode"`. -authorizationUrl | `string` | `oauth2` (`"implicit"`, `"accessCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. -tokenUrl | `string` | `oauth2` (`"password"`, `"application"`, `"accessCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. -scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -3067,22 +3068,96 @@ bearerFormat: JWT ```json { "type": "oauth2", - "authorizationUrl": "http://swagger.io/api/oauth/dialog", - "flow": "implicit", - "scopes": { - "write:pets": "modify pets in your account", - "read:pets": "read your pets" + "flow": { + "implicit": { + "authorizationUrl": "http://swagger.io/api/oauth/dialog", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } } } ``` ```yaml type: oauth2 -authorizationUrl: http://swagger.io/api/oauth/dialog -flow: implicit -scopes: - write:pets: modify pets in your account - read:pets: read your pets +flow: + implicit: + authorizationUrl: http://swagger.io/api/oauth/dialog + scopes: + write:pets: modify pets in your account + read:pets: read your pets +``` + +#### OAuth Flows Object + +Allows configuration of the supported OAuth Flows. + +##### Fixed Fields +Field Name | Type | Description +---|:---:|---|--- +implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow +password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow +client_credentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenApi 2.0. +authorization_code| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenApi 2.0. +refresh_token| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Refresh Token flow. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +#### OAuth Flow Object + +Configuration details for a supported OAuth Flow + +##### Fixed Fields +Field Name | Type | Validity | Description +---|:---:|---|--- +authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorization_code"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. +tokenUrl | `string` | `oauth2` (`"password"`, `"client_credentials"`, `"authorization_code"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. +scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. + +This object can be extended with [Specification Extensions](#specificationExtensions). + +##### OAuth Flow Object Examples + +```JSON +{ + "type": "oauth2", + "flow": { + "implicit": { + "authorizationUrl": "http://swagger.io/api/oauth/dialog", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + }, + "authorization_code": { + "authorizationUrl": "http://swagger.io/api/oauth/dialog", + "tokenUrl": "http://swagger.io/api/oauth/token", + "scopes": { + "write:pets": "modify pets in your account", + "read:pets": "read your pets" + } + } + } +} +``` + +```YAML +type: oauth2 +flow: + implicit: + authorizationUrl: http://swagger.io/api/oauth/dialog + scopes: + write:pets: modify pets in your account + read:pets: read your pets + authorization_code: + authorizationUrl: http://swagger.io/api/oauth/dialog + tokenUrl: http://swagger.io/api/oauth/token + scopes: + write:pets: modify pets in your account + read:pets: read your pets ``` #### Scopes Object From 00be7e39b9482dc92888b3e87c78267a6e5002d0 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 28 Oct 2016 09:53:09 -0400 Subject: [PATCH 04/10] Update to Security Requirements descriptions for clarity --- versions/3.0.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 7b64d20ce9..140aae1362 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -130,7 +130,6 @@ Field Name | Type | Description servers | [[Server Object](#serverObject)] | An optional array of Server Objects which provide connectivity information to a target server. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. @@ -526,7 +525,7 @@ Field Name | Type | Description callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation. schemes | [`string`] | The transfer protocol for the operation. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. The value overrides the OpenAPI Object [`schemes`](#oasSchemes) definition. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for this operation. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes can be used for this operation. The list of values describes alternative security schemes that can be used. Only one of the schemes need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. host | `string` | The host (name or ip) serving the path. This optional value will override the top-level [host](#oasHost) or path item-level [host](#pathItemHost). if present. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the `host` is not included, the host serving the documentation is to be used (including the port). The `host` does not support [path templating](#pathTemplating). basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#pathItemHost). This optional value will override the top-level [basePath](#oasBasePath) or path item-level [basePath](#oasPathItemBasePath) if present. If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating). schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. This optional value will override the top-level [schemes](#oasSchemes) or path-item level [schemes](#pathItemSchemes) if present. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself. @@ -3189,15 +3188,18 @@ read:pets: read your pets #### Security Requirement Object Lists the required security schemes to execute this operation. -The object can have multiple security schemes declared in it which are all required (that is, there is a logical AND between the schemes). - The name used for each property MUST correspond to a security scheme declared in the [Security Definitions](#securityDefinitionsObject). +Security Requirement Objects that contain multiple schemes require that all schemes MUST be satisfied for a request to be authorized. +This enables support for scenarios where there multiple query parameters or HTTP headers are required to convey security information. + +When a list of Security Requirement Objects is defined on the [Open API object](#oasObject) or [Operation Object](#operationObject), only one of Security Requirement Objects in the list needs to be satisfied to authorize. + ##### Patterned Fields Field Pattern | Type | Description ---|:---:|--- -{name} | [`string`] | Each name must correspond to a security scheme which is declared in the [Security Definitions](#securityDefinitions). If the security scheme is of type `"oauth2"`, 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 Definitions](#securityDefinitions). 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. ##### Security Requirement Object Examples From 78cba996a53143b55d49d9c9af6a25cbad5eac83 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 28 Oct 2016 09:55:44 -0400 Subject: [PATCH 05/10] More security requirements clarification --- versions/3.0.md | 1 + 1 file changed, 1 insertion(+) diff --git a/versions/3.0.md b/versions/3.0.md index 140aae1362..564067146f 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -130,6 +130,7 @@ Field Name | Type | Description servers | [[Server Object](#serverObject)] | An optional array of Server Objects which provide connectivity information to a target server. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes can be used across the API. The list of values describes alternative security schemes that can be used. Only one of the schemes need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. From df151d69ef796324a596361cb7717c0f59580d01 Mon Sep 17 00:00:00 2001 From: Darrel Date: Tue, 1 Nov 2016 15:52:57 -0400 Subject: [PATCH 06/10] Fix casing of flows and wording of sec reqs --- versions/3.0.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 564067146f..e192c1d759 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -130,7 +130,7 @@ Field Name | Type | Description servers | [[Server Object](#serverObject)] | An optional array of Server Objects which provide connectivity information to a target server. paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API. components | [Components Object](#componentsObject) | An element to hold various schemas for the specification. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes can be used across the API. The list of values describes alternative security schemes that can be used. Only one of the schemes need to be satisfied to authorize a request. Individual operations can override this definition. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. Individual operations can override this definition. tags | [[Tag Object](#tagObject)] | A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared may be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. @@ -526,7 +526,7 @@ Field Name | Type | Description callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation. schemes | [`string`] | The transfer protocol for the operation. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. The value overrides the OpenAPI Object [`schemes`](#oasSchemes) definition. deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. -security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes can be used for this operation. The list of values describes alternative security schemes that can be used. Only one of the schemes need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. +security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. host | `string` | The host (name or ip) serving the path. This optional value will override the top-level [host](#oasHost) or path item-level [host](#pathItemHost). if present. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the `host` is not included, the host serving the documentation is to be used (including the port). The `host` does not support [path templating](#pathTemplating). basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#pathItemHost). This optional value will override the top-level [basePath](#oasBasePath) or path item-level [basePath](#oasPathItemBasePath) if present. If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating). schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. This optional value will override the top-level [schemes](#oasSchemes) or path-item level [schemes](#pathItemSchemes) if present. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself. @@ -3099,9 +3099,9 @@ Field Name | Type | Description ---|:---:|---|--- implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow -client_credentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenApi 2.0. -authorization_code| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenApi 2.0. -refresh_token| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Refresh Token flow. +clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenApi 2.0. +authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenApi 2.0. +refresh_token| [OAuth Flow Object](#oauthFlowObject) | [TODO] DO WE NEED THIS? Configuration for the OAuth Refresh Token flow. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -3112,8 +3112,8 @@ Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Validity | Description ---|:---:|---|--- -authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorization_code"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. -tokenUrl | `string` | `oauth2` (`"password"`, `"client_credentials"`, `"authorization_code"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. +authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. @@ -3132,7 +3132,7 @@ This object can be extended with [Specification Extensions](#specificationExtens "read:pets": "read your pets" } }, - "authorization_code": { + "authorizationCode": { "authorizationUrl": "http://swagger.io/api/oauth/dialog", "tokenUrl": "http://swagger.io/api/oauth/token", "scopes": { @@ -3152,7 +3152,7 @@ flow: scopes: write:pets: modify pets in your account read:pets: read your pets - authorization_code: + authorizationCode: authorizationUrl: http://swagger.io/api/oauth/dialog tokenUrl: http://swagger.io/api/oauth/token scopes: From 06e9df23face2bde13d6c9d1a28eb08189a46b32 Mon Sep 17 00:00:00 2001 From: Darrel Date: Wed, 2 Nov 2016 09:32:01 -0400 Subject: [PATCH 07/10] Removed refresh flow --- versions/3.0.md | 1 - 1 file changed, 1 deletion(-) diff --git a/versions/3.0.md b/versions/3.0.md index e192c1d759..d4cb798072 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -3101,7 +3101,6 @@ Field Name | Type | Description password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow. Previously called `application` in OpenApi 2.0. authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow. Previously called `accessCode` in OpenApi 2.0. -refresh_token| [OAuth Flow Object](#oauthFlowObject) | [TODO] DO WE NEED THIS? Configuration for the OAuth Refresh Token flow. This object can be extended with [Specification Extensions](#specificationExtensions). From 452a988b76535db0706f9911db0ca102de021a0e Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 4 Nov 2016 14:41:09 -0400 Subject: [PATCH 08/10] Fixed casing and https --- versions/3.0.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index d4cb798072..34c5050990 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -3011,7 +3011,7 @@ Field Name | Type | Validity | Description scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the Authorization header as per [RFC 7235](https://tools.ietf.org/html/rfc7235). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flow | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. -openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. Url may be relative to location of OpenAPI document. +openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. URL may be relative to location of OpenAPI document. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -3070,7 +3070,7 @@ bearerFormat: JWT "type": "oauth2", "flow": { "implicit": { - "authorizationUrl": "http://swagger.io/api/oauth/dialog", + "authorizationUrl": "https://swagger.io/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" @@ -3084,7 +3084,7 @@ bearerFormat: JWT type: oauth2 flow: implicit: - authorizationUrl: http://swagger.io/api/oauth/dialog + authorizationUrl: https://swagger.io/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets @@ -3125,15 +3125,15 @@ This object can be extended with [Specification Extensions](#specificationExtens "type": "oauth2", "flow": { "implicit": { - "authorizationUrl": "http://swagger.io/api/oauth/dialog", + "authorizationUrl": "https://swagger.io/api/oauth/dialog", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" } }, "authorizationCode": { - "authorizationUrl": "http://swagger.io/api/oauth/dialog", - "tokenUrl": "http://swagger.io/api/oauth/token", + "authorizationUrl": "https://swagger.io/api/oauth/dialog", + "tokenUrl": "https://swagger.io/api/oauth/token", "scopes": { "write:pets": "modify pets in your account", "read:pets": "read your pets" @@ -3147,13 +3147,13 @@ This object can be extended with [Specification Extensions](#specificationExtens type: oauth2 flow: implicit: - authorizationUrl: http://swagger.io/api/oauth/dialog + authorizationUrl: https://swagger.io/api/oauth/dialog scopes: write:pets: modify pets in your account read:pets: read your pets authorizationCode: - authorizationUrl: http://swagger.io/api/oauth/dialog - tokenUrl: http://swagger.io/api/oauth/token + authorizationUrl: https://swagger.io/api/oauth/dialog + tokenUrl: https://swagger.io/api/oauth/token scopes: write:pets: modify pets in your account read:pets: read your pets From fd3e3ed8905bad2e860bf869f73fa26db6aedf5b Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 18 Nov 2016 11:37:45 -0500 Subject: [PATCH 09/10] Fixes based on PR comments --- versions/3.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index e281c7d50f..5b3ce3821d 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -3061,7 +3061,7 @@ Field Name | Type | Validity | Description description | `string` | Any | A short description for security scheme. name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used. in | `string` | `apiKey` | **Required** The location of the API key. Valid values are `"query"` or `"header"`. -scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the Authorization header as per [RFC 7235](https://tools.ietf.org/html/rfc7235). +scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC 7235](https://tools.ietf.org/html/rfc7235#section-4.2). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flow | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. URL may be relative to location of OpenAPI document. @@ -3164,9 +3164,9 @@ Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Validity | Description ---|:---:|---|--- -authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This SHOULD be in the form of a URL. Url may be relative to location of OpenAPI document. +authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. +tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. +refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This SHOULD be in the form of a URL. scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. This object can be extended with [Specification Extensions](#specificationExtensions). From 5107b5f3f5b2787aad82f9ef440d260109629ff9 Mon Sep 17 00:00:00 2001 From: Darrel Date: Fri, 18 Nov 2016 13:26:09 -0500 Subject: [PATCH 10/10] Changed SHOULD to MUST for security URLs --- versions/3.0.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.md b/versions/3.0.md index 5b3ce3821d..3ee0d88bdb 100644 --- a/versions/3.0.md +++ b/versions/3.0.md @@ -3064,7 +3064,7 @@ Field Name | Type | Validity | Description scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC 7235](https://tools.ietf.org/html/rfc7235#section-4.2). bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes. flow | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. -openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. URL may be relative to location of OpenAPI document. +openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. This object can be extended with [Specification Extensions](#specificationExtensions). @@ -3164,9 +3164,9 @@ Configuration details for a supported OAuth Flow ##### Fixed Fields Field Name | Type | Validity | Description ---|:---:|---|--- -authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL. -tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **Required.** The token URL to be used for this flow. This SHOULD be in the form of a URL. -refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This SHOULD be in the form of a URL. +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 | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme. This object can be extended with [Specification Extensions](#specificationExtensions).