IAM-based API authentication overview

This page applies to Apigee, but not to Apigee hybrid.

Apigee supports IAM-based authentication and authorization for API proxies. With this solution, access to invoke an API is based on multiple factors, including whether the request flow includes the VerifyIAM policy and whether the API consumer has the necessary Google Cloud IAM role or permissions to invoke Apigee APIs. Authorization can be granted for any Google Cloud principal, and is not limited to individual users.

Use IAM-based access control

This section describes the end-to-end process for setting up IAM-based authentication and authorization, how requests are evaluated once access is set up, and how to revoke access for API consumers who have previously had access.

Add access management

To set up access management for an API proxy:

Add the VerifyIAM policy to the Apigee API proxy or proxies as part of the request flow.
The Cloud admin for the Apigee project:
1. Grants the deploymentInvoker IAM role (or a custom role with the apigee.deployments.invoke IAM permission) to the API consumer's Google Cloud principal at the project level. This gives the API consumer access to invoke all the hosted APIs in the associated Apigee organization.
  
  or
2. Uses the SetIamPolicy action to grant the role or permission to the API consumer's Google Cloud principle at a particular deployment or iteratively at multiple deployments. Use the list operation on the deployment resource to see all of the deployments within an environment, including both API proxies and shared flows. The name of the deployment is the name of the API proxy or the shared flow.
  Note: Adding the role or permission on shared flow deployments does not create a VerifyIAM policy check on the shared flows; apply the permissions to proxies only. For proxies calling shared flows, the permissions should be applied to the proxies. With proxy chaining, grant the permission on the proxy with the policy; the permission is not required on other proxies part of the chain.
Direct the API consumer to generate an access token, which they will pass inside the Apigee API request for the permission check. The generated token must have the https://www.googleapis.com/auth/cloud-platform auth scope.

Admin Operations

This section lists actions API admins (API producers) take when managing IAM-based permissions.

Documentation for API-based operations used when managing IAM-based access are found in the organizations.environments and organizations.environments.deployments API reference documentation, and include the SetIamPolicy, GetIamPolicy, TestIamPermissions, and GetDeployment operations.

This table maps operations to required permissions:

Admin operation	Action	IAM Permission needed	IAM Resource on which the permission is needed^*
GetDeployment	Retrieve information for a deployment in an Apigee environment	apigee.deployments.get	Google Cloud project or Apigee environment
ListDeployments	List the deployments in an Apigee environment	apigee.deployments.list	Project or Apigee Environment
SetIamPolicy	Set invoke access for API consumer(s) at a particular API deployment	apigee.deployments.setIamPolicy	Google Cloud project or Apigee environment
GetIamPolicy	Fetch the set of invoke access settings for an API deployment	apigee.deployments.getIamPolicy	Google Cloud project or Apigee environment
TestIamPermissions	Check whether the user calling this API has the permission mentioned in the payload	No IAM permission needed	N/A

^* The Google Cloud project is the project used to provision Apigee. Apigee environment-level permissions are set on the environment using setIAMPolicy.

Runtime access check

When the API consumer attempts to access an API with IAM-based access control, a check is performed to see if they have the necessary access token and appropriate role or permission at either the project or deployment level. If so, they are allowed to continue with access to the proxy. Otherwise, they are blocked.

Remove access

To remove access at the project level: To remove access for an API consumer that's managed at the project level, the Cloud admin for the Apigee project revokes the deploymentInvoker IAM role (or the custom role with the apigee.deployments.invoke IAM permission) from the API consumer's Google Cloud principal for the Google Cloud project.

If access was granted for individual deployments using setIamPolicy, remove the role or permission from the deployment(s) using another setIamPolicy operation.

Characteristics and limitations of IAM-based access control

Note these characteristics and limitations when using IAM-based authentication and authorization:

Typically, policy execution with VerifyIAM takes approximately 10 milliseconds. However, some calls might experience completion latencies of approximately 50 ms. For example, in the asia-east2 region specifically, average latency can rise to 50 ms, and some calls could take around 100 ms to complete.

