Configurer l'authentification auprès d'Artifact Registry pour les dépôts de paquets Python

Vous devez vous authentifier auprès d'Artifact Registry lorsque vous utilisez une application tierce pour vous connecter à un dépôt.

Vous n'avez pas besoin de configurer l'authentification pour les environnements d'exécution Cloud Build ou Google Cloudtels que Google Kubernetes Engine et Cloud Run, mais vous devez vérifier que les autorisations requises sont configurées.

Artifact Registry est compatible avec les méthodes d'authentification suivantes pour les dépôts de packages Python :

  • Jetons d'accès : utilisez des jetons d'accès dans les pipelines d'automatisation, CI/CD, les compilations de conteneurs ou les environnements où l'installation de la bibliothèque de trousseau de clés n'est pas prise en charge.
  • Bibliothèque Python Keyring (recommandée pour le développement local) : utilisez cette option sur les postes de travail des développeurs pour gérer automatiquement l'actualisation des identifiants.
  • Authentification par mot de passe : utilisez cette option lorsqu'une application n'est pas compatible avec les identifiants par défaut de l'application, mais qu'elle prend en charge l'authentification avec un nom d'utilisateur et un mot de passe.

Avant de commencer

  1. Si le dépôt cible n'existe pas, créez-en un.
  2. Vérifiez que Python 3 est installé. Pour obtenir des instructions d'installation, consultez leGoogle Cloud tutoriel de configuration de Python.
  3. Vérifiez que le compte utilisateur ou le compte de service que vous utilisez dispose des autorisations requises pour accéder au dépôt.

  4. Installez la Google Cloud CLI. Une fois que la Google Cloud CLI est installée, initialisez-la en exécutant la commande suivante : 

    gcloud init

    Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  5. (Facultatif) Configurez des valeurs par défaut pour les commandes gcloud CLI.

Générer des jetons pour l'authentification

Pour authentifier votre package dans Artifact Registry, vous devez d'abord générer un jeton d'authentification. Vous pouvez ensuite utiliser ce jeton lorsque vous envoyez des requêtes depuis votre package vers Artifact Registry.

Vous pouvez générer un jeton d'accès oauth2 à l'aide de Google Cloud ou d'un jeton oauth2l en dehors de Google Cloud.

Les jetons d'accès sont valides pendant 60 minutes. Générez un jeton d'accès peu de temps avant d'exécuter des commandes qui interagissent avec les dépôts. Si votre jeton d'accès a expiré, vous devez en générer un nouveau.

Générer un jeton à l'aide de gcloud

Pour générer un jeton d'accès oauth2 à l'aide de Google Cloud, exécutez la commande suivante :

export ACCESS_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

Vous pouvez désormais faire référence à ACCESS_TOKEN lorsque vous envoyez des requêtes depuis votre package Python vers Artifact Registry.

Générer un jeton sans utiliser gcloud

Pour générer un jeton d'accès à l'aide de la CLI oauth2l uniquement, procédez comme suit :

  1. Installez la dernière version de oauth2l en exécutant la commande suivante :

    go install github.com/google/oauth2l@latest

  2. Exécutez la commande suivante :

    export ACCESS_TOKEN="oauth2l fetch --scope cloud-platform"

    Google Cloud génère un jeton de hachage SHA256 et le stocke dans la variable ACCESS_TOKEN. Vous pouvez désormais faire référence à ACCESS_TOKEN lorsque vous envoyez des requêtes depuis votre package Python vers Artifact Registry.

S'authentifier avec pip

Après avoir exporté ACCESS_TOKEN, vous pouvez le transmettre à pip pour installer des packages :

pip install PACKAGE --index-url https://$ACCESS_TOKEN@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/

S'authentifier avec un trousseau de clés

La bibliothèque Python keyring permet aux applications d'accéder aux backends keyring, c'est-à-dire aux magasins d'identifiants du système d'exploitation et tiers. Artifact Registry fournit le backend de trousseau de clés keyrings.google-artifactregistry-auth pour gérer l'authentification auprès des dépôts Artifact Registry.

Les instructions de cette section décrivent la configuration de pip comme seul index de packages dans lequel pip recherche des packages. Nous vous recommandons d'utiliser des dépôts virtuels pour rechercher des packages dans vos packages privés dans Artifact Registry et des packages publics depuis PyPI, au lieu de configurer plusieurs index de packages dans le fichier de configuration pip. L'outil pip ne recherche pas les index de packages dans un ordre particulier. Vos utilisateurs peuvent donc télécharger ou installer par erreur un package public portant le même nom que l'un de vos packages privés. Les dépôts virtuels vous permettent de configurer des priorités pour les sources en amont afin d'atténuer ce risque de confusion des dépendances.

Ordre de recherche des identifiants

