This page describes how to grant Identity and Access Management (IAM) roles to principals on Secure Source Manager resources. For information on granting roles on other Google Cloud resources, see Manage access to projects, folders, and organizations.
Secure Source Manager instances and repositories have their own roles. The first time you grant instance roles in a project you must use the gcloud CLI tool or the REST API. You can grant repository roles with the gcloud CLI tool, the REST API, or through the Secure Source Manager web interface.
After you have granted a Secure Source Manager role using the gcloud CLI, web interface, or the REST API, the role is visible for your project in the Google Cloud console.
Required roles
To get the permissions that you need to update the IAM policy on an instance or repository, ask your administrator to grant you the following IAM roles:
-
Grant instance IAM roles:
Secure Source Manager Instance Owner (
roles/securesourcemanager.instanceOwner
) on the Secure Source Manager instance -
Grant repository IAM roles:
Secure Source Manager Repo Admin (
roles/securesourcemanager.repoAdmin
) on the repository
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
For information on granting Secure Source Manager roles, see Access control with IAM and Grant users instance access.
Specify principals
A principal represents an identity that can access a resource. Each principal has its own identifier. Principal identifiers have the following form:
PRINCIPAL-TYPE:ID
For example, user:my-user@example.com
. For more information on principals,
read How IAM works.
For the principal type user
, the domain name in the identifier must be a
Google Workspace domain or a Cloud Identity domain unless you are using
Workforce Identity Federation. To learn how to set up a Cloud Identity domain, see
the overview of Cloud Identity.
Workforce Identity Federation principals
If you use Workforce Identity Federation to access Secure Source Manager, then principals are represented differently. To learn more about granting access to principals that represent groups of identities, see Represent workforce pool users in IAM policies.
For example, the following command grants the user user@example.com
the
Instance Accessor role (roles/securesourcemanager.instanceAccessor
) in the
workforce pool my-pool
on the instance my-instance
in
the project my-project
in the us-central1
region:
gcloud beta source-manager instances add-iam-policy-binding my-instance \
--project=my-project \
--region=us-central1 \
--member=principal://iam.googleapis.com/locations/global/workforcePools/my-pool/subject/user@example.com \
--role=roles/securesourcemanager.instanceAccessor
You can grant users or groups within your workforce identity pool based on your Identity provider (IdP) attributes, or use Common Expression Language (CEL) to map your OIDC attributes to custom attributes to define an authorization strategy in your IAM policy. For more information about attribute mappings, read Attribute mappings.
Grant or revoke instance roles
To grant or revoke instance roles, use the read-modify-write pattern to update the resource's allow policy:
- Read the current allow policy by calling
getIamPolicy()
. - Edit the allow policy, either by using a text editor, or programmatically, to add or remove any principals or role bindings.
- Write the updated allow policy by calling
setIamPolicy()
.
gcloud
To read the current allow policy and save it to
/tmp/instances.json
, run the following command:gcloud beta source-manager instances get-iam-policy INSTANCE_ID \ --project=PROJECT_ID \ --region=REGION \ --format=json > /tmp/instance.json
Replace the following:
INSTANCE_ID
with the instance ID.PROJECT_ID
with the project ID or project number of the instance.REGION
with the region the instance is located in. See the locations documentation for available Secure Source Manager regions.
The output will include any existing bindings, or, if none exist, the
etag
value similar to the following:{ "etag": "BwUjHYKJUiQ=" }
Programmatically or using a text editor, modify the local copy of your instance's allow policy to reflect the roles that you want to grant or revoke.
To ensure that you don't overwrite other changes, don't edit or remove the allow policy's
etag
field. Theetag
field identifies the current state of the allow policy. When you set the updated allow policy, IAM compares theetag
value in the request with the existingetag
, and only writes the allow policy if the values match.To edit the roles that an allow policy grants, you need to edit the role bindings in the allow policy. Role bindings have the following format:
{ "role": "ROLE_NAME", "members": [ "PRINCIPAL_1", "PRINCIPAL_2", ... "PRINCIPAL_N" ] }
The placeholders have the following values:
ROLE_NAME
: The name of the role that you want to grant. Use the following format:roles/securesourcemanager.IDENTIFIER
PRINCIPAL_1
,PRINCIPAL_2
,...PRINCIPAL_N
: Identifiers for the principals that you want to grant the role to.
For example, the following policy grants the
instanceOwner
role touser1@gmail.com
, and theinstanceManager
role to usersuser2@gmail.com
,user3@gmail.com
, and service accountmy-other-app@appspot.gserviceaccount.com
.{ "etag": "BwUjHYKJUiQ=", "bindings": [ { "role": "roles/securesourcemanager.instanceOwner", "members": [ "user:user1@gmail.com" ] }, { "role": "roles/resourcemanager.instanceManager", "members": [ "user:user2@gmail.com", "user:user3@gmail.com", "serviceAccount:my-other-app@appspot.gserviceaccount.com" ] } ] }
After you modify the saved allow policy to grant and revoke the selected roles, update your instance allow policy by running the following command:
gcloud beta source-manager instances set-iam-policy INSTANCE_ID \ --project=PROJECT_ID \ --region=REGION \ /tmp/instance.json
Replace the following:
INSTANCE_ID
with the instance ID.PROJECT_ID
with the project ID or project number of the instance.REGION
with the region the instance is located in. See the locations documentation for available Secure Source Manager regions.
API
Run the following
instances.getIamPolicy
command to read the current policy:curl \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://securesourcemanager.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_ID:getIamPolicy > /tmp/instance.json
Replace the following:
PROJECT_ID
the project ID or project number of the instance.REGION
the region the instance is located in. See the locations documentation for available Secure Source Manager regions.INSTANCE_ID
the instance ID.
The output will include any existing bindings, or, if none exist, the
etag
value similar to the following:{ "etag": "BwUjHYKJUiQ=" }
Programmatically or using a text editor, modify the local copy of your instance's allow policy to reflect the roles that you want to grant or revoke.
To ensure that you don't overwrite other changes, don't edit or remove the allow policy's
etag
field. Theetag
field identifies the current state of the allow policy. When you set the updated allow policy, IAM compares theetag
value in the request with the existingetag
, and only writes the allow policy if the values match.To edit the roles that an allow policy grants, you need to edit the role bindings in the allow policy. Role bindings have the following format:
{ "role": "ROLE_NAME", "members": [ "PRINCIPAL_1", "PRINCIPAL_2", ... "PRINCIPAL_N" ] }
The placeholders have the following values:
ROLE_NAME
: The name of the role that you want to grant. Use the following format:roles/securesourcemanager.IDENTIFIER
PRINCIPAL_1
,PRINCIPAL_2
,...PRINCIPAL_N
: Identifiers for the principals that you want to grant the role to.
For example, the following policy grants the
instanceOwner
role touser1@gmail.com
, and theinstanceManager
role to usersuser2@gmail.com
,user3@gmail.com
, and service accountmy-other-app@appspot.gserviceaccount.com
.{ "policy": { "etag": "BwUjHYKJUiQ=", "bindings": [ { "role": "roles/securesourcemanager.instanceOwner", "members": [ "user:user1@gmail.com" ] }, { "role": "roles/resourcemanager.instanceManager", "members": [ "user:user2@gmail.com", "user:user3@gmail.com", "serviceAccount:my-other-app@appspot.gserviceaccount.com" ] } ] } }
After you modify the allow policy to grant and revoke the chosen roles, call
instances.setIamPolicy()
to make the updates.Use the following
instances.setIamPolicy
command to set the new policy on the instance.curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://securesourcemanager.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/instances/INSTANCE_ID:setIamPolicy \ -d @/tmp/instance.json
Replace the following:
PROJECT_ID
the project ID or project number of the instance.REGION
the region the instance is located in. See the locations documentation for available Secure Source Manager regions.INSTANCE_ID
the instance ID.
Grant or revoke repository roles
To grant or revoke repository roles to users and service accounts, you can assign them from the Secure Source Manager web interface, or use the Secure Source Manager API to update the repository allow policy. To grant groups repository roles, you must use the Secure Source Manager API.
Users must be granted an instance role before they can be granted repository roles. For information on granting instance roles, see Grant or revoke instance roles.
Web interface
To grant users or service accounts repository-level roles using the web interface:
- Navigate to the instance URL provided by your Google contact.
- From the My repositories page, Select your repository.
- Click the Permissions tab.
- In the People and permissions section, click Add users.
- In the Add principal field, enter the email of the user or service account you want to grant the role to.
- In the Assign a role menu, select the role to assign.
- Click Save.
To add additional roles click the edit Edit icon and add the roles using the Assign a role menu.
API
The Secure Source Manager API repositories.getIamPolicy
method
gets a repository's allow policy.
- Run the following
repositories.getIamPolicy
command to read the current policy and save it to/tmp/repository.json
:
curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://securesourcemanager.googleapis.com/v1/projects/REPOSITORY_PROJECT/locations/REGION/repositories/REPOSITORY_ID:getIamPolicy > /tmp/repository.json
Replace the following:
REPOSITORY_PROJECT
the project ID or project number of the repository.REGION
the region the repository is located in.REPOSITORY_ID
the repository ID.
The output will include any existing bindings, or, if none exist, the etag
value similar to the following:
{
"etag": "BwUjHYKJUiQ="
}
Programmatically or using a text editor, modify the local copy of your repository's allow policy saved in
/tmp/repository.json
to reflect the roles that you want to grant or revoke.To ensure that you don't overwrite other changes, don't edit or remove the allow policy's
etag
field. Theetag
field identifies the current state of the allow policy. When you set the updated allow policy, IAM compares theetag
value in the request with the existingetag
, and only writes the allow policy if the values match.To edit the roles that an allow policy grants, you need to edit the role bindings in the allow policy. Role bindings have the following format:
{ "role": "ROLE_NAME", "members": [ "PRINCIPAL_1", "PRINCIPAL_2", ... "PRINCIPAL_N" ] }
The placeholders have the following values:
ROLE_NAME
: The name of the role that you want to grant. Use the following format:roles/securesourcemanager.<var>IDENTIFIER</var>
PRINCIPAL_1
,PRINCIPAL_2
,...PRINCIPAL_N
: Identifiers for the principals that you want to grant the role to.
The following example grants the
repoAdmin
role to the useremail1@gmail.com
, and therepoWriter
role to usersemail2@gmail.com
,group1@gmail.com
, and service accountmy-other-app@appspot.gserviceaccount.com
.{ "policy": { "etag": "BwUjHYKJUiQ=", "bindings": [ { "role": "roles/securesourcemanager.repoAdmin", "members": [ "user:email1@gmail.com" ] }, { "role": "roles/resourcemanager.repoWriter", "members": [ "user:email2@gmail.com", "group:group1@gmail.com", "serviceAccount:my-other-app@appspot.gserviceaccount.com" ] } ] } }
Save the edited
/tmp/repository.json
file.Set the new policy with the
setIamPolicy
command:curl \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ https://securesourcemanager.googleapis.com/v1/projects/REPOSITORY_PROJECT/locations/REGION/repositories/REPOSITORY_ID:setIamPolicy \ -d @/tmp/repository.json
Replace the following:
REPOSITORY_PROJECT
the project ID or project number of the repository.REGION
the region the repository is located in. See the locations documentation for available Secure Source Manager regions.REPOSITORY_ID
the repository ID.
What's next
- Learn more about access control with IAM in Secure Source Manager.