Access control with IAM

This page describes access control with Identity and Access Management (IAM) in Artifact Registry.

Default permissions for Artifact Registry minimize setup effort when implementing a CI/CD pipeline. You can also integrate Artifact Registry with third-party CI/CD tools and configure the permissions and authentication required to access repositories.

If you use Artifact Analysis to work with container metadata, such as vulnerabilities found in images, see the Artifact Analysis documentation for information about granting access to view or manage metadata.

Before you begin

  1. Enable Artifact Registry, including enabling the API and installing the Google Cloud CLI.
  2. If you want to apply repository-specific permissions, then create an Artifact Registry repository for your packages.

Overview

IAM permissions and roles determine your ability to create, view, edit, or delete data in an Artifact Registry repository.

A role is a collection of permissions. You can't grant a principal permissions directly; instead, you grant them a role. When you grant a role to a principal, you grant them all the permissions that the role contains. You can grant multiple roles to the same principal.

Google Cloud default permissions

By default, the following permissions apply to Google Cloud CI/CD services in the same project as Artifact Registry:

  • Cloud Build permissions include permissions to upload and download artifacts.

If all your services are in the same Google Cloud project and the default permissions meet your needs, you don't need to configure permissions.

You must configure Artifact Registry permissions for these services if:

  • You want to use these services to access Artifact Registry in another project. In the project with Artifact Registry, grant the workload identity pool or service account for each service the required role. If connecting to Cloud Run, grant the Cloud Run Service Agent the required role.
  • You're using a GKE version that does not have built-in support for pulling images from Artifact Registry. See the GKE section for configuration instructions.
  • You want the default service account to have read and write access to repositories. See the following information for details:
  • You're using a user-provided service account for your runtime environments instead of the default service account. In the project with Artifact Registry, grant your service account the required role.

Third-party integration

For third-party clients, you must configure both permissions and authentication.

Traditionally, applications running outside Google Cloud use service account keys to access Google Cloud resources. However, service account keys are powerful credentials, and can present a security risk if they are not managed correctly.

Workload Identity Federation lets you use Identity and Access Management to grant external identities IAM roles, including the ability to impersonate service accounts. This approach eliminates the maintenance and security burden associated with service account keys.

Use Workload Identity Federation:

  1. Create a Workload Identity Federation pool.
  2. Create a Workload Identity Federation provider.
  3. Grant the appropriate Artifact Registry role to the workload identity pool to allow repository access. For more information, see Allow your external workload to access Google Cloud resources.
  4. If you need to access Artifact Registry for longer periods of time, then configure the OIDC token expiration time to a longer period in your credential configuration.

  5. Configure your third-party client to authenticate with Artifact Registry.

Use a service account:

  1. Create a service account to act on behalf of your application, or choose an existing service account that use for your CI/CD automation.
  2. Grant the appropriate Artifact Registry role to the service account to provide repository access.

  3. Configure your third-party client to authenticate with Artifact Registry.

GitLab on Google Cloud

The GitLab on Google Cloud integration uses Workload Identity Federation for authorization and authentication for GitLab workloads on Google Cloud without the need for service accounts or service account keys. For more information on how Workload Identity Federation is used in this partnership, see Google Cloud Workload Identity Federation and IAM policies.

To set up Workload Identity Federation and the necessary IAM roles for the GitLab on Google Cloud, see the GitLab tutorial Google Cloud Workload Identity Federation and IAM policies.

To connect your Artifact Registry repository, follow the GitLab tutorial Google Artifact Registry.

Roles and permissions

Every Artifact Registry API method requires that the principal making the request has the required permissions to use the resource. Permissions are given to principals by setting policies that grant the principal a predefined role on the resource.

You can grant roles on the Google Cloud project or the Artifact Registry repository.

Predefined Artifact Registry roles

IAM provides predefined roles that grant access to specific Google Cloud resources.

Use the following predefined roles for repositories on the pkg.dev domain:
Role Description
Artifact Registry Reader
(roles/artifactregistry.reader)		 View and get artifacts, view repository metadata.
Artifact Registry Writer
(roles/artifactregistry.writer)		 Read and write artifacts.
Artifact Registry Repository Administrator
(roles/artifactregistry.repoAdmin)		 Read, write, and delete artifacts.
Artifact Registry Administrator
(roles/artifactregistry.admin)		 Create and manage repositories and artifacts.
The following additional predefined roles contain permissions required to migrate from Container Registry to Artifact Registry.

Role Description
Container Registry -> Artifact Registry Migration Admin (roles/artifactregistry.containerRegistryMigrationAdmin) Includes all permissions required to run migration tooling
Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) Read and write artifacts. Create gcr.io repositories when you push to gcr.io URLs.
Artifact Registry Create-on-push Repository Administrator (roles/artifactregistry.createOnPushRepoAdmin) Read, write, and delete artifacts. Create gcr.io repositories.
For a full list of the individual permissions in each role, refer to Artifact Registry roles. You can also use the gcloud iam roles describe command to view a list of permissions in each role.

Basic IAM roles

Basic roles are highly permissive roles that existed prior to the introduction of IAM. You shouldn't grant basic roles in a production environment, but you can grant them in a development or test environment.

