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 Data Governance 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. An Gateway API Endpoint's configuration also determines how the Data Governance 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.
For example, given the URI request path "/api/User/ABCD" and the following configuration values:
↓Parent Component
↓Relations from This Component
↓Relations to This Component
↓Properties
↓dsconfig Usage
The Gateway API Endpoint component inherits from the API Endpoint
The following components have a direct aggregation relation from Gateway API Endpoints:
The following components have a direct aggregation relation to Gateway API Endpoints:
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 |
| 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 | 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 |
| 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 |
| 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 |
| 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 |
disable-response-processing (Advanced Property)
| Property Group | Authorization and Policies |
| Description | Prevents the Data Governance 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 |
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}