Grant and revoke IAM roles

This page describes how to grant Identity and Access Management (IAM) roles 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. The first time you grant repository roles in a project you must use the gcloud CLI tool, the REST API, or 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 available 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:

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.

Grant or revoke instance roles

To grant or revoke instance roles, use the read-modify-write pattern to update the resource's allow policy:

  1. Read the current allow policy by calling getIamPolicy().
  2. Edit the allow policy, either by using a text editor, or programmatically, to add or remove any principals or role bindings.
  3. Write the updated allow policy by calling setIamPolicy().

gcloud

  1. 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="
    }
    
  2. 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. The etag field identifies the current state of the allow policy. When you set the updated allow policy, IAM compares the etag value in the request with the existing etag, 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.

    Principal identifiers usually have the following form: PRINCIPAL-TYPE:ID. For example, user:my-user@example.com. For a full list of the values that PRINCIPAL can have, see the Policy Binding reference.

    For the principal type user, the domain name in the identifier must be a Google Workspace domain or a Cloud Identity domain. To learn how to set up a Cloud Identity domain, see the overview of Cloud Identity.

    For example, the following policy grants the instanceOwner role to user1@gmail.com, and the instanceManager role to users user2@gmail.com,user3@gmail.com, and service account my-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"
            ]
        }
        ]
    }
    
  3. After you modify the saved allow policy to grant and revoke the desired 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

  1. 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="
    }
    
  2. 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. The etag field identifies the current state of the allow policy. When you set the updated allow policy, IAM compares the etag value in the request with the existing etag, 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.

    Principal identifiers usually have the following form: PRINCIPAL-TYPE:ID. For example, user:my-user@example.com. For a full list of the values that PRINCIPAL can have, see the Policy Binding reference.

    For the principal type user, the domain name in the identifier must be a Google Workspace domain or a Cloud Identity domain. To learn how to set up a Cloud Identity domain, see the overview of Cloud Identity.

    For example, the following policy grants the instanceOwner role to user1@gmail.com, and the instanceManager role to users user2@gmail.com,user3@gmail.com, and service account my-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"
            ]
        }
        ]
    }
    }
    
  3. After you modify the allow policy to grant and revoke the desired 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:

  1. Navigate to the instance URL provided by your Google contact.
  2. From the My repositories page, Select your repository.
  3. Click the Permissions tab.
  4. In the People and permissions section, click Add users.
  5. In the Add principal field, enter the email of the user or service account you want to grant the role to.
  6. In the Assign a role menu, select the role to assign.
  7. 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.

  1. 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="
}
  1. 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. The etag field identifies the current state of the allow policy. When you set the updated allow policy, IAM compares the etag value in the request with the existing etag, 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.

    Principal identifiers usually have the following form: PRINCIPAL-TYPE:ID. For example, user:my-user@example.com. For a full list of the values that PRINCIPAL can have, see the Policy Binding reference.

    For the principal type user, the domain name in the identifier must be a Google Workspace domain or a Cloud Identity domain. To learn how to set up a Cloud Identity domain, see the overview of Cloud Identity.

    The following example grants the repoAdmin role to the user email1@gmail.com, and the repoWriter role to users email2@gmail.com, group1@gmail.com, and service account my-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"
            ]
        }
        ]
    }
    }
    
  2. Save the edited /tmp/repository.json file.

  3. 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