OAS Hub: Security Refresh/New (#47)

Co-authored-by: Sagar Batchu <sagar.batchu92@gmail.com>

Author: philsturgeon

openapi/security.mdx

@@ -11,7 +11,7 @@ When designing an API, it is important to consider the security requirements for
 
 Firstly, "security" is a general term which covers multiple authentication and authorization systems which are commonly used to keep API operations being used by only the intended actors.
 
-In OpenAPI this is broken in two halves.
+In OpenAPI this is broken in two halves. 
 
 1. Security schemes
 2. Security requirements
@@ -160,14 +160,14 @@ paths:
       security:
         - apiKey: [] # Can be access with an API key, or...
         - oauth2: # an oauth2 token which has the read scope
-            - read
+          - read
     post:
       operationId: createDrink
       summary: Create a new drink
       security:
-        - apiKey: [] # Can be accessed with an API key, or...
+        - apiKey: [] # Can be accessed with an API key, or... 
         - oauth2: # an oauth2 token which has the write scope
-            - write
+          - write
 
 components:
   securitySchemes:

openapi/security/security-schemes/security-api-key.mdx

@@ -6,12 +6,40 @@ import { Table } from "@/mdx/components";
 
 # API Key Security Scheme in OpenAPI
 
+
 An API Key security scheme is the most common form of authentication for machine-to-machine APIs and supports passing a pre-shared secret in several ways. The secret can be passed either via the Authorization header (or another custom header), as a query parameter, or via a cookie.
 
-While this is probably the most commonly used mechanism, it is generally one of the least secure. This is especially true if the key is passed outside of headers or cookies (that is, via query params, as various logging mechanisms normally store query param information).
+
+Here's an example of an API key being passed in the query string.
+
+```http
+GET /drinks?api_key=abcdef12345
+```
+
+or as a request header:
+
+```http
+GET /something HTTP/1.1
+
+Speakeasy-API-Key: abcdef12345
+```
+
+or as a cookie:
+
+```http
+GET /something HTTP/1.1
+
+Cookie: X-API-KEY=abcdef12345
+```
+
+API Keys are one of the most commonly used mechanism, but depending on what that key is and how its generated it may not well be very secure. This is especially true if the key is passed outside of headers or cookies (that is, via query params, as various logging mechanisms normally store query param information).
 
 The biggest security flaw is that most pre-shared secrets are long-lived and if intercepted, can be used until they are either revoked or expire (generally in months or years). This risk is normally tolerated for machine-to-machine applications as the chance of interception (especially when using private VPCs/TLS and other mechanisms) is relatively low compared to a key from a user's device traveling on a public network.
 
+Regardless of which method you use, HTTPS/TLS is highly recommended.
+
+## API Key Object
+
 The fields for an API Key security scheme are as follows:
 
 <Table
@@ -30,13 +58,37 @@ The fields for an API Key security scheme are as follows:
   ]}
 />
 
+To describe an API key, create an object in `securitySchemes` with a name of whatever you like. Perhaps it's just called `ApiKey` but it could be called `anythingYOULikeAuth`. So long as its easy to remember and a valid YAML string. Then the object defines `type: apiKey` and the name of the header/query/cookie parameter as it should show up in the HTTP request.
+
 ```yaml
 components:
   securitySchemes:
-    api_key:
+    ApiKey:
       type: apiKey
-      name: api_key
+      name: Speakeasy-API-Key
       in: header
 security:
-  - api_key: []
+  - ApiKey: []
+```
+
+A description can be added to let API users know where to go to find an API key, or an email address to request one.
+
+## Multiple API keys
+
+Some APIs require two API keys to be used at once, like an app ID and an app Key. In this case, it's possible to define both keys as `securitySchemes` then reference them both in the same [security requirement object](../../security.mdx).
+
+```yaml
+security:
+  - AppId: []
+    AppKey: [] # no leading dash
+components:
+  securitySchemes:
+    AppId:
+      type: apiKey
+      name: Speakeasy-App-Id
+      in: header
+    AppKey:
+      type: apiKey
+      name: Speakeasy-App-Key
+      in: header
 ```

openapi/security/security-schemes/security-http.mdx

@@ -127,11 +127,11 @@ Since all APIs need to be accurately described (warts and all), here's how to de
     { key: "field", header: "Field" },
     { key: "type", header: "Type" },
     { key: "required", header: "Required" },
