API security gateway authentication

The API security gateway authenticates requests through bearer tokens by default, and you can configure it to handle authentication according to your preferences.

Although the gateway doesn’t require the authentication of requests, the default policy set requires bearer token authentication.

To support this, the gateway uses the configured access token validators to evaluate bearer tokens that are included in incoming requests. The validation result is supplied to the policy request in the HttpRequest.AccessToken attribute, and the user identity associated with the token is provided in the TokenOwner attribute.

Policies use this authentication information to affect the processing of requests and responses. For example, a policy in the default policy set requires that all requests are made with an active access token.

Rule: Deny if HttpRequest.AccessToken.active Equals false

Statement:
  Code: denied-reason
  Applies To: Deny
  Payload: {"status":401, "message": "invalid_token", "detail":"Access token is expired or otherwise invalid"}

Gateway API Endpoints include the following configuration properties to specify how client authentication is handled:

http-auth-evaluation-behavior

Determines whether the Gateway API Endpoint evaluates or modifies the HTTP authentication scheme and whether this scheme is forwarded to the API server.

This property accepts the following values:

do-not-evaluate

The Gateway API Endpoint doesn’t evaluate or modify the HTTP authentication scheme. This can be useful when implementing an authentication scheme that doesn’t evaluate bearer tokens, such as MTLS.

If the client request includes an Authorization header, the PingAuthorize Server forwards the unmodified header to the external API server.

If you specify this value, policies protecting this endpoint should not enforce constraints on request authentication, such as the validity of the access token. The default policy snapshot enforces such a constraint in the Token Validation policy.

evaluate-and-forward

The Gateway API Endpoint evaluates the provided authentication credentials and makes authentication information available for policy evaluation. If the client request includes an Authorization header, the PingAuthorize Server forwards the unmodified header to the external API server unless a policy decision directs otherwise.

This value is set by default.

evaluate-and-discard

The Gateway API Endpoint evaluates the provided authentication credentials and makes authentication information available for policy evaluation. If the client request includes an Authorization header, the PingAuthorize Server removes this header before forwarding the request to the external API server.

evaluate-and-replace

The Gateway API Endpoint evaluates the provided authentication credentials and makes authentication information available for policy evaluation. If the client request includes an Authorization header, the PingAuthorize Server replaces this header with one containing the basic authentication credentials defined for the external API server.

If you specify this value, make sure your authorization policies enforce an appropriate level of authorization for the client.

access-token-validator

Sets the access token validators that the Gateway API Endpoint uses. By default, this property has no value, and the Gateway API Endpoint can evaluate every bearer token by using each access token validator that is configured on the server. To constrain the set of access token validators that a Gateway API Endpoint uses, set this property to use one or more specific values.

If http-auth-evaluation-behavior is set to do-not-evaluate, this setting is ignored.