This is in beta. If you find something wrong, let us know

API Security

API Design

Applying the right level of security will allow your APIs to perform well without compromising on the security risk.

To secure your APIs the security standards are grouped into three categories: Design, Transport, and Authentication & Authorisation.

At minimum the security standards that are defined here MUST be applied. Further security considerations may apply depending on the API design and requirements – refer to our API Design Considerations section for more details.

Transport Security

Depending on the security classification you may be required to establish the following controls above and beyond the standard controls:

Authentication and Authorization

TDIF

TDIF ( Trusted Digital Identity Framework ) forms the basis of single-sign-on (SSO) user authentication for citizens to access government services across Australia. Through a series of double-blind identity exchanges, it provides a federated approach to SSO that allows user choice in terms of identity provider, as well as attribute provider capabilities. It is currently being developed at state level with states either building their own identity exchange or using the federal identity exchange. It supports OpenID Connect and SAML 2.0 - OpenID Connect is built on top of OAuth 2.0. ref: https://www.dta.gov.au/our-projects/digital-identity/trusted-digital-identity-framework

OAuth 2.0

OAuth 2.0 can be used for authorisation. OAuth is an authorisation protocol that securely delegates authorisation to another resource. It allows users to approve applications to act on their behalf without sharing their password.

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.

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.

As a general principle there should be a level of abstraction of the source system data and business logic in your API design to decouple the consumers and the API service provider(s). Applying BASIC abstraction to a SaaS API (such as an Azure API) is recommended. For example; if there are changes in the SaaS authentication schema it could be handled within the API.

A higher level of abstraction would be required for APIs that have multiple consumers and the cost of change to the API consumers is greater than the cost to change the backend systems / service providers.

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 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

Apply rate limiting and throttling policies to prevent abuse of your API. Ensure appropriate alerts are implemented and respond with informative errors when thresholds are nearing or have been exceeded.

The following headers will be returned when rate limits are in place:

Header Description
X-Rate-Limit-Limit Rate limit ceiling for the given request (for example, 100 messages).
X-Rate-Limit-Remaining Number of requests left for the time window (for example, 45 messages).
X-Rate-Limit-Reset Remaining time window before the rate limit resets in UTC epoch seconds (for example, 1353517297).

Error Handling

When your application displays error messages, it should not expose information that could be used to attack your system. You should establish the following controls when providing error messages:

Audit Logs

An important aspect of security is to be notified when something wrong occurs, and to be able to investigate it. It is RECOMMENDED to define the right level of logging and audit and to set the right alerts.

Input Validation

Input validation is performed to ensure only properly formed data is received by your system, this helps to prevent malicious attacks

Content Type Validation

Honour the specified content-type. Reject requests containing unexpected or missing content type headers with HTTP response status 415 Unsupported Media Type.

Gateway Security Features

It is preferable to use the security policy features available in the WoG API Gateway platform than to implement the policies in your back-end API.

Security API Gateway Component Comment Implementation Required
HTTP verbs Listeners->Path HTTP verbs can be selected when defining the path for the API Recommended
Input Validation Filter -> Content Filtering Various filters can be used for validating the input i.e. message size, schema validation, validate headers, validate query strings etc. Recommended
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 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

Protective Marking

Protective marking allows entities correctly assess the sensitivity or security classification of their information and adopt marking, handling, storage and disposal arrangements that guard against information compromise. Classification semantics may be unique to individual jurisdictions.

An ‘x-protective-marking’ header should be used to apply data classification. The following rules apply to the use of the ‘x-protective-marking’ header:

The content of the ‘x-protective-marking’ header should follow the following format, with additional optional semantics defined per jurisdiction:

Syntax

X-Protective-Marking: VER=<ver>, NS=<namespace>, SEC=<securityClassification>

The first key-value pair will be the classification version, which is backward compatible and should change infrequently. The second key-value pair is the classification scheme namespace. The security classification marker (and further optional markings) follow.

e.g.

x-protective-marking: VER=2018.1, NS=gov.au, SEC=PROTECTED

For Commonwealth data the Australian Government (gov.au) namespace should be used, and the values (and case) of the header should align with the appropriate Security classification literals defined in the Protective Security Policy Framework, and conforming to the syntax prescribed in the Annex B Email protective marking standard.

State or territory governments may use the Australian Government (gov.au) namespace and semantics, or they may use a their own namespace value (different from the Australian Government) and apply rules specific to their jurisdiction.

Content (payload) classified as having a high business impact level or above MUST NOT be logged, unless over secure channels and to platforms approved for the retention of data to the appropriate classification.