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

Last updated: 2020-05-14

Calls to my Amazon API Gateway REST API are getting 403 Forbidden errors after I created a 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 only 403 errors related to Lambda authorizers that are configured for a REST API.

When an API Gateway REST API with a Lambda authorizer returns a 403 error, it's usually for one of the following reasons:

Resolution

Follow these troubleshooting steps to help determine the cause of the errors and resolve it.

Determine the cause of the error

1.    Review the error message in the response from API Gateway.

If the call to your API contained an invalid token or identity sources, you see an error message similar to this:

{
    errorMessage: Unauthorized
}

If the Lambda authorizer function returned an IAM policy document with an explicit deny, you see an error message similar to this:

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

If your API has an attached resource policy that implicitly or explicitly denies access to the caller, you see an error message similar to this:

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

2.    View the API Gateway execution logs in CloudWatch to review the authorization workflow. You can see the Lambda authorizer's output and the outcome of API Gateway's resource policy evaluation.

Note: If you haven't already enabled API Gateway logging to Amazon CloudWatch Logs, see How do I enable CloudWatch Logs for troubleshooting my API Gateway REST API or WebSocket API?

When a required token is missing or doesn't match the token validation, the Lambda authorizer isn't invoked, and you see log messages similar to this:

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

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

When the Lambda authorizer returns a policy that denies access, the log messages are similar to this:

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.

When the API Gateway resource policy denies the request, the log messages are similar to this:

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 "Unauthorized" errors

1.    Review your Lambda authorizer's configuration in the API Gateway console to determine what must be included in calls to your API. For more information, see Input to an Amazon API Gateway Lambda authorizer.

Note: If you change the Lambda authorizer's configuration, be sure to redeploy your API to commit the changes.

2.    Call your API again. Be sure to include the configured token or identity sources that you confirmed in the console in the previous step.

For more information, see Why am I getting API Gateway 401 Unauthorized errors after creating a Lambda authorizer?

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

If you're seeing this error intermittently, the error could be caused by policy caching. Review your Lambda authorizer's configuration in the API Gateway console to verify that Authorization Caching is enabled. Then, do any 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.
  • Disable policy caching, and then call your API again.
    Note: If you disable 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 configured 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're seeing this error consistently, review your Lambda authorizer function's code in AWS Lambda to determine why your authorizer explicitly denies access to the caller.

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

Review your API's resource policy to determine if the policy is invalid, or if it explicitly denies access to your calls. 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.