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

Short description

Note: This solution addresses 403 errors that are related to Lambda authorizers configured for a REST API only. For information about how to troubleshoot other types of 403 errors, see How do I troubleshoot HTTP 403 errors from API Gateway?

"403 Forbidden" errors might occur because of the following reasons:

• The AWS Identity and Access Management (IAM) policy document returned by the Lambda authorizer function explicitly denies access to the caller.
• The IAM policy document returned by the Lambda authorizer function either doesn't allow or implicitly denies access to the caller. The resource policy that's attached to the API also doesn't allow or implicitly denies access to the caller.
• The API has an attached resource policy that explicitly denies access to the caller.

If your API call has a token or identity source that's missing, null, or not validated, then you get a "401 Unauthorized" error. For more information, see Why do I get API Gateway "401 Unauthorized" errors after I create a Lambda authorizer?

Resolution

Confirm the cause of the error

If you haven't already done so, turn on Amazon CloudWatch Logs for your API Gateway REST API. If you change the authorizer configuration, then redeploy the API.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Review the error log message

In the response from API Gateway, look for an error log message in the following examples.

Example error log 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 log message for REST APIs with an attached resource policy that implicitly denies access to the caller:

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

Example error log message for REST APIs with 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 about API Gateway APIs that an IAM policy controls, see Policy evaluation outcome tables.

View the API Gateway logs

To review the authorization workflow, view the API Gateway execution logs in CloudWatch Logs. Note the Lambda authorizer's output and outcome of the API Gateway resource policy evaluation. Look for a log error message in the following examples.

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

Extended Request Id: EXAMPLEabcIdGxzR=Unauthorized request: request-id

Note: The Extended Request Id value in your logs is different because it's randomly generated.

Example error log message if a Lambda authorizer returns a policy that denies access:

Sending request to https://lambda.region.amazonaws.com/2015-03-31/functions/lambda-authorizer-arn/invocationsAuthorizer 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 depends on your Lambda authorizer. If the resource-arn of the returned policy doesn't include the requesting resource, then the policy implicitly denies requests.

Example error log message if the API Gateway resource policy denies the request:

Extended Request Id: EXAMPLE1ABdGeZB=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 "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, take one of the following actions:

• For a one-time test, run the AWS CLI command flush-stage-authorizers-cache. When the authorizer's cache entries are flushed, call your API again.
• Turn off policy caching, redeploy your API to commit the changes, and then call your API again.
  Note: If policy caching is deactivated for a request parameter-based authorizer, then API Gateway doesn't validate calls to your API before it invokes the Lambda authorizer function.
• To change the authorizer's cache key, update the header name that's 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 with the newly configured token header or identity sources.

To determine why your authorizer explicitly denies access to the caller, review your Lambda authorizer function's code. If you determine that the issue is because of caching, then update the code to allow 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 "User is not authorized to access this resource" errors?

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

To determine if your API resource policy isn't valid, or if it explicitly denies access to your calls, review your API resource policy. You can view your API 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.

Related information

Use API Gateway Lambda authorizers

Control and manage access to REST APIs in API Gateway