Skip to content

Request Verification

Connect API implementations want to ensure all requests are coming from the Connect API Gateway. This is done by verifying the API key specified in the request, and checking the request origin for the appropriate I.P. address.

After reading this article, you will understand:

  • the request flow for every API request
  • the responsibility of each component
  • how to verify a request for its origin

The Request Flow Sequence

Every request to the Connect API goes through the following sequence:

flowchart TD
    client(Client)
    aws(AWS API Gateway)
    authorizer(AWS Authorizer)
    connect(Connect API Gateway)
    identity(Identity Manager)
    tms(Implementation)

    client --> |send request| aws
    aws <--> |authorize token| authorizer
    aws --> |forward request| connect
    connect <--> |get implementation url| identity
    connect --> |dispatch| tms

The Client sends a request to the Connect API endpoint, which is handled by an instance of AWS API Gateway. The AWS API Gateway uses a Cognito authorizer to authorize and authenticate the request token; then, it forwards the request to the Connect API Gateway.

The Connect API Gateway extracts information from the token to verify the identity of the request through Identity Manager. This also determines the URL of the specific implementation to which the request should be dispatch.

The Connect API Gateway replaces the X-API-Key header with the implementation’s configured API key value. This value is unique per implementation (not per request), remains stable across requests, and corresponds to the apiKey retrieved from Vault until you rotate it. Then, the request is dispatched to the implementation including all components of the original request.

The response is returned to the Client unmodified.

Verifying A Connect Request

Implementations of the Connect API must verify that all requests are coming from a valid source. This is done by verifying two pieces of information: the API key and the request origin.

Requests that reach a Connect API implementation are valid only if they contain the correct API key and originate from the Connect API Gateway. All other requests must be rejected with a 403 Forbidden response.

The valid API key and list of valid origins is maintained in a secret that can be retrieved through the Connect Vault Service API. This secret has a key of ptga-client-params, and it returns both pieces of information: the valid API key, and the valid origins:

GET https://vault.envaseconnect.cloud/secrets/ptga-client-params

The response body will contain the secret information that can be used to validate the request, and it typically has a structure similar to the following: 

{
    "id": "ptga-client-params",
    "ern": "ern:vault:prd:ptga-client-params",
    "arn": "arn:aws:secretsmanager:us-east-1:{aws-account-id}:secret:ern/vault/prd/ptga-client-params-{random-suffix}",
    "secret": {
        "apiKey": "the-api-key-used-by-connect-gateway",
        "ipAllowlist": [
            "88.888.888.88",
            "99.999.999.99"
        ]
    }
}

The response contains a secret property with the apiKey that Connect Gateway will send with the request. If the value of the X-API-Key header doesn't match this value, the request must be forbidden (403 Forbidden).

The response also contains an array of allowed IPs. You should validate the request comes from one of these IPs. Prefer validating the actual peer/source IP as seen by your application platform (for example, the remote address provided by your web server or runtime).

If you rely on the X-Forwarded-For header instead of the direct source IP, you must ensure that a trusted ingress or proxy strips any incoming X-Forwarded-For headers from clients and then appends the immediate upstream IP in a well-defined position. In that case, only compare the allowlisted IPs against the specific position documented by your ingress (for example, the first or last IP), not against every IP in the header.

⚠️ The X-Forwarded-For header can have multiple IPs separated by commas. Unless your ingress normalizes this header by removing any client-provided values and appending its own, it should be treated as attacker-controlled input. Do not allow a request just because any IP in X-Forwarded-For matches the allowlist; instead, validate only the trusted IP position defined by your network architecture.

Validating the Authorization Token

You may decide to validate the access token provided in the Authorization header of the request. This token has been validated by the Authorizer in AWS, and you doing the same will impact performance. Validating tokens is, by design, slow, so you want to minimize the number times it is done.

Instead, enforce security by only allowing requests from known origins. This can be done through code as explained in the section above, or even by configuration of your firewall, security group, vpc, etc.

If you decide to validate the access token, you can contact the Connect team for the information you need to access the public keys.

Conclusion

Implementations of the Connect API interface must verify requests are coming from a known source. This is done by checking the values in the X-API-Key and X-Forwarded-For headers.

The whitelisted values for these two headers are stored in the Connect Vault Service API under the ptga-client-params key. These values can be retrieved for validation.

Alternatively, these values can be retrieve and used to configure any firewalls, security groups, or VPCs protecting your service implementation. They seldom change, so they don't require a lot of maintenance.

Validating the access token can be expensive and impact the performance of your API, so it is not recommended. If you choose to do so, you can request the public key information from the Connect team.