From 300ba4d20277e0a1869ea0248b4583b92acb0460 Mon Sep 17 00:00:00 2001 From: TimGoodwill <51429996+TimGoodwill@users.noreply.github.com> Date: Thu, 13 May 2021 15:09:24 +1000 Subject: [PATCH 1/3] Update to api-versioning.md to align with updated definitions.md Update to api-versioning.md to provide both camelCase and snake_case version payload to align with updated definitions.md case consistency reqirement. Change MUST to SHOULD - this is a significant requirement will not be implementable in some cases. --- sections/api-versioning.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sections/api-versioning.md b/sections/api-versioning.md index 9aa685c..edf0897 100644 --- a/sections/api-versioning.md +++ b/sections/api-versioning.md @@ -32,13 +32,13 @@ When new major versions are published the older version must be deprecated follo ## Minor Version -Minor version numbers are displayed on the API documentation page or part of a special management call to the API URI itself. To support this your API **MUST** implement a response to a GET request to the base URI of the API and return the following metadata in the response: +Minor version numbers are displayed on the API documentation page or part of a special management call to the API URI itself. To support this your API **SHOULD** implement a response to a GET request to the base URI of the API and return the following metadata in the response: -- **api_name:** The API Name -- **api_version:** The API Version with major and minor versions -- **api_released:** The date the API was released -- **api_documentation:** Links to the API Documentation -- **api_status:** To indicate whether an API is still active or has been deprecated. +- **api_name** or **apiName** : The API Name +- **api_version** or **apiVersion** : The API Version with major and minor versions +- **api_released** or **apiReleased** : The date the API was released +- **api_documentation:** or **apiDocumentation** : Links to the API Documentation +- **api_status** or **apiStatus** " To indicate whether an API is still active or has been deprecated. Additional metadata can be added to the response if required. From 0b3dff280646fbdf3eb1a5754d858a47d44142aa Mon Sep 17 00:00:00 2001 From: TimGoodwill <51429996+TimGoodwill@users.noreply.github.com> Date: Mon, 17 May 2021 15:02:43 +1000 Subject: [PATCH 2/3] api-security.md error corrections Error corrections missed in the v1.1 update including: * Change TLS 1.2 to 'at least' TLS 1.2 * Explicitly call out PKI Mutual TLS OAuth Client Authentication Method option, per https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml * Change reference to API Key as client 'authentication' to 'identification', as discussed in 2020. * Remove reference to 'WoG API Team'. --- sections/api-security.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/sections/api-security.md b/sections/api-security.md index 8c0f23a..d4110c9 100644 --- a/sections/api-security.md +++ b/sections/api-security.md @@ -11,7 +11,7 @@ At minimum the security standards that are defined here **MUST** be applied. Fur ## Transport Security -- ALL transport **MUST** occur over HTTPS using TLS 1.2. +- ALL transport **MUST** occur over HTTPS using at least TLS 1.2. - ALL certificates **MUST** be from SHA-2 (Secure Hash Algorithm 2) cryptographic hash functions with minimum key length of 2048. - ALL publicly accessible endpoints **MUST** use a Digital Certificate that has been signed by an approved Certificate Authority. - Internal facing endpoints **MAY** use self-signed Digital Certificates. @@ -23,6 +23,7 @@ Depending on the security classification you may be required to establish the fo - Mutual authentication between the consumer and the API Gateway - Mutual authentication between the API Gateway and the back-end API +- PKI Mutual TLS OAuth Client Authentication - IP Whitelisting of API Consumers using either API Gateway Policy or Firewall configurations - IP Whitelisting of API Publishers using either API Gateway Policy or Firewall configurations - Payload encryption while in transit @@ -33,11 +34,11 @@ Depending on the security classification you may be required to establish the fo - Basic or Digest authentication **SHOULD NOT** be used. - The `Authorization: Bearer` header **MUST** be used for authentication/authorization e.g. using a JWT token. - A refresh token **SHOULD** be provided for extending expiry time of existing token without having to provide the credentials again. -- Always set a reasonable expiration date for tokens. JWT token lifetime **SHOULD NOT*** exceed 5 minutes. +- Always set a reasonable expiration date for tokens. An OIDC access token lifetime **SHOULD NOT*** exceed 5 minutes. - JWT refresh tokens **SHOULD** be used when new JWT tokens are required outside of this lifetime. -- All APIs **MUST** have a policy that only allows access based on a valid API key. -- API keys **MUST** be used for client authentication. Use of API keys should only be permitted when TLS is enabled. Rotation policy for API Key should be implemented as well. -- API keys **SHOULD NOT** be included in the URL or query string. API keys **SHOULD** be included in the HTTP header as query strings may be saved by the client or server in unencrypted format by the browser or server application. +- All APIs **MUST** have a policy that only allows access to an authenticated client application. +- Client application identity **MUST** be established via a consistent mechanism. This may be via an API Key, client credentials (API key + secret) or via an OAuth 2.0 asserted server identity. Use of API keys should only be permitted when TLS is enabled. Rotation policy for API Key/secret should be implemented where applicable. +- API key and secret **SHOULD NOT** be included in the URL or query string. API keys **SHOULD** be included in the HTTP header as query strings may be saved by the client or server in unencrypted format by the browser or server application. - CORS headers should only be used when necessary as it reduces the overall security mechanisms built into web browsers by selectively relaxing cross-origin restrictions. - A request from Domain A is considered cross-origin when it tries to make a request to an API that is hosted in Domain B. - For security reasons, browsers restrict cross-origin HTTP requests. @@ -55,8 +56,6 @@ OAuth 2.0 can be used for authorisation. OAuth is an authorisation protocol that OpenID Connect extends the OAuth 2.0 protocol to receive information about the authenticated users such as their username and is useful when dealing with federated identity providers. -The API Team provides an OAuth service that can be used by WoG APIs. Alternatively, API Providers can link into Open ID Providers to delegate authorisation. This process can be facilitated by the WoG API Gateway. - ## Abstraction There are multiple levels of abstraction and determining the level of abstraction is largely based on the number of consumers and the cost to change the system in response to an API change. @@ -70,7 +69,7 @@ The varying levels of abstraction are as follows: | Abstraction Level | Description | | --- | --- | | `BASIC` | **Basic abstraction level** - represents the minimum abstraction required for all APIs (including point-to-point): - Use `JSON` as your default representation. - Always provide a version number in the URL to facilitate change. - Always use an API Key ID - Little or no abstraction of the Data model and expose data as required -| `INTERMEDIATE` | APIs which aim for re-use should consider Intermediate levels of abstraction: **Payload abstraction** - Represent resources from the consumer view point and be independent of the underlying system. NEVER directly expose the internal database table structure as is in your API. - Error abstraction – Handle source system errors and represent the errors in a consistent and informative. **System IDs abstraction** – Avoid exposing and sharing internal system identifiers (such as a database ID) with your consumers. Use a candidate key or a secondary identifier. +| `INTERMEDIATE` | APIs which aim for re-use should consider Intermediate levels of abstraction: **Payload abstraction** - Represent business resources as an abstraction of the domain model, independant of the implimentation, with a focus on client usability and self-service. NEVER directly expose the internal database table structure as is in your API. - Error abstraction – Handle source system errors and represent the errors in a consistent and informative. **System IDs abstraction** – Avoid exposing and sharing internal system identifiers (such as a database ID) with your consumers. Use a candidate key or a secondary identifier. | `ADVANCED` | The highest level of abstraction and it encompasses all the other levels. - Use the API Gateway pattern to take care of cross-cutting concerns such as security, traffic management and analytics/monitoring. - Use Linked Data hypermedia to promote "discoverability" of your API resources and relationships. - Consider using HATEOAS to abstract allowable actions. ## Rate Limiting @@ -124,8 +123,6 @@ It is preferable to use the security policy features available in the WoG API Ga | SSL | Listeners | SSL protocol (i.e. TLS 1.2 etc.) can be selected at listener level | Recommended | | Digital Certificate | Filter -\> Integrity | Various filters can be used for creating and validating the signature i.e. XML signature, JWT sign | Optional depends on business requirements (Recommended algorithm is RS256) | | JWT | Filter -\> Integrity | Message can be signed using JWT | Optional depends on business requirements | -| API Keys | Filter -\> Authentication | Various filters can be used for authenticating the consumers i.e. API Keys etc. | Recommended | +| API Keys | Filter -\> Authentication | Various filters can be used for identifying the consumer i.e. API Keys etc. | Recommended | | OAUTH | Filter -\> OAUTH | OAUTH can be used for authorizing the consumers | Optional as it depends on business requirements | | CORS | Listeners-\>Path | CORS can be restricted at path level | Recommended | - -The WoG API Team can provide advice on which API Gateway security policies should be applied. \ No newline at end of file From 790ab94657df3fa5aea350681b69643e2113455b Mon Sep 17 00:00:00 2001 From: TimGoodwill <51429996+TimGoodwill@users.noreply.github.com> Date: Wed, 2 Jun 2021 12:43:21 +1000 Subject: [PATCH 3/3] Update api-security.md --- sections/api-security.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sections/api-security.md b/sections/api-security.md index d4110c9..fd86f8f 100644 --- a/sections/api-security.md +++ b/sections/api-security.md @@ -36,9 +36,9 @@ Depending on the security classification you may be required to establish the fo - A refresh token **SHOULD** be provided for extending expiry time of existing token without having to provide the credentials again. - Always set a reasonable expiration date for tokens. An OIDC access token lifetime **SHOULD NOT*** exceed 5 minutes. - JWT refresh tokens **SHOULD** be used when new JWT tokens are required outside of this lifetime. -- All APIs **MUST** have a policy that only allows access to an authenticated client application. -- Client application identity **MUST** be established via a consistent mechanism. This may be via an API Key, client credentials (API key + secret) or via an OAuth 2.0 asserted server identity. Use of API keys should only be permitted when TLS is enabled. Rotation policy for API Key/secret should be implemented where applicable. -- API key and secret **SHOULD NOT** be included in the URL or query string. API keys **SHOULD** be included in the HTTP header as query strings may be saved by the client or server in unencrypted format by the browser or server application. +- Client application identity **SHOULD** be established via a consistent mechanism. This may be via an API Key, or via a more robust mechanism such as an OAuth 2.0 asserted server identity. +- Use of API keys **SHOULD** only be permitted when TLS is enabled. Rotation policy for API Key/secret should be implemented where applicable. +- API key and secret **SHOULD NOT** be included in the URL or query string. API keys **SHOULD** be included in the HTTP header as query strings may be saved by the client or server in unencrypted format by the browser or server application. - CORS headers should only be used when necessary as it reduces the overall security mechanisms built into web browsers by selectively relaxing cross-origin restrictions. - A request from Domain A is considered cross-origin when it tries to make a request to an API that is hosted in Domain B. - For security reasons, browsers restrict cross-origin HTTP requests.