Setting up authentication to PyPI repositories

This page describes how to configure authentication with an Artifact Registry PyPI repository.

You must authenticate to Artifact Registry when you use a third-party application to connect to a repository.

Integration with Google Cloud services such as Cloud Build or Google Kubernetes Engine does not require authentication. However, you should verify that the identities that act on behalf of these services have the required permissions to access repositories.

Package management is in alpha. It is only available to alpha users, and might not include all features available for container management. To apply for the alpha, complete the sign up form. For more information, see Requirements to access alpha features.

Before you begin

  1. Verify that you have enabled the Artifact Registry API and installed Cloud SDK. See Enabling and disabling service for instructions.

    gcloud command-line tool version 329.0.0 is required to run commands for PyPI repositories. You can check the version with the command:

    gcloud version
    
  2. If the target repository does not exist, create a new PyPI repository.

  3. Verify that Python 3 is installed. For installation instructions, see the Google Cloud tutorial for setting up Python.

  4. Verify that the user account or service account you are using has the required permissions to access the repository.

  5. (Optional) Configure defaults for gcloud commands.

Overview

Artifact Registry supports the following authentication methods.

Python keyring library (Recommended)
Artifact Registry provides a keyring backend to store the credentials for connecting to Artifact Registry repositories.
Password authentication
Use this option when you cannot use keyring and need an option that supports basic password authentication.

Authenticating with keyring

The Python keyring library provides applications with a way to access keyring backends, meaning operating system and third-party credential stores.

Artifact Registry provides the keyrings.google-artifactregistry-auth keyring backend to handle authentication with Artifact Registry repositories.

Credential search order

When you use the Artifact Registry keyring backend, your credentials are not stored in your Python project. Instead, Artifact Registry searches for credentials in the following order:

  1. Application Default Credentials (ADC), a strategy that looks for credentials in the following order:

    1. Credentials defined in the GOOGLE_APPLICATION_CREDENTIALS environment variable.

    2. Credentials that the default service account for Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine, or Cloud Functions provides.

  2. Credentials provided by the Cloud SDK, including user credentials from the command gcloud auth application-default login.

The GOOGLE_APPLICATION_CREDENTIALS variable makes the account for authentication explicit, which makes troubleshooting easier. If you do not use the variable, verify that any accounts that ADC might use have the required permissions. For example the default service account for Compute Engine VMs, Google Kubernetes Engine nodes, and Cloud Run revisions has read-only access to repositories. If you intend to upload from these environments using the default service account, you must modify the permissions.

Setting up keyring

To set up authentication with the Artifact Registry keyring backend:

  1. Install the keyring library.

    pip install keyring
    
  2. Install the Artifact Registry backend.

    pip install keyrings.google-artifactregistry-auth
    
  3. List backends to confirm the installation.

    keyring --list-backends
    

    The list should include

    • ChainerBackend(priority:10)
    • GooglePyPIAuth(priority: 9)
  4. Run the following command to print the repository configuration to add to your Python project.

    gcloud alpha artifacts print-settings pypi [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION]
    

    Replace the following values:

    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • LOCATION is the regional or multi-regional location for the repository.
  5. Add the following settings to the .pypirc file. The default location is for the per-user pip configuration file is:

    • Linux and MacOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
    index-servers =
        PYPI-REPO-ID
    
    [PYPI-REPO-ID]
    repository: https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/
    

    Replace the following values:

    • PYPI-REPO-ID is an ID for the repository that you can reference with tools like Twine.
    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • LOCATION is the regional or multi-regional location for the repository.
  6. Edit the pip configuration file to include the following setting in the [global] section. The default location is for the per-user pip configuration file is:

    • Linux: $HOME/.config/pip/pip.conf or $HOME/.pip/pip.conf
    • MacOS: /Library/Application Support/pip/pip.conf or $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini or %USERPROFILE%\pip\pip.ini

    To configure pip to only search a specified Artifact Registry repository, add the repository with the index-url setting [global] section:

    [global]
    index-url = https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    

    To configure pip to search pypi.org or other configured package indexes, use the extra-index-url setting in the [global] section. If your configuration includes multiple package indexes, pip searches pypi.org and any other configured package indexes and chooses the latest version of the package.

    [global]
    extra-index-url = https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    

    The /simple/ string at the end of the repository path indicates that the repository implements the Python Simple Repository API.

