Note: this is an abstract component that cannot be instantiated.
An API Endpoint represents an endpoint at an API service that is protected by the PingAuthorize Server, which acts as a policy enforcement point (PEP) for the API service. All requests and responses routed through the PingAuthorize Server are authorized with a policy decision point (PDP).
↓Direct Subcomponents
↓Relations from This Component
↓Properties
The following API Endpoints are available in the server :
These API Endpoints inherit from the properties described below.
The following components have a direct aggregation relation from API Endpoints:
The properties supported by this managed object are as follows:
| General Configuration Basic Properties: | Advanced Properties: |
|---|---|
| ↓ description | ↓ error-template |
| ↓ correlation-id-header | |
| Authorization and Policies Basic Properties: | Advanced Properties: |
| ↓ service | ↓ resource-path |
| ↓ http-auth-evaluation-behavior | ↓ policy-request-attribute |
| ↓ access-token-validator |
| 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 |
| 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 |
| 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 |
| 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 |
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 |