Ping Identity PingAuthorize Server - Sideband API Endpoint

PingAuthorize Server Documentation Index
Configuration Reference Home

Sideband API Endpoint

Note: this component stores cluster-wide configuration data and is mirrored across all servers in the topology within the the same cluster.

Note: changes to cluster-wide configuration objects are immediately and automatically mirrored across all servers within the same cluster, so offline changes are not supported.

A Sideband API Endpoint represents an endpoint at an API service that is protected by the PingAuthorize Server Sideband API, which acts as a policy enforcement point (PEP) for requests and responses handled by an API Gateway.

Using the base-path property, a Sideband API Endpoint determines if an incoming Sideband API request is eligible for policy processing based on the path portion of its 'url' field. Other properties of a Sideband API Endpoint's configuration determine how the Sideband API forms policy decision requests to the policy decision point (PDP).

The Sideband API populates policy decision requests with several attributes that provide details about the HTTP request and/or response, provide details about the authenticated requester, and allow the PDP to target specific policy sets.

TokenOwner - An object containing attributes of the authenticated requester, as determined by an Access Token Validator.
HttpRequest - An object containing properties of the HTTP request and/or response, including the request URI, HTTP headers, query parameters, request/response body, and decoded access token.
Gateway - An object containing other properties, such as path parameters derived from the base-path and values set using the policy-request-attribute configuration property.

A Sideband API Endpoint configuration is applied to an incoming HTTP request if the request's 'url' value matches the base-path property. The base-path value may be specified using one or more parameter names wrapped in curly braces. If a parameter is used, then any matching value from the actual request path can be used in several other configuration properties.

For example, given a 'url' value "https://hostname:port/api/User/ABCD" and the following configuration values:

base-path - "/api/{resourceType}/{resourceId}"
service - "MyAPI.{resourceType}"
resource-path - "{resourceType}/{resourceId}"

Then the corresponding policy decision request will contain the following attributes, among others:

Service - "MyAPI.User"
HttpRequest.ResourceURI - "https://hostname:port/api/User/ABCD"
HttpRequest.ResourcePath - "User/ABCD"
Gateway._BasePath - "/api/User/ABCD"
Gateway.resourceType - "User"
Gateway.resourceId - "ABCD"

↓Parent Component
↓Properties
↓dsconfig Usage

Parent Component

The Sideband API Endpoint component inherits from the API Endpoint

Properties

The properties supported by this managed object are as follows:

General Configuration Basic Properties:	Advanced Properties:
↓ description	↓ error-template
↓ base-path	↓ correlation-id-header
↓ enabled
Authorization and Policies Basic Properties:	Advanced Properties:
↓ service	↓ resource-path
↓ http-auth-evaluation-behavior	↓ policy-request-attribute
↓ access-token-validator	↓ user-name
	↓ password

Basic Properties

description

Property Group	General Configuration
Description	A description for this API Endpoint
Default Value	None
Allowed Values	A string
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

base-path

Property Group	General Configuration
Description	The base HTTP request path, used to match this Sideband API Endpoint. The base-path value may be parameterized by enclosing parameter names in curly braces, as in "/users/{userId}/friends", which would match 'url' paths beginning with "/users/XYZ/friends" or "/users/1234/friends", for example. Parameter values are substituted for matching parameter names in the values of the service, resource-path, and policy-request-attribute properties. Parameters and their values are also submitted as sub-attributes of the Gateway policy request attribute when authorizing requests and responses with the policy decision point. For example, using the earlier example of a base-path of "/users/{userId}/friends", if the 'url' path begins with "/users/XYZ/friends", then the attribute Gateway.userId will be added to the PDP request with a value of "XYZ".
Default Value	None
Allowed Values	The value must start with a forward slash and must represent a valid HTTP URI path. The value may be parameterized by enclosing parameters in curly braces.
Multi-Valued	No
Required	Yes
Admin Action Required	None. Modification requires no further action

enabled

Property Group	General Configuration
Description	Indicates whether this Sideband API Endpoint is enabled for use in PingAuthorize Server.
Default Value	true
Allowed Values	true false
Multi-Valued	No
Required	Yes
Admin Action Required	None. Modification requires no further action

service

