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 that are 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 can 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 is 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 the API must be redeployed.

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

Review the error message

In the response from API Gateway, look for an error message that's 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 with an attached resource policy that implicitly denies access to the caller. The Lambda authorizer functions also returns an IAM policy document with an implicit deny:

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

Example error 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 controlled by an IAM policy, 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 the outcome of the API Gateway resource policy evaluation. Look for a log error message similar to one of the following.

Example log error message if 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 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 request is implicitly denied.

Example log error message if 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 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. 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 invoking the Lambda authorizer function.
• To change the authorizer's cache key, update 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 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 caused by 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

Controlling and managing access to a REST API in API Gateway