Please note that these latency figures are not guaranteed.
Inclusion of the VerifyIAM policy for a proxy is a verified/not verified check only; the API consumer's specific roles and permissions are not considered in later processes in the request or response flow.
Since an authorization check is performed only at the time of VerifyIAM policy execution, VerifyIAM should be the first policy in the request flow, after only traffic management policies.
If the permission validation succeeds or the API producer has marked the VerifyIAM policy to continue on error, the request flow continues to execute the other policies, if any, ultimately reaching the target server. If the permission check fails and the API producer has not marked the policy to continue on error, the user receives an error.
Adding invoke access (apigee.deployments.invoke) at the environment level does not convey the invoke access on all API deployments within the environment.
IAM conditions are not supported on the deployment resource, and can't be used to control invoke access. See Adding Apigee IAM Conditions to policies for more information.
IAM-based access control supports a maximum of 1,500 role bindings within a single policy and other limitations. See IAM quotas and limits.
IAM-based access control is subject to IAM propagation delays.
Attempting to manage other apigee.deployments operations, such as apigee.deployments.delete via the deployment-level setIAMPolicy, will not be effective but also will not return an error. Only apigee.deployements.invoke is effective.
Access on a deployment is deleted when the corresponding proxy is undeployed from the environment or deleted; access needs to be re-added on redeployment.
IAM-based authentication and authorization is not available in hybrid at this time.

Examples

This section provides examples for granting and revoking IAM-based access to APIs. These examples all assume that VerifyIAM has already been added to the appropriate API proxy.

In these examples, use either the Cloud console or gcloud (shown) to manage roles or permissions on the API consumer's Google Cloud principal. The $Project in the examples is the Google Cloud project.

Grant and revoke user access to invoke all APIs in an Apigee organization

To add access, add the deploymentInvoker role:

gcloud projects add-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

To revoke access, remove the deploymentInvoker role:

gcloud projects remove-iam-policy-binding {$Project} --member={$user} --role='roles/apigee.deploymentInvoker'

Grant and revoke user access to specific deployments within an environment

To add the invoker role for a user to a specific deployment:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
    --header 'Authorization: Bearer $TOKEN ' \
    --header 'Content-Type: application/json' \
    --data '{"policy":{"bindings":[{"members":["user:$user"],"role":"roles/apigee.deploymentInvoker"}]}}'

A success response should look something like:

  {
    "version": 1,
    "etag": "BwYT8i40Vwo=",
    "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

To confirm that the policy object that you have added is persisted correctly (optional):

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

You should see a success response like the one shown above.

For the user to verify whether they are able to access the specified deployment (whether the apigee.deployments.invoke permission is set for the specified user in a specified deployment), instruct the user to submit this request using the access token they generated previously:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

The response should include the apigee.deployments.invoke permission for the user.

To revoke access on a specific deployment, remove the deploymentInvoker role. First, get the policy object that is currently associated with the deployment:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:getIamPolicy' \
  --header 'Authorization: Bearer $TOKEN'

The success response should look something like the following. Note that you might see other bindings as well.

{
  "version": 1,
  "etag": "BwYT8i40Vwo=",
  "bindings": [
      {
        "role": "roles/apigee.deploymentInvoker",
        "members": [
          "user:$user"
        ]
      }
    ]
  }

To remove the binding:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:setIamPolicy' \
  --header 'Authorization: Bearer $TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

Note that providing an empty payload removes access for all users but is appropriate in this example because we have only one user with access. When removing user access in a circumstance where access should continue for other users, specify the users who should continue to have access, in the payload, as you would when setting initial access for those users.

To verify that the binding was removed, make sure that the apigee.deployments.invoke permission does not exist for the user on the deployment:

curl 'https://apigee.googleapis.com/v1/organizations/{org}/environments/{env}/deployments/{api}:testIamPermissions' \
  --header 'Authorization: Bearer $USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{"permissions":["apigee.deployments.invoke"]}'

This should return an empty output if no users have the permission.