Lorsque vous utilisez le backend de trousseau de clés Artifact Registry, vos identifiants ne sont pas stockés dans votre projet Python. Artifact Registry recherche plutôt les identifiants dans l'ordre suivant :

  1. Identifiants par défaut de l'application (ADC), stratégie qui recherche les identifiants dans l'ordre suivant :

    1. Identifiants définis dans la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

    2. Identifiants fournis par le compte de service par défaut pour Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine ou Cloud Run Functions.

  2. Identifiants fournis par Google Cloud CLI, y compris les identifiants utilisateur de la commande gcloud auth application-default login.

La variable GOOGLE_APPLICATION_CREDENTIALS rend le compte d'authentification explicite, ce qui facilite le dépannage. Si vous n'utilisez pas la variable, vérifiez que tous les comptes que les ADC peuvent utiliser disposent des autorisations requises. Par exemple, le compte de service par défaut pour les VM Compute Engine, les nœuds Google Kubernetes Engine et les révisions Cloud Run dispose d'un accès en lecture seule aux dépôts. Si vous prévoyez d'importer des données à partir de ces environnements à l'aide du compte de service par défaut, vous devez modifier les autorisations.

Configurer le trousseau de clés

Pour configurer l'authentification avec le backend du trousseau de clés Artifact Registry :

  1. Installez la bibliothèque de trousseau de clés.

    pip install keyring

  2. Installez le backend Artifact Registry.

    pip install keyrings.google-artifactregistry-auth

  3. Listez les backends pour confirmer l'installation.

    keyring --list-backends

    La liste doit inclure

    • ChainerBackend(priority:10)
    • GooglePythonAuth(priority: 9)

  4. Exécutez la commande suivante pour imprimer la configuration du dépôt à ajouter à votre projet Python.

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

    Remplacez les valeurs suivantes :

    • PROJECT est l'ID de projet. Si cette option est ignorée, le projet en cours ou par défaut est utilisé.
    • REPOSITORY est l'ID du dépôt. Si vous avez configuré un dépôt Artifact Registry par défaut, il est utilisé lorsque cette option est omise dans la commande.
    • LOCATION est l'emplacement régional ou multirégional du dépôt.

  5. Ajoutez les paramètres suivants au fichier .pypirc. L'emplacement par défaut est le suivant :

    • Linux et macOS : $HOME/.pypirc
    • Windows : %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/

    Remplacez les valeurs suivantes :

    • PYTHON-REPO-ID est un ID pour le dépôt que vous pouvez référencer avec des outils tels que Twine.
    • PROJECT est l'ID de projet. Si cette option est ignorée, le projet en cours ou par défaut est utilisé.
    • REPOSITORY est l'ID du dépôt. Si vous avez configuré un dépôt Artifact Registry par défaut, il est utilisé lorsque cette option est omise dans la commande.
    • LOCATION est l'emplacement régional ou multirégional du dépôt.

  6. Ajoutez votre dépôt au fichier de configuration pip. L'emplacement du fichier dépend de si vous souhaitez mettre à jour le fichier par utilisateur ou le fichier spécifique à un environnement virtuel que vous utilisez.

    Pour le fichier associé à l'utilisateur de votre système d'exploitation :

    • Unix : $HOME/.config/pip/pip.conf ou $HOME/.pip/pip.conf
    • macOS : /Library/Application Support/pip/pip.conf ou $HOME/.config/pip/pip.conf
    • Windows : %APPDATA%\pip\pip.ini ou %USERPROFILE%\pip\pip.ini

    Pour les environnements virtuels :

    • Unix et macOS : $VIRTUAL_ENV/pip.conf
    • Windows : %VIRTUAL_ENV%\pip.ini

    Pour configurer pip afin qu'il ne recherche que dans votre dépôt, utilisez le paramètre index-url et assurez-vous qu'aucun autre index de package n'est configuré avec le paramètre extra-index-url.

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

    La chaîne /simple/ à la fin du chemin d'accès au dépôt indique que le dépôt implémente l'API Python Simple Repository.

Votre environnement Python est maintenant configuré pour l'authentification auprès d'Artifact Registry.

Authentification du trousseau de clés avec les identifiants utilisateur

Une fois que vous avez configuré le trousseau de clés, vous pouvez l'utiliser avec vos identifiants utilisateur dans gcloud CLI. Connectez-vous à Google Cloud CLI avant de vous connecter à un dépôt de packages Python.

Exécutez la commande suivante :

gcloud auth login

Authentification du trousseau de clés avec les identifiants du compte de service

Une fois que vous avez configuré le trousseau de clés, vous pouvez configurer un compte de service pour l'authentification.

  1. Créez un compte de service ou choisissez-en un existant que vous utilisez pour l'automatisation.
  2. Attribuez le rôle Artifact Registry spécifique au compte de service pour lui permettre d'accéder au dépôt.

  3. Utilisez l'une des options suivantes pour vous authentifier avec votre compte de service :

    • Identifiants par défaut de l'application (recommandé)

      Attribuez l'emplacement du fichier de clé du compte de service à la variable GOOGLE_APPLICATION_CREDENTIALS afin que l'assistant d'identification Artifact Registry puisse obtenir votre clé lors de la connexion aux dépôts.

      export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    • Identifiants gcloud CLI

      Avant de vous connecter à un dépôt, connectez-vous en tant que compte de service. Évitez cette option si vous vous connectez à des dépôts depuis des VM Compute Engine, car Artifact Registry trouve les identifiants du compte de service de la VM avant les identifiants de gcloud CLI.

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

    Remplacez KEY-FILE par le chemin d'accès au fichier de clé du compte de service.