Your Python environment is now configured to authenticate with Artifact Registry.

Keyring authentication with user credentials

After you have set up keyring, you can use keyring with your user credentials in gcloud. Log in to Cloud SDK before connecting to a PyPI repository.

Run the following command:

gcloud auth login

Keyring authentication with service account credentials

After you have set up keyring, you can set up a service account for authentication.

  1. Create a service account, or choose an existing service account that you use for automation.
  2. Grant the appropriate Artifact Registry role to the service account to provide repository access.
  3. Use one of the following options to authenticate with your service account:

    • Application Default Credentials (Recommended)

      Assign the service account key file location to the variable GOOGLE_APPLICATION_CREDENTIALS so that the Artifact Registry credential helper can obtain your key when connecting with repositories.

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
      
    • gcloud credentials

      Before connecting to a repository, log in as the service account. Avoid this option if you are connecting to repositories from Compute Engine VMs since Artifact Registry finds the VM service account credentials before credentials in gcloud.

      gcloud auth activate-service-account --key-file=KEY-FILE
      

    Replace KEY-FILE with the path to the service account key file.

Authenticating with a service account key

Use this approach when you require authentication with a username and password.

Service account keys are long-lived credentials. Use the following guidelines to limit access to your repositories:

  • Consider using a dedicated service account for interacting with repositories.
  • Grant the minimum Artifact Registry role required by the service account. For example, assign Artifact Registry Reader to a service account that only downloads artifacts.
  • If groups in your organization require different levels of access to specific repositories, grant access at the repository level rather than the project level.
  • Follow best practices for managing credentials.

To configure authentication:

  1. Create a service account to act on behalf of your application, or choose an existing service account that you use for automation.

    You will need the location of the service account key file to set up authentication with Artifact Registry. For existing accounts, you can view keys and create new keys on the Service Accounts page.

    Go to the Service Accounts page

  2. Grant the appropriate Artifact Registry role to the service account to provide repository access.

  3. Run the following command to print the repository configuration to add to your Python project.

    gcloud alpha artifacts print-settings pypi [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION] --json-key=KEY-FILE
    

    Replace the following values:

    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • LOCATION is the regional or multi-regional location for the repository.
    • KEY-FILE is path to the service account JSON key file.
  4. Add the following settings to the .pypirc file. The default location is for the per-user pip configuration file is:

    • Linux and MacOS: $HOME/.pypirc
    • Windows: %USERPROFILE%\.pypirc
    [distutils]
    index-servers =
        PYPI-REPO-ID
    
    [PYPI-REPO-ID]
    repository: https://LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/
    username: _json_key_base64
    password: KEY
    

    Replace the following values:

    • PYPI-REPO-ID is an ID for the repository that you can reference with tools like Twine.
    • PROJECT is the project ID. If this flag is omitted, the current or default project is used.
    • REPOSITORY is the ID of the repository. If you configured a default Artifact Registry repository, it is used when this flag is omitted from the command.
    • LOCATION is the regional or multi-regional location for the repository.
    • KEY is the private key in your service account key file.
  5. Edit the pip configuration file to include the following setting in the [global] section. The default location is for the per-user pip configuration file is:

    • Linux: $HOME/.config/pip/pip.conf or $HOME/.pip/pip.conf
    • MacOS: /Library/Application Support/pip/pip.conf or $HOME/.config/pip/pip.conf
    • Windows: %APPDATA%\pip\pip.ini or %USERPROFILE%\pip\pip.ini

    To configure pip to only search a specified Artifact Registry repository, add the following setting to the [global] section:

    [global]
    index-url = https://_json_key_base64:KEY@LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    

    To configure pip to search pypi.org as well, add the following setting to the [global] section. There is no particular search order, so tools such as pip and Twine might search pypi.org first or last. We recommend that you use unique names for private packages that you store in your Artifact Registry repository.

    [global]
    extra-index-url = https://_json_key_base64:KEY@LOCATION-pypi.pkg.dev/PROJECT/REPOSITORY/simple/
    
    • KEY the private key in your service account key file.
    • The /simple/ string at the end of the repository path indicates that the repository implements the Python Simple Repository API.

What's next