Property Group	Authorization and Policies
Description	An identifier for the API service. This will be used as the value of the Service policy request attribute when authorizing HTTP requests and responses with the policy decision point. The service name is used by policies to target requests for a particular API. The service name may be a simple value, such as "Users", or it may include a parameter enclosed by curly braces, such as "Users.{employeeType}". If a parameter is used in the service name, then the parameter must also appear in the base-path value. When an HTTP request is handled by the Sideband API Endpoint, the parameter value(s) will be computed by applying the actual request path to the base-path value. The parameter value(s) will then be used to construct the service name value sent in the authorization request to the policy decision point. For example, if the base-path property is configured as "/api/{resourceType}/{resourceId}", the service property is configured as "{resourceType}", and a request is received with the path "/api/User/ABCD", then the authorization request to the policy decision point will include the policy request attribute "Service" with a value of "User".
Default Value	If a service name is not specified, then the name of this Sideband API Endpoint will be used.
Allowed Values	A string
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

http-auth-evaluation-behavior

Property Group	Authorization and Policies
Description	Determines how this API Endpoint will handle HTTP authenticated requests for the purpose of policy enforcement. Currently, only bearer token authentication is supported.
Default Value	evaluate-and-forward
Allowed Values	do-not-evaluate - The API Endpoint will not attempt to evaluate or modify the HTTP authentication scheme. If an "Authorization" request header is provided, it will be forwarded to the API server as-is. If this value is chosen, policies that impact this API Endpoint should not enforce constraints regarding request authentication, such as access token validity. evaluate-and-forward - If a supported HTTP authentication scheme is used, the API Endpoint will attempt to evaluate the authentication credentials and make authentication information available for policy processing. If an "Authorization" request header is provided, it will be forwarded to the API server as-is unless a policy result specifically prevents the API Endpoint from doing so. evaluate-and-discard - If a supported HTTP authentication scheme is used, the API Endpoint will attempt to evaluate the authentication credentials and make authentication information available for policy processing. If an "Authorization" request header is provided, it will be removed from the request that is forwarded to the API server, effectively stripping HTTP authentication from the forwarded request. evaluate-and-replace - If a supported HTTP authentication scheme is used, the API Endpoint will attempt to evaluate the authentication credentials and make authentication information available for policy processing. Any existing "Authorization" header will be removed from the request that is forwarded to the API server and replaced with an "Authorization" header containing the basic auth credentials configured for the external server designated by this API Endpoint's api-server property. If this value is chosen, the API server will receive a fixed set of credentials, and policies will be responsible for ensuring that the original requester is authorized appropriately.
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

access-token-validator

Property Group	Authorization and Policies
Description	If specified, the Access Token Validator(s) that may be used to validate access tokens for requests submitted to this API Endpoint. This property is ignored if the http-auth-evaluation property has a value of "do-not-evaluate" or if the request does not use the RFC 6750 bearer token authentication scheme.
Default Value	If no validators are specified, then any of the Access Token Validators configured for this server may be used to validate an access token.
Allowed Values	The DN of any Access Token Validator.
Multi-Valued	Yes
Required	No
Admin Action Required	None. Modification requires no further action

Advanced Properties

error-template (Advanced Property)

Property Group	General Configuration
Description	Specifies the template that will be used when an error occurs on the server.
Default Value	If no error template is specified, then a default error response format is used.
Allowed Values	The DN of any Error Template.
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

correlation-id-header (Advanced Property)

Property Group	General Configuration
Description	Specifies the name of the HTTP header that will contain a correlation ID value. This header will be added both to requests to downstream API servers and to client responses. This property can be used to specify a custom header name for correlation IDs. The value specified here will override the correlation-id-response-header property of the HTTP Connection Handler hosting this API Endpoint. Example values are "Correlation-Id", "X-Amzn-Trace-Id", and "X-Request-Id". For this property to be used, the use-correlation-id-header property of the HTTP Connection Handler hosting this API Endpoint must be enabled. Otherwise, this property will be ignored. If a correlation ID request header specified by the HTTP Connection Handler's correlation-id-request-header property is present, that header value is used as the correlation ID. Otherwise, a correlation ID is automatically generated by the server.
Default Value	The correlation-id-response-header property of the HTTP Connection Handler hosting this API Endpoint will be used.
Allowed Values	A string
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

resource-path (Advanced Property)

