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

Short description

Note: The following resolution addresses 403 errors related to Lambda authorizers configured for REST APIs only. For information about how to troubleshoot other types of 403 errors, see How do I troubleshoot HTTP 403 errors from API Gateway?

You could receive "403 Forbidden" errors for 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 your API Gateway logs, look for an error message similar to 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 in an identity-based policy"}

Example error log message for REST APIs with 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 because no resource-based policy allows the execute-api:Invoke action"}

Note: An implicit deny from a resource policy results only in a 403 error when no other authorization mechanism explicitly allows the request. If a Lambda authorizer returns an Allow statement, then it overrides the implicit deny from the resource policy and the request succeeds.

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 in a resource-based policy"}

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 logs in CloudWatch Logs. Note the output of the Lambda authorizer and the outcome of the API Gateway resource policy evaluation. Look for a log error message similar to 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
Gateway response type: UNAUTHORIZED with status code: 401

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:

Starting authorizer: AUTHORIZER_ID for request: REQUEST_ID
Incoming identity: {IDENTITY_SOURCE=MASKED_VALUE}
Using valid authorizer policy for principal: PRINCIPAL
Successfully completed authorizer execution
The client is not authorized to perform this operation.
Gateway response type: ACCESS_DENIED with status code: 403

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 in a resource-based policy: REQUEST_ID
Gateway response type: DEFAULT_4XX with status code: 403

Resolve 403 errors caused by a resource ARN mismatch in the authorizer response

A Lambda authorizer can return a valid Allow policy. If the Resource Amazon Resource Name (ARN) in the policy statement doesn't match the ARN of the invoked API Gateway method, then you receive a "403 Forbidden" response. There are no additional details about the error in the API Gateway response or CloudWatch Logs.

This scenario occurs when the authorizer constructs the Resource ARN dynamically and introduces a mismatch in any of the following components:

• The API stage name, for example, prod instead of dev
• The HTTP method, for example, GET instead of POST
• The resource path, for example, /users instead of /users/*

To resolve this issue, complete the following steps:

1. Review the output of your Lambda authorizer in CloudWatch Logs. Locate the Resource field in the IAM policy document that the authorizer returns.
2. Compare the Resource ARN in the policy to the ARN of the API Gateway method that you invoke. The ARN must use the following format:
   arn:aws:execute-api:{region}:{account-id}:{api-id}/{stage}/{HTTP-METHOD}/{resource-path}
3. Confirm that the stage, HTTP method, and resource path in the authorizer's response exactly match the method that you call. For example, if you invoke GET /prod/users, then the Resource ARN must include prod/GET/users, not dev/GET/users or prod/POST/users.
4. If the authorizer uses a wildcard (*) in the Resource field, then confirm that the wildcard pattern covers the invoked method. For example, arn:aws:execute-api:{region}:{account-id}:{api-id}/prod/GET/* allows all GET requests under the prod stage.
5. Update your Lambda authorizer code to return the correct Resource ARN that matches the invoked API method, and then redeploy the API.

Note: Because this type of 403 error doesn't produce a distinct error message in CloudWatch Logs, it can be difficult to distinguish from other authorization failures. If you confirmed that the authorizer returns an Allow policy and you still receive a 403 error, then check the Resource ARN mismatch first.

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

You 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 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. After you flush the authorizer's cache entries, call your API again.
  Note: The cache flush can take several seconds to fully propagate across all API Gateway endpoints.
• Turn off authorization caching, redeploy your API to commit the changes, and then call your API again.
  Note: Use the Authorization Caching toggle in the API Gateway console to turn off authorization caching. The TTL field accepts only values between 1 and 3600 seconds. You can't set the TTL value to 0.
• 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

You receive this error when the resource policy explicitly denies access to the caller. The error message includes "with an explicit deny in a resource-based policy."

You also receive this error when the resource policy implicitly denies access because no statement allows the request. The error message includes "because no resource-based policy allows the execute-api:Invoke action."

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

Control and manage access to REST APIs in API Gateway