Configurer l'authentification par mot de passe avec des clés de compte de service

Utilisez cette approche lorsque vous avez besoin d'une authentification avec un nom d'utilisateur et un mot de passe.

Les clés de compte de service sont des identifiants de longue durée. Suivez les instructions ci-dessous pour limiter l'accès à vos dépôts :

  • Envisagez d'utiliser un compte de service dédié pour interagir avec les dépôts.
  • Attribuez le rôle Artifact Registry minimal requis par le compte de service. Par exemple, attribuez le lecteur Artifact Registry à un compte de service qui télécharge les artefacts uniquement.
  • Si les groupes de votre organisation nécessitent différents niveaux d'accès à des dépôts spécifiques, accordez l'accès au niveau du dépôt plutôt qu'au niveau du projet.
  • Suivez les bonnes pratiques de gestion des identifiants.

Pour configurer l'authentification :

  1. Créez un compte de service pour agir au nom de votre application ou sélectionnez un compte de service existant que vous utilisez pour l'automatisation.

    Vous aurez besoin de l'emplacement du fichier de clé de compte de service pour configurer l'authentification avec Artifact Registry. Pour les comptes existants, vous pouvez afficher les clés et en créer sur la page "Comptes de service".

    Accéder à la page "Comptes de service"

  2. Attribuez le rôle Artifact Registry approprié au compte de service pour lui donner accès au dépôt.

  3. Exécutez la commande suivante pour imprimer la configuration du dépôt à ajouter à votre projet Python.

    gcloud artifacts print-settings python --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --json-key=KEY-FILE

    Remplacez les valeurs suivantes :

    • PROJECT est l'ID de projet. Si cette option est ignorée, le projet en cours ou par défaut est utilisé.
    • REPOSITORY est l'ID du dépôt. Si vous avez configuré un dépôt Artifact Registry par défaut, il est utilisé lorsque cette option est omise dans la commande.
    • LOCATION est l'emplacement régional ou multirégional du dépôt.
    • KEY-FILE est le chemin d'accès au fichier de clé JSON du compte de service.

  4. Ajoutez les paramètres suivants au fichier .pypirc. L'emplacement par défaut du fichier de configuration pip par utilisateur est le suivant :

    • Linux et macOS : $HOME/.pypirc
    • Windows : %USERPROFILE%\.pypirc
    [distutils]
index-servers =
    PYTHON-REPO-ID

[PYTHON-REPO-ID]
repository = https://LOCATION-python.pkg.dev/PROJECT/REPOSITORY/
username: _json_key_base64
password: KEY

    Remplacez les valeurs suivantes :

    • PYTHON-REPO-ID est un ID pour le dépôt que vous pouvez référencer avec des outils tels que Twine.
    • PROJECT est l'ID de projet. Si cette option est ignorée, le projet en cours ou par défaut est utilisé.
    • REPOSITORY est l'ID du dépôt. Si vous avez configuré un dépôt Artifact Registry par défaut, il est utilisé lorsque cette option est omise dans la commande.
    • LOCATION est l'emplacement régional ou multirégional du dépôt.
    • KEY est la clé encodée en base64 dans le fichier de clé de votre compte de service.

  5. Ajoutez votre dépôt au fichier de configuration pip. L'emplacement du fichier de configuration pip dépend de l'emplacement du fichier que vous souhaitez mettre à jour (fichier par utilisateur ou fichier spécifique à un environnement virtuel que vous utilisez).

    Pour le fichier associé à l'utilisateur de votre système d'exploitation :

    • Unix : $HOME/.config/pip/pip.conf ou $HOME/.pip/pip.conf
    • macOS : /Library/Application Support/pip/pip.conf ou $HOME/.config/pip/pip.conf
    • Windows : %APPDATA%\pip\pip.ini ou %USERPROFILE%\pip\pip.ini

    Pour les environnements virtuels :

    • Unix et macOS : $VIRTUAL_ENV/pip.conf
    • Windows : %VIRTUAL_ENV%\pip.ini

    Ajoutez la ligne suivante au fichier de configuration pip :

    [global]
index-url = https://_json_key_base64:KEY@LOCATION-python.pkg.dev/PROJECT/REPOSITORY/simple/
    • KEY : clé privée dans le fichier de clé de votre compte de service.
    • La chaîne /simple/ à la fin du chemin d'accès au dépôt indique que le dépôt implémente l'API Python Simple Repository.

Étapes suivantes