Test permissions for custom user interfaces

Most Google Cloud resources expose the testIamPermissions() method, which allows you to programmatically check whether the currently authenticated caller has been granted one or more specific IAM permissions on the resource. The testIamPermissions() method takes a resource identifier and a set of permissions as input parameters, and returns the set of permissions that the caller is allowed.

You can use the testIamPermissions() method to determine whether a user should have access to an administrative tool in a web application. For example, you can use this method to decide, based on the user's permissions, whether to display detailed information about a Google Cloud resource.

For example, to determine if the currently authenticated user has the permission to delete a project, call the projects.testIamPermissions() method by providing the project ID (such as foo-project) and the resourcemanager.projects.delete permission as input parameters. If the caller has been granted the resourcemanager.projects.delete permission, it will be listed in the response body. If the caller does not have this permission, the response body will list no permissions.

The testIamPermissions() method is intended for third-party graphical user interfaces (GUIs) that need to display Google Cloud resources based on what the authenticated user has permissions to see. For example, the Google Cloud console internally uses the testIamPermissions() method to determine what resources and functionality are visible to you after authenticating. Different users are typically granted different permissions, and the Google Cloud console hides or exposes items accordingly.

Before you begin

  • Enable the Resource Manager API.

    Enable the API

Required roles

No IAM role is required to test permissions.

How to test permissions

This example shows how to test the resourcemanager.projects.get and resourcemanager.projects.delete permissions for a Google Cloud project. To test permissions for other Google Cloud resources, use the testIamPermissions() method exposed by each resource. For example, you can test the IAM permissions for a Cloud Storage bucket.

REST

In this example, the user has an IAM role that allows them to get information about a project, but not to delete projects.

The Resource Manager API's projects.testIamPermissions method accepts a list of permissions and tests which of the permissions a principal has.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud project ID. Project IDs are alphanumeric strings, like my-project.

HTTP method and URL: 

POST https://cloudresourcemanager.googleapis.com/v1/projects/PROJECT_ID:testIamPermissions

Request JSON body: 

{
  "permissions":  [
    "resourcemanager.projects.get",
    "resourcemanager.projects.delete"
  ]
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "permissions": [
    "resourcemanager.projects.get"
  ]
}

C++

To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C++ API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment. 

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& name, std::vector<std::string> const& permissions) {
  iam::IAMClient client(iam::MakeIAMConnection());
  auto response = client.TestIamPermissions(name, permissions);
  if (!response) throw std::move(response).status();
  std::cout << "Permissions successfully tested: " << response->DebugString()
            << "\n";
}

C#

To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C# API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

IAM tests the permissions of the service account that you are using to generate credentials. 

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.CloudResourceManager.v1;
using Google.Apis.CloudResourceManager.v1.Data;

public partial class AccessManager
{
    public static IList<String> TestIamPermissions(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(CloudResourceManagerService.Scope.CloudPlatform);
        var service = new CloudResourceManagerService(
            new CloudResourceManagerService.Initializer
            {
                HttpClientInitializer = credential
            });

        TestIamPermissionsRequest requestBody = new TestIamPermissionsRequest();
        var permissions = new List<string>() { "resourcemanager.projects.get", "resourcemanager.projects.delete" };
        requestBody.Permissions = new List<string>(permissions);
        var returnedPermissions = service.Projects.TestIamPermissions(requestBody, projectId).Execute().Permissions;

        return returnedPermissions;
    }
}

Java

To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Java API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

IAM tests the permissions of the service account that you are using to generate credentials. 
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.cloudresourcemanager.v3.CloudResourceManager;
import com.google.api.services.cloudresourcemanager.v3.model.TestIamPermissionsRequest;
import com.google.api.services.cloudresourcemanager.v3.model.TestIamPermissionsResponse;
import com.google.api.services.iam.v1.IamScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class TestPermissions {

  // Tests if the caller has the listed permissions.
  public static void testPermissions(String projectId) {
    // projectId = "my-project-id"

    CloudResourceManager service = null;
    try {
      service = createCloudResourceManagerService();
    } catch (IOException | GeneralSecurityException e) {
      System.out.println("Unable to initialize service: \n" + e.toString());
      return;
    }

    List<String> permissionsList =
        Arrays.asList("resourcemanager.projects.get", "resourcemanager.projects.delete");

    TestIamPermissionsRequest requestBody =
        new TestIamPermissionsRequest().setPermissions(permissionsList);
    try {
      TestIamPermissionsResponse testIamPermissionsResponse =
          service.projects().testIamPermissions(projectId, requestBody).execute();

      System.out.println(
          "Of the permissions listed in the request, the caller has the following: "
              + testIamPermissionsResponse.getPermissions().toString());
    } catch (IOException e) {
      System.out.println("Unable to test permissions: \n" + e.toString());
    }
  }

  public static CloudResourceManager createCloudResourceManagerService()
      throws IOException, GeneralSecurityException {
    // Use the Application Default Credentials strategy for authentication. For more info, see:
    // https://cloud.google.com/docs/authentication/production#finding_credentials_automatically
    GoogleCredentials credential =
        GoogleCredentials.getApplicationDefault()
            .createScoped(Collections.singleton(IamScopes.CLOUD_PLATFORM));

    CloudResourceManager service =
        new CloudResourceManager.Builder(
                GoogleNetHttpTransport.newTrustedTransport(),
                GsonFactory.getDefaultInstance(),
                new HttpCredentialsAdapter(credential))
            .setApplicationName("service-accounts")
            .build();
    return service;
  }
}

Python

To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Python API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

IAM tests the permissions of the service account that you are using to generate credentials. 
def test_permissions(project_id: str) -> dict:
    """Tests IAM permissions of the caller"""

    credentials = service_account.Credentials.from_service_account_file(
        filename=os.environ["GOOGLE_APPLICATION_CREDENTIALS"],
        scopes=["https://www.googleapis.com/auth/cloud-platform"],
    )
    service = googleapiclient.discovery.build(
        "cloudresourcemanager", "v1", credentials=credentials
    )

    permissions = {
        "permissions": [
            "resourcemanager.projects.get",
            "resourcemanager.projects.delete",
        ]
    }

    request = service.projects().testIamPermissions(
        resource=project_id, body=permissions
    )
    returnedPermissions = request.execute()
    print(returnedPermissions)
    return returnedPermissions

What's next

Learn how to grant, change, and revoke access to principals.