Property Group	Authorization and Policies
Description	An identifier for the HTTP resource targeted by the request. This will be used as the value of the HttpRequest.ResourcePath policy request attribute when authorizing HTTP requests and responses with the policy decision point. The HttpRequest.ResourcePath value can be used by policies to identify a specific web resource. If resource-path is undefined, the HttpRequest.ResourcePath value will be set to the portion of the request path that follows the base path. For example, if the base-path is "/users", and the actual request URI path is "/users/ABCD", then HttpRequest.ResourcePath will be "ABCD". The value for this property may contain a parameter from the base-path. This can be useful if the base-path value includes a portion of the path that identifies the resource. For example, if the base-path is "/api/{userType}", then the resource-path value could be set to "{userType}". If a parameter is used in the resource-path value, then the parameter must also appear in the base-path value. When an HTTP request is handled by the Sideband API Endpoint, the parameter value(s) will be computed by applying the actual request path to the base-path value. The parameter value(s) will then be used to construct the actual HttpRequest.ResourcePath value sent in the authorization request to the policy decision point. For example, if the base-path property is configured as "/api/{resourceType}/{resourceId}", the resource-path property is configured as "{resourceType}/{resourceId}", and a request is received with the path "/api/User/ABCD", then the authorization request to the policy decision point will include the policy request attribute "HttpRequest.ResourcePath" with a value of "User/ABCD".
Default Value	If a resource-path value is not specified, then the portion of the request URI relative to the inbound-base-path will be used .
Allowed Values	A string
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

policy-request-attribute (Advanced Property)

Property Group	Authorization and Policies
Description	A custom key/value pair that will be added as a sub-attribute of the Gateway policy request attribute when authorizing HTTP requests and responses with the policy decision point. Custom policy request attributes may be used to satisfy arbitrary policy requirements. Each policy request attribute must be specified in the form KEY=VALUE. The key portion must be a constant string value, but the value portion may contain a parameter name from the base-path property. If a parameter is used in the custom policy request attribute value, then the parameter must also appear in the base-path value. When an HTTP request is handled by the Sideband API Endpoint, the parameter value(s) will be computed by applying the actual request path to the base-path value. The parameter value(s) will then be used to construct the custom policy request attribute values sent in the authorization request to the policy decision point. For example, if the base-path property is configured as "/api/{resourceType}/{resourceId}", a custom policy request attribute is configured as "myAttribute={resourceType}, and a request is received with the path "/api/User/ABCD", then the authorization request to the policy decision point will include the custom policy request attribute Gateway.myAttribute with a value of "ABCD".
Default Value	None
Allowed Values	A key/value pair using the form KEY=VALUE.
Multi-Valued	Yes
Required	No
Admin Action Required	None. Modification requires no further action

user-name (Advanced Property)

Property Group	Authorization and Policies
Description	The name of a login account to use for HTTP requests to the downstream API server using basic authentication. This property is ignored unless the http-auth-evaluation-behavior property is set to "evaluate-and-replace".
Default Value	None
Allowed Values	A string
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

password (Advanced Property)

Property Group	Authorization and Policies
Description	The name of the login password to use for HTTP requests to the downstream API server using basic authentication. This property is ignored unless the http-auth-evaluation-behavior property is set to "evaluate-and-replace".
Default Value	None
Allowed Values	A string
Multi-Valued	No
Required	No
Admin Action Required	None. Modification requires no further action

dsconfig Usage

To list the configured Sideband API Endpoints:

dsconfig list-sideband-api-endpoints
     [--property {propertyName}] ...

To view the configuration for an existing Sideband API Endpoint:

dsconfig get-sideband-api-endpoint-prop
     --endpoint-name {name}
     [--tab-delimited]
     [--script-friendly]
     [--property {propertyName}] ...

To update the configuration for an existing Sideband API Endpoint:

dsconfig set-sideband-api-endpoint-prop
     --endpoint-name {name}
     (--set|--add|--remove) {propertyName}:{propertyValue}
     [(--set|--add|--remove) {propertyName}:{propertyValue}] ...

To create a new Sideband API Endpoint:

dsconfig create-sideband-api-endpoint
     --endpoint-name {name}
     --type sideband
     --set base-path:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Sideband API Endpoint:

dsconfig delete-sideband-api-endpoint
     --endpoint-name {name}