How do I troubleshoot HTTP 403 Forbidden errors when using a Lambda authorizer with an API Gateway REST API?

Last updated: 2021-05-18

Calls to my Amazon API Gateway REST API are getting 403 Forbidden errors after I created an AWS Lambda authorizer. How do I troubleshoot these errors?

Short description

Note: API Gateway can return 403 Forbidden errors for a variety of reasons. This article addresses 403 errors related to Lambda authorizers that are configured for a REST API only. For information on troubleshooting other types of 403 errors, see How do I troubleshoot HTTP 403 Forbidden errors from API Gateway?

There are two common reasons why an API Gateway REST API with a Lambda authorizer returns a 403 error:

If the call to your API has a token or identity sources that are missing, null, or not validated, you'll see a 401 Unauthorized error. For more information, see Why am I getting API Gateway 401 Unauthorized errors after creating a Lambda authorizer?

Resolution

Confirm the cause of the error

Note: If you haven't done so already, turn on CloudWatch Logs for your API Gateway REST API.

1.    Review the error message in the response from API Gateway. Look for an error message similar to one of the following.

Example error message for Lambda authorizer functions that return an IAM policy document with an explicit deny

{
    "message": "User is not authorized to access this resource with an explicit deny"
}

Example error message for REST APIs that have an attached resource policy that implicitly denies access to the caller

{
    "message": "User: anonymous is not authorized to perform: execute-api:Invoke on resource: <api-resource-arn>"
}

Example error message for REST APIs that have an attached resource policy that explicitly denies access to the caller

{
    "message": "User: anonymous is not authorized to perform: execute-api:Invoke on resource: <api-resource-arn> with an explicit deny"
}

Note: For more information on resulting behavior when access to an API Gateway API is controlled by an IAM policy, see Policy evaluation outcomes.

2.    View the API Gateway execution logs in CloudWatch to review the authorization workflow. You see the Lambda authorizer's output and the outcome of API Gateway's resource policy evaluation. You also see a log error message similar to one of the following.

Example log error message for when a required token is missing or doesn't match the token validation

Extended Request Id: MY92nHDwwwIdGxzR=
Unauthorized request: <request-id>

Note: The Extended Request Id is randomly generated. The Extended Request Id value in your logs will be different.

Example log error message for when a Lambda authorizer returns a policy that denies access

Sending request to https://lambda.<region>.amazonaws.com/2015-03-31/functions/<lambda-authorizer-arn>/invocations
Authorizer result body before parsing:
{
    "principalId": "user",
    "policyDocument": {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Action": "execute-api:Invoke",
                "Effect": "Deny",
                "Resource": "<resource-arn>"
            }
        ]
    }
}
Using valid authorizer policy for principal: <principal>
Successfully completed authorizer execution
The client is not authorized to perform this operation.

Note: The policy returned is dependent on your Lambda authorizer.

Example log error message for when the API Gateway resource policy denies the request

Extended Request Id: MY-BIVb4GEdGeZB=
ExplicitDenyException User: anonymous is not authorized to perform: execute-api:Invoke on resource: <api-resource-arn> with an explicit deny: <request-id>

Resolve "not authorized to access this resource" errors from the Lambda authorizer

If you're seeing not authorized to access this resource errors intermittently, the error could be caused by policy caching. To confirm that Authorization Caching is turned on, review your Lambda authorizer's configuration in the API Gateway console. Then, do one of the following:

  • For a one-time test, run the flush-stage-authorizers-cache command from the AWS Command Line Interface (AWS CLI). With the authorizer's cache entries flushed, call your API again.
  • Turn off policy caching, and then call your API again.
    Note: When you turn off policy caching for a request parameter-based authorizer, API Gateway doesn't validate calls to your API before invoking the Lambda authorizer function.
  • Change the authorizer's cache key by updating the header name specified in Token Source (for token-based authorizers) or any Identity Sources (for request parameter-based authorizers). Redeploy your API to commit the changes. Then, call your API again using the newly configured token header or identity sources.

If you see the errors consistently, determine why your authorizer explicitly denies access to the caller by reviewing your Lambda authorizer function's code. Then, update the code so that it allows access to the caller.

Resolve "not authorized to perform: execute-api:Invoke" errors

Determine if your APIs resource policy isn't valid, or if it explicitly denies access to your calls by reviewing your API's resource policy. You can view your API's execution logs to see the response outcome for the resource policy.

For more information, see Access policy language overview for Amazon API Gateway and Lambda authorizer and resource policy.