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

Last updated: 2022-08-26

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

This error can occur if:

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

Note: 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?

Resolution

Confirm the cause of the error

Note:

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 Lambda authorizer functions that return an IAM policy document with an implicit deny

{
    "message": "User is not authorized to access this resource"
}

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 outcome tables.

2.    View the API Gateway execution logs in CloudWatch to review the authorization workflow. Note the Lambda authorizer's output and the outcome of the API Gateway's resource policy evaluation. You get 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 is 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. If the resource-arn of the returned policy does not include the requesting resource, request will be implicitly denied.

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

You might get the not authorized to access this resource errors intermittently because of 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 AWS CLI command flush-stage-authorizers-cache. 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 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 find the errors consistently, determine why your authorizer explicitly denies access to the caller by reviewing your Lambda authorizer function's code. If you have that determined that the issue is caused by caching, you can update the code so that it allows access to the caller. For instructions, see Why is my API Gateway proxy resource with a Lambda authorizer that has caching activated returning HTTP 403 errors?

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 get 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.