PingAuthorize Server Documentation Index
Configuration Reference Home

Gateway 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 Gateway API Endpoint represents an endpoint at an API service that is protected by the PingAuthorize Server Gateway, which acts as a facade and policy enforcement point (PEP) for the API service.

A Gateway API Endpoint controls how incoming HTTP requests matching a particular request path are routed to a backend API service. A Gateway API Endpoint's configuration also determines how the PingAuthorize Server Gateway forms policy decision requests to the policy decision point (PDP).

The Gateway 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.

  1. TokenOwner - An object containing attributes of the authenticated requester, as determined by an Access Token Validator.
  2. 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.
  3. Gateway - An object containing other properties, such as path parameters derived from the inbound-base-path and values set using the policy-request-attribute configuration property.
A Gateway API Endpoint configuration is applied to an incoming HTTP request if the request URI path matches the inbound-base-path property. The inbound-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 the URI request path "/api/User/ABCD" and the following configuration values:

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

Parent Component
Relations from This Component
Relations to This Component
Properties
dsconfig Usage

Parent Component

The Gateway API Endpoint component inherits from the API Endpoint

Relations from This Component

The following components have a direct aggregation relation from Gateway API Endpoints:

Relations to This Component

The following components have a direct aggregation relation to Gateway API Endpoints:

Properties

The properties supported by this managed object are as follows:


General Configuration Basic Properties: Advanced Properties:
↓ description ↓ error-template
↓ inbound-base-path ↓ correlation-id-header
↓ outbound-base-path
↓ api-server
Authorization and Policies Basic Properties: Advanced Properties:
↓ service ↓ resource-path
↓ http-auth-evaluation-behavior ↓ policy-request-attribute
↓ access-token-validator ↓ disable-response-processing
↓ strict-http-request-validation

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

inbound-base-path

Property Group
General Configuration
Description
The base path to use for incoming HTTP requests handled by this Gateway API Endpoint. The inbound-base-path value may be parameterized by enclosing parameter names in curly braces, as in "/users/{userId}/friends", which would match requests URI paths beginning with "/users/XYZ/friends" or "/users/1234/friends", for example.

Parameter values are substituted for matching parameter names in outbound-base-path when constructing URI paths for requests forwarded to the downstream API server. Similar substitutions will be performed for parameter names found in the values of the service, resource-path, and policy-request-attribute properties.

Parameters and their values are 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 an inbound-base-path of "/users/{userId}/friends", if the request URI 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

outbound-base-path

Property Group
General Configuration
Description
The base path used in requests forwarded to the downstream API server. The value may be parameterized by enclosing parameters in curly braces, as in "/users/{userId}/friends". When constructing the URI path for requests forwarded to the downstream API server, the parameter values used will be those obtained by applying the client request path to the inbound-base-path value. Any parameters named in the outbound-base-path value must therefore also appear in the inbound-base-path value.

For example, if the inbound-base-path property is configured with the value "/profiles/{userId}", the outbound-base-path property is configured with the value "/usermgmt/v1/{userId}", and a request is received with the path "/profiles/ABCD", then the actual request path used in the request to the API server will be "/usermgmt/v1/ABCD".

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

api-server

Property Group
General Configuration
Description
Specifies the HTTP server that hosts the API that will be proxied by this Gateway API Endpoint.
Default Value
None
Allowed Values
The DN of any API External Server.
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 inbound-base-path value. When an HTTP request is handled by the API Endpoint, the parameter value(s) will be computed by applying the actual request path to the inbound-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 inbound-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 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 inbound-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 inbound-base-path. This can be useful if the inbound-base-path value includes a portion of the path that identifies the resource. For example, if the inbound-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 inbound-base-path value. When an HTTP request is handled by the API Endpoint, the parameter value(s) will be computed by applying the actual request path to the inbound-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 inbound-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 inbound-base-path property.

If a parameter is used in the custom policy request attribute value, then the parameter must also appear in the inbound-base-path value. When an HTTP request is handled by the API Endpoint, the parameter value(s) will be computed by applying the actual request path to the inbound-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 inbound-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

disable-response-processing (Advanced Property)

Property Group
Authorization and Policies
Description
Prevents the PingAuthorize Server Gateway from performing policy processing for responses.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action

strict-http-request-validation (Advanced Property)

Property Group
Authorization and Policies
Description
Specifies whether Gateway API Endpoint should enable strict HTTP request validation. If this is enabled, certain commonly-used but noncompliant requests (such as GET with a message body) will be rejected with an error response.
Default Value
false
Allowed Values
true
false
Multi-Valued
No
Required
No
Admin Action Required
None. Modification requires no further action


dsconfig Usage

To list the configured Gateway API Endpoints:

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

To view the configuration for an existing Gateway API Endpoint:

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

To update the configuration for an existing Gateway API Endpoint:

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

To create a new Gateway API Endpoint:

dsconfig create-gateway-api-endpoint
     --endpoint-name {name}
     --type gateway
     --set inbound-base-path:{propertyValue}
     --set outbound-base-path:{propertyValue}
     --set api-server:{propertyValue}
     [--set {propertyName}:{propertyValue}] ...

To delete an existing Gateway API Endpoint:

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