Merge pull request OAI#818 from OAI/dm/securityreview

darrelmiller · web-flow · commit 848973d2fe52 · 2016-11-18T13:29:17.000-05:00
Security definition documentation updates
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -185,7 +185,7 @@ Field Name | Type | Description
 <a name="oasHosts"></a>servers | [[Server Object](#serverObject)] | An optional array of Server Objects which provide connectivity information to a target server.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
 <a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
-<a name="oasSecurity"></a>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.
+<a name="oasSecurity"></a>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.
 <a name="oasTags"></a>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.
 <a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
 
@@ -584,7 +584,7 @@ Field Name | Type | Description
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
 <a name="operationCallbacks"></a>callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation.
 <a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`.
-<a name="operationSecurity"></a>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.
+<a name="operationSecurity"></a>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.
 <a name="operationItemServer"></a>servers | [Server Object](#serverObject) | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
@@ -3025,11 +3025,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"
+        }
+      }
     }
   }
 }
@@ -3042,17 +3045,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
 ```
 
 #### <a name="securitySchemeObject"></a>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
@@ -3061,13 +3065,10 @@ Field Name | Type | Validity | Description
 <a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme.
 <a name="securitySchemeName"></a>name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used.
 <a name="securitySchemeIn"></a>in | `string` | `apiKey` | **Required** The ___location of the API key. Valid values are `"query"` or `"header"`.
-<a name="securitySchemeScheme"></a>scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the Authorization header as per RFC 7234.
-<a name="securitySchemeBearerFormat"></a>bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token should be formatted.
-<a name="securitySchemeOpenIdConnectUrl"></a>openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. 
-<a name="securitySchemeFlow"></a>flow | `string` | `oauth2` | **Required.** The flow used by the OAuth2 security scheme. Valid values are `"implicit"`, `"password"`, `"application"` or `"accessCode"`.
-<a name="securitySchemeAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"accessCode"`) | **Required.** The authorization URL to be used for this flow. This SHOULD be in the form of a URL.
-<a name="securitySchemeTokenUrl"></a>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.
-<a name="securitySchemeScopes"></a>scopes | [Scopes Object](#scopesObject) | `oauth2` | **Required.** The available scopes for the OAuth2 security scheme.
+<a name="securitySchemeScheme"></a>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).
+<a name="securitySchemeBearerFormat"></a>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.
+<a name="securitySchemeFlow"></a>flow | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. 
+<a name="securitySchemeOpenIdConnectUrl"></a>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). 
 
@@ -3077,7 +3078,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
 
 ```json
 {
-  "type": "scheme",
+  "type": "http",
   "scheme" : "basic"
 }
 ```
@@ -3124,22 +3125,95 @@ 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": "https://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: https://swagger.io/api/oauth/dialog
+    scopes:
+      write:pets: modify pets in your account
+      read:pets: read your pets
+```
+
+#### <a name="oauthFlowsObject"></a>OAuth Flows Object
+
+Allows configuration of the supported OAuth Flows.
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---|---
+<a name="oauthFlowImplicit"></a>implicit| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Implicit flow 
+<a name="oauthFlowPassword"></a>password| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Resource Owner Password flow 
+<a name="oauthFlowClientCredentials"></a>clientCredentials| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Client Credentials flow.  Previously called `application` in OpenApi 2.0. 
+<a name="oauthFlowAuthorizationCode"></a>authorizationCode| [OAuth Flow Object](#oauthFlowObject) | Configuration for the OAuth Authorization Code flow.  Previously called `accessCode` in OpenApi 2.0. 
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
+#### <a name="oauthFlowObject"></a>OAuth Flow Object
+
+Configuration details for a supported OAuth Flow
+
+##### Fixed Fields
+Field Name | Type | Validity | Description
+---|:---:|---|---
+<a name="securitySchemeAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **Required.** The authorization URL to be used for this flow. This MUST be in the form of a URL.
+<a name="securitySchemeTokenUrl"></a>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.
+<a name="securitySchemeRefreshUrl"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+<a name="securitySchemeScopes"></a>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": "https://swagger.io/api/oauth/dialog",
+      "scopes": {
+        "write:pets": "modify pets in your account",
+        "read:pets": "read your pets"
+      }
+    },
+    "authorizationCode": {
+      "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"
+      }
+    }
+  }
+}
+```
+
+```YAML
+type: oauth2
+flow: 
+  implicit:
+    authorizationUrl: https://swagger.io/api/oauth/dialog
+    scopes:
+      write:pets: modify pets in your account
+      read:pets: read your pets
+  authorizationCode:
+    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 
 ```
 
 #### <a name="scopesObject"></a>Scopes Object
@@ -3171,15 +3245,18 @@ read:pets: read your pets
 #### <a name="securityRequirementObject"></a>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
 ---|:---:|---
-<a name="securityRequirementsName"></a>{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.
+<a name="securityRequirementsName"></a>{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
 