-    { key: "description", header: "Description" },
+    { key: "description", header: "Description" }
   ]}
 />
 
-For example:
+For example: 
 
 ```yaml
 components:
@@ -143,6 +143,20 @@ security:
   - auth: []
 ```
 
+The description field can be used to warn developers about the risks of using Basic authentication, and to encourage them to use more secure alternatives like Bearer tokens or OAuth2.
+
+```yaml
+components:
+  securitySchemes:
+    auth:
+      type: http
+      scheme: basic
+      description: |
+        **Warning:** Basic authentication sends credentials in an easily decodable format, so this
+        should only be used over HTTPS. Instead of using your password please only use a short lived access token
+        which can be obtained from <https://example.com/tokens>.
+```
+
 ## HTTP Digest
 
 The Digest security scheme is a more secure alternative to Basic authentication. Instead of sending the username and password in plain text, Digest authentication uses a challenge-response mechanism that hashes credentials with a nonce provided by the server. This helps protect against replay attacks and credential interception.
@@ -205,3 +219,81 @@ components:
 security:
   - digestAuth: []
 ```
+
+## Overlap with other security schemes
+
+The HTTP security scheme overlaps with a few other more specific schemes.
+
+The [API Key](./security-api-key.mdx) security scheme is better suited for non-standard API keys using custom headers like `Acme-API-Key`, whereas HTTP security schemes are specifically designed for HTTP-based authentication methods using `Authorization` header.
+
+There is also some overlap with [OAuth2](./security-oauth2.mdx) and [OpenID Connect](./security-openid.mdx) security schemes. These may use bearer tokens, and they may use the JWT format, but they are more complex and involve additional flows and endpoints. The `oauth2` and `openidConnect` security schemes are better suited for any APIs using the OAuth 2.0 and OpenID Connect protocols than trying to cover it with the `http` security scheme.
+
+### Unauthorized Response
+
+As well as describing the security requirements, it also helps to describe what will happen when those requirements are not met. The 401 Unauthorized response can be returned for requests with missing security credentials, showing what the client can expect to see if this happens. This response includes the `WWW-Authenticate` header, which you may want to mention. As with other generic responses, the 401 response can be defined as a component in the `responses` section, and referenced with `$ref` to avoid repetition.
+
+```yaml
+paths:
+  /drinks:
+    get:
+      # ...
+      responses:
+        # ...
+        '401':
+          $ref: '#/components/responses/HttpErrorUnauthorized'
+    post:
+      # ...
+      responses:
+        # ...
+        '401':
+          $ref: '#/components/responses/HttpErrorUnauthorized'
+
+components:
+  responses:
+    HttpErrorUnauthorized:
+      description: Unauthorized
+      headers:
+        WWW_Authenticate:
+          schema:
+            type: string
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/ProblemDetails'
+```
+
+Learn more about describing [responses](../../responses.mdx).
+
+## Forbidden Response
+
+The 403 Forbidden response can be returned for requests that are authenticated but not authorized to access the resource. This response can also include the `WWW-Authenticate` header, but it is not required. 
+
+As with the 401 response, the 403 response can be defined as a component in the `responses` section, and referenced with `$ref` to avoid repetition. This error is using the HTTP Problem Details format, which is a standard way to provide more information about the error.
+
+```yaml
+paths:
+  /drinks:
+    get:
+      # ...
+      responses:
+        # ...
+        '403':
+          $ref: '#/components/responses/HttpErrorForbidden'
+    post:
+      # ...
+      responses:
+        # ...
+        '403':
+          $ref: '#/components/responses/HttpErrorForbidden'
+components:
+  responses:
+    HttpErrorForbidden:
+      description: Forbidden
+      headers:
+        WWW_Authenticate:
+          type: string
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/ProblemDetails'
+```

openapi/security/security-schemes/security-mutualtls.mdx

@@ -1,6 +1,6 @@
 ---
 title: MutualTLS in OpenAPI
-description: >
+description: > 
   Mutual TLS (mTLS) is a security protocol that enhances the security of API 
   communication by requiring both the client and server to authenticate each
   other using digital certificates.
@@ -45,4 +45,5 @@ components:
         full information about what this application is to obtain a certificate.
 ```
 
-That's all there is to this one.
+Learn more about Mutual TLS in the [OpenAPI Specification](https://spec.openapis.org/oas/v3.1.0#mutual-tls-security-scheme),
+or on Cloudflare's [What is Mutual TLS](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/).