Security

This section describes security principles and patterns applicable to API development.

Northbound security

Users must be authenticated before using the API. This can be implemented in different ways. OAuth 2.0 or any token authentication is a secure option (see Chapter 3.3 Fundamentals). The appropriate method depends on many factors, such as the openness of the API. For more detailed information on northbound security, including specific policies, see the Cookbook.

API Type	Public	Partner	Internal
Guideline	Must	Must	Must

Southbound security

The purpose of southbound security is to ensure that all traffic goes through the API management solution, preventing bypassing of security measures. This means the web service that exposes the data must only be accessible via the API management solution. Any other connection must be rejected.

The best way to enforce this is by implementing two-way TLS (mTLS), which uses public key cryptography and certificates on both client and server sides to authenticate both parties. In this setup, Apigee acts as the TLS client, while the backend API acts as the TLS server.

To properly implement mTLS, both parties must verify each other’s identity using certificates stored in a Trust Store. Production and Acceptance environments should use certificates signed by a recognised authority, stored securely in a TLS keystore.

If two-way SSL is not supported by the backend, an exception must be approved by the security officer. In such cases, alternative security mechanisms such as IP whitelisting and API-specific secrets may be used.

API Type	Public	Partner	Internal
Guideline	Must	Must	Must

note

If you require further clarification or assistance, please reach out to the security officer or your local security team.

Fundamentals

Identification

Identification concerns identity tracking: who or which app is using the API. Generally, this is done by using an API key. Other identity tracking can be done via IP address and host header. When end users are involved who need to log in, only using identification will not be enough.

Standards: API key, IP address, and host header.

Authentication

Confirming whether someone or something is who or what they claim to be. Often, a username and password are sent in an authorisation header (basic) or form parameters. The provided credentials are compared to those in the database. If they match, the user is considered authenticated.

Standards: AD/LDAP, OpenID Connect.

Authorisation

Determining what a user or app can do. Specifying or checking user account permissions, access rights, or privileges for resources. It can be defined in roles. Is this user or app allowed to perform this action? Usually, authorisation is preceded by authentication. For OAuth v2.0, a token is sent in an authorisation header (bearer).

Standards: OAuth v2.0, SAML 2.0.

OAuth grant type

Grant types are a way to specify how a client can interact with an identity provider (IDP). The Open Authorisation (OAuth) framework specifies several grant types.

OAuth 2.0 should always be the preferred OAuth implementation.

For security purposes, it is recommended to implement one of the most common OAuth grant types, if supported by the platform:

• Authorisation Code: Used to obtain an access token. In the case of a successful access token request, the client will receive an authorisation code, which it can use to obtain an access token from the authorisation server.
• Proof Key for Code Exchange (PKCE): Used to prevent CSRF and authorisation code injection attacks. It is used as an addition to the Authorisation Code flow. It is not considered a replacement for a client secret and is recommended even if a client is using a client secret.
• Client Credential: Used to obtain an access token without user context. It is used for machine-to-machine authentication or service accounts where there is no user involved. Any application can receive an access token by sending the client ID and client secret keys to the authorisation server.
• Device Code (Device Authorisation Grant): Used by browserless or input-constrained devices in the device flow to exchange a previously obtained device code for an access token.
• Refresh Token: Used to obtain a refresh token that can be exchanged for an access token when the access token has expired.

When implementing OAuth, it is not recommended to use the following legacy OAuth grant types:

• Implicit Flow: A simplified version of the Authorisation Code grant type optimised for clients running in the browser. Due to security issues, it is no longer recommended by OAuth creators.
• Password Grant: Works by exchanging user credentials (e.g., username and password) to obtain an access token.

When to choose what type to use for your API?

This depends on the use case. The following questions should be considered when making a choice:

• Who is connecting to the API and how? (user through mobile app, browser, server-to-server)
• What authentication/authorisation does the backend require?
• Is there an Active Directory/identity provider available? Is there a central place in the current IT landscape where users are managed?
• What standards concerning identification, authentication, and authorisation are used in the current IT landscape?
• Is this an internal or external API?
• How scalable and robust does the solution need to be?

Security is a profession on its own. More details about security on APIs are covered in a separate document. For the latest version, see Reference Documents.

Tokens

Token types

Tokens come in different shapes and sizes. We make a distinction between opaque tokens and transparent tokens:

Token type

Token Type	Description
Opaque	Token is encrypted and consists of a random sequence of alphanumeric characters that contain no inherent meaning. The token itself does not contain any content. To obtain the content, an additional endpoint is required.
Transparent	Token is not encrypted (often encoded and signed). The token contains content, and the content can be read by anyone. Example: JWT

In web services, the two most common types of tokens are JSON Web Tokens (JWTs) and opaque tokens. A JWT token is a JSON string that contains all the claims and information it represents and is certified by a signature from the issuer. By default, it’s unencrypted, but it can be encrypted via the JSON Web Encryption (JWE) standard.

An opaque token’s format is chosen by the issuer of the token. Usually, it’s a string of numbers or characters that identifies some information in the database of the issuer. This is in contrast to JWTs, where the holder of the token can’t inspect it without contacting the issuer.

It is recommended to pass the access token within the authorisation header instead of a custom header.

For example, the Basic and Digest authentication schemes are dedicated to authentication using a username and a secret. The Bearer authentication scheme is dedicated to authentication using a token.

Token introspection endpoint

Sometimes, it can be important for a protected resource to determine the status and retrieve meta-information about a token. This should be possible by using the token introspection endpoint (RFC 7662).

Example: A backend would like to know if the token from the request contains certain scopes. In this case, it could call the introspection endpoint to retrieve this information.

Request example:

POST <host>/token/introspect
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorisation: "Bearer" + <access token>

token=<access token to be inspected>&tokenType=<type of token>*

*tokenType is optional.

Response example:

Active token response:

200 OK
Content-Type: application/json

{
    "active": true,
    "clientId": "l238j323ds-23ij4",
    "appName": "portalApp",
    "email": "[email protected]",
    "username": "jdoe",
    "productList": "[retail, oauth]",
    "scope": "read write dolphin",
    "tokenType": "JWT",
    "expiresIn": "3425"
}

Revoked or inactive token response:

200 OK
Content-Type: application/json

{
    "active": false
}