Authenticating API server requests

As with the API security gateway, API server requests authorized by the Sideband API don’t require authentication. However, the default policy set requires bearer token authentication.

About this task

The Sideband API uses configured Access Token Validators to evaluate bearer tokens that are included in incoming requests. The HttpRequest.AccessToken attribute supplies the validation result to the policy request, and the TokenOwner attribute provides the user identity that is associated with the token.

Policies use this authentication information to affect the processing requests and responses. For example, the following policy in the default policy set requires all requests to be 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"}

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

http-auth-evaluation-behavior

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

This property accepts the following values:

do-not-evaluate

The Sideband 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 through the API gateway.

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 Sideband 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 through the API gateway unless a policy decision directs otherwise.

This value is set by default.

evaluate-and-discard

The Sideband 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 through the API gateway.

evaluate-and-replace

The Sideband 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 Sideband API Endpoint uses. By default, this property has no value, and the Sideband 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 Sideband 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.