Use predefined roles for repository access whenever possible so that users and service accounts only have the permissions that are required.

For more information on basic roles, see IAM basic and predefined roles reference.

Granting roles

Grant roles at the project level if the same roles apply to all repositories in the project. If some accounts require different levels of access, grant roles at the repository level.

If you're granting roles on a virtual repository, those roles apply to all upstream repositories available through the virtual repository, regardless of individual repository permissions.

If you're granting roles using the gcloud command, you can specify a single role binding for a principal or you can make large-scale policy changes by getting a resource's allow policy, modifying it, and then setting the modified allow policy. For more information, see Grant or revoke multiple roles programmatically.

Granting project-wide roles

Grant a role at the project level if the same permissions apply to all repositories in the project.

To add a user or service account to a project and grant them an Artifact Registry role:

Console

  1. Open the IAM page in the Google Cloud console.

    Open the IAM page

  2. Click Select a project, choose the project where Artifact Registry is running, and click Open.

  3. Click Add.

  4. Enter an email address. You can add individuals, service accounts, or Google Groups as principals.

  5. Select a role for the principal. In accordance with the security principle of least privilege, consider granting the least amount of privilege needed to access the required Artifact Registry resources. For information on Artifact Registry predefined roles and permissions, see Predefined Artifact Registry roles.

  6. Click Save.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. To grant a role to a single principal, run the following command:

    gcloud projects add-iam-policy-binding PROJECT \
   --member=PRINCIPAL \
   --role=ROLE

    where

    • PROJECT is the ID of the project where Artifact Registry is running.

    • PRINCIPAL is the principal to add the binding for. Use the form user|group|serviceAccount:email or domain:domain.

      Examples: user:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, or domain:example.domain.com.

    • ROLE is the role that you want to grant.

    For more information, see the add-iam-policy-binding documentation.

    To grant roles using a policy file, see Grant or revoke multiple roles programmatically

Granting repository-specific roles

Grant repository-level roles when you want users or service accounts to have different levels of access for each repository in your project.

Console

To grant access to a specific repository:

  1. Open the Repositories page in the Google Cloud console.

    Open the Repositories page

  2. Select the appropriate repository.

  3. If the info panel is not displayed, click Show Info Panel in the menu bar.

  4. On the Permissions tab, click Add Principal.

  5. Enter an email address. You can add individuals, service accounts, or Google Groups as principals.

  6. Select a role for the principal. In accordance with the security principle of least privilege, consider granting the least amount of privilege needed to access the required Artifact Registry resources. For information on Artifact Registry predefined roles and permissions, see Predefined Artifact Registry roles.

  7. Click Save.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. You can set an IAM set of individual policy bindings or use a policy file.

    To grant a role to a single principal, run the following command:

    gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
   --location=LOCATION \
   --member=PRINCIPAL \
   --role=ROLE

    where

    • REPOSITORY is the ID of the repository.

    • PRINCIPAL is the principal to add the binding for. Use the form user|group|serviceAccount:email or domain:domain.

      Examples: user:test-user@gmail.com, group:admins@example.com, serviceAccount:test123@example.domain.com, or domain:example.domain.com.

    • ROLE is the role that you want to grant.

    • LOCATION is the regional or multi-regional location of the repository.

    For example, to add an IAM policy binding for the role roles/artifactregistry.writer for the user write@gmail.com with the repository my-repo in the location --us-west1, run:

    gcloud artifacts repositories add-iam-policy-binding my-repo \
--location=us-west1 --member=user:write@gmail.com --role=roles/artifactregistry.writer

    To grant roles using a policy file, use the procedure described in Grant or revoke multiple roles programmatically with the gcloud artifacts repositories get-iam-policy and gcloud artifacts repositories set-iam-policy commands.

Terraform

Use the google_artifact_registry_repository_iam resource to configure an IAM policy. The following example defines a service account with the resource name repo-account and grants it read access to a repository with the resource name my-repo.

If you're new to using Terraform for Google Cloud, see the Get Started - Google Cloud page on the HashiCorp website.

provider "google" {
    project = "PROJECT-ID"
}

resource "google_artifact_registry_repository" "my-repo"     {
  provider = google-beta

  location = "LOCATION"
  repository_id = "REPOSITORY"
  description = "DESCRIPTION"
  format = "FORMAT"
}

resource "google_service_account" "repo-account" {
  provider = google-beta

  account_id   = "ACCOUNT-ID"
  display_name = "Repository Service Account"
}

resource "google_artifact_registry_repository_iam_member" "repo-iam" {
  provider = google-beta

  location = google_artifact_registry_repository.my-repo.location
  repository = google_artifact_registry_repository.my-repo.name
  role   = "roles/artifactregistry.reader"
  member = "serviceAccount:${google_service_account.repo-account.email}"
}

ACCOUNT-ID is the ID of the service account. This is the the part of the service account email field before the @ symbol.

For additional examples, see the documentation for the google_artifact_registry_repository_iam resource.

Configuring public access to a repository

If you have artifacts that you want to make available to anyone on the internet without authentication, store them in a repository that you make public.

To configure a repository for public read-only access, grant the Artifact Registry Reader role to the principal allUsers. We also recommend capping user request quotas so that a single user can't use up your project's overall quota.

Console

  1. Open the