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.
Set up authentication.
Select the tab for how you plan to use the samples on this page:
C++
To use the C++ samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
C#
To use the .NET samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
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.
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 Before you begin.
C#
To authenticate to Resource Manager, set up Application Default Credentials. For more information, see Before you begin.
To learn how to install and use the client library for Resource Manager, see Resource Manager client libraries.
IAM tests the permissions of the service account that you are using to generate credentials.
Java
To authenticate to Resource Manager, set up Application Default Credentials. For more information, see Before you begin.
To learn how to install and use the client library for Resource Manager, see Resource Manager client libraries.
IAM tests the permissions of the service account that you are using to generate credentials.
Python
To authenticate to Resource Manager, set up Application Default Credentials. For more information, see Before you begin.
To learn how to install and use the client library for Resource Manager, see Resource Manager client libraries.
IAM tests the permissions of the service account that you are using to generate credentials.
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, likemy-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" ] }
What's next
Learn how to grant, change, and revoke access to principals.