Configura la autenticación en Artifact Registry para npm

Debes autenticarte en Artifact Registry cuando uses una aplicación de terceros para conectarte a un repositorio.

No necesitas configurar la autenticación para Cloud Build ni Google Cloud entornos de ejecución, como Google Kubernetes Engine y Cloud Run, pero debes verificar que los permisos necesarios estén configurados.

Antes de comenzar

  1. Install the Google Cloud CLI, then initialize it by running the following command:

    gcloud init
  2. (Opcional) Configura valores predeterminados para los comandos de gcloud CLI.
  3. Si te conectas a repositorios desde Windows, instala PowerShell.
  4. Crea una cuenta de servicio que actúe en nombre de tu aplicación.
  5. Si eres nuevo en la Administración de socios de red, lee la descripción general con el fin de obtener información sobre los paquetes con alcance y el archivo de configuración para configuración de la autenticación.

Descripción general

Artifact Registry admite los siguientes métodos de autenticación.

Cómo usar un auxiliar de credenciales
Esta opción proporciona la mayor flexibilidad. Cuando incluyes el asistente en tu configuración de npm, Artifact Registry busca credenciales de la cuenta de servicio en el entorno.
Especifica una clave de cuenta de servicio como una credencial
Usa esta opción cuando una aplicación no sea compatible con las credenciales predeterminadas de la aplicación, pero admita la autenticación mediante un nombre de usuario y una contraseña.

Autentica con un auxiliar de credenciales

google-artifactregistry-auth es una biblioteca cliente que obtiene credenciales para los repositorios de Artifact Registry.

Artifact Registry busca las credenciales en el siguiente orden:

  1. Las credenciales predeterminadas de la aplicación (ADC), que es una estrategia que busca credenciales en el siguiente orden:

    1. Credenciales definidas en la variable de entorno GOOGLE_APPLICATION_CREDENTIALS

    2. Credenciales que proporciona la cuenta de servicio predeterminada para Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Functions

  2. Credenciales que proporciona Google Cloud CLI, incluidas las credenciales de usuario del comando gcloud auth application-default login

La variable GOOGLE_APPLICATION_CREDENTIALS hace que la cuenta para la autenticación sea explícita, lo que facilita la solución de problemas. Si no usas la variable, verifica que las cuentas que pueda usar ADC tengan los permisos necesarios. Por ejemplo, la cuenta de servicio predeterminada para las VMs de Compute Engine, los nodos de Google Kubernetes Engine y las revisiones de Cloud Run tiene acceso de solo lectura a los repositorios. Si quieres subir desde estos entornos con la cuenta de servicio predeterminada, debes modificar los permisos.

Para crear una cuenta de servicio y establecer la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, haz lo siguiente:

  1. Crea una cuenta de servicio que actúe en nombre de tu aplicación o elige una cuenta de servicio existente que se use para la automatización de CI/CD.

  2. Otorga el rol específico de Artifact Registry a la cuenta de servicio para proporcionar acceso al repositorio.

  3. Asigna la ubicación del archivo de claves de la cuenta de servicio a la variable GOOGLE_APPLICATION_CREDENTIALS para que el auxiliar de credenciales de Artifact Registry pueda obtener tu clave cuando se conecta con repositorios.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
    

    En el ejemplo anterior, KEY-FILE es la ruta de acceso al archivo de claves de la cuenta de servicio.

Para configurar la autenticación, sigue estos pasos:

  1. Ejecuta el siguiente comando para imprimir la configuración del repositorio:

    gcloud artifacts print-settings npm [--project=PROJECT] \
        [--repository=REPOSITORY] \
        [--location=LOCATION] \
        --scope=@SCOPE-NAME \
    

    Dónde

    • PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto actual o predeterminado.
    • REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
    • LOCATION es la ubicación regional o multirregional del repositorio.
    • SCOPE-NAME es el nombre del permiso de la Administración de socios de red que se debe asociar con el repositorio.

      El uso de permisos garantiza que siempre publiques e instales paquetes desde el repositorio correcto.

      Los paquetes sin permisos están asociados con tu registro predeterminado de la Administración de socios de red, por lo general, el registro público de la Administración de socios de red. Si no especificas un permiso, la configuración que se muestra establece tu repositorio de Artifact Registry como el registro predeterminado. Esto puede causar problemas si tus proyectos de Node.js deben instalar paquetes del registro público de la Administración de socios de red y de tu repositorio de Artifact Registry.

  2. Agrega los parámetros de configuración que se muestran al archivo de configuración .npmrc en tus proyectos de Node.js. Por lo general, este archivo se encuentra en el mismo directorio que package.json.

    Asegúrate de incluir esta configuración en los proyectos de Node.js para los paquetes que publicas, así como en los proyectos que instalarán dependencias desde tu repositorio de npm.

  3. Si tienes otros repositorios de Node.js para conectarte, repite los pasos anteriores para obtener la configuración y agrégala a los archivos .npmrc correspondientes.

  4. Cuando tengas todo listo para conectar un repositorio, obtén un token de acceso para la autenticación.

Cada repositorio de paquetes de Node.js de Artifact Registry está asociado con un extremo de registro https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY.

Si no especificaste un permiso con el comando print-settings, puedes ejecutar el siguiente comando para asociar un permiso con un repositorio de Artifact Registry.

npm config set @SCOPE_NAME:registry https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY/

Obtén un token de acceso

Los tokens de acceso son válidos durante 60 minutos. Genera un token de acceso poco antes de ejecutar comandos que interactúan con repositorios.

Para obtener un token, usa una de estas opciones:

  • Usa el comando npx para actualizar el token de acceso.

    1. Asegúrate de que las credenciales para conectarte al registro público de la Administración de socios de red estén en el archivo de configuración de la Administración de socios de red de tu usuario, ~/.npmrc.

    2. Ejecuta el siguiente comando en el directorio de tu proyecto de Node.js.

      npx google-artifactregistry-auth
      

      Si tu repositorio de Artifact Registry está configurado como tu registro global y tus paquetes no tienen un permiso, usa el siguiente comando para que pueda descargar el asistente de credenciales del registro público de npm en lugar de tu repositorio de Artifact Registry.

      npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
      
  • Agrega una secuencia de comandos al archivo package.json en tu proyecto.

    "scripts": {
     "artifactregistry-login": "npx google-artifactregistry-auth"
    }
    

    Ejecuta la secuencia de comandos en el directorio de tu proyecto de Node.js.

    npm run artifactregistry-login
    

Artifact Registry lee la configuración del repositorio de Artifact Registry en el archivo .npmrc de tu proyecto y la usa para agregar credenciales de token a tu archivo .npmrc de usuario. Almacenar el token en el archivo .npmrc del usuario aísla tus credenciales del código fuente y del sistema de control de código fuente.

  • --repo-config es el archivo .npmrc con la configuración de tu repositorio. Si no especificas esta marca, la ubicación predeterminada es el directorio actual.
  • --credential-config es la ruta de acceso al archivo .npmrc en el que deseas escribir el token de acceso. El valor predeterminado es el archivo .npmrc del usuario.

Configura la autenticación con contraseña

Usa este enfoque cuando la aplicación de Node.js requiera la autenticación con un nombre de usuario y una contraseña especificados.

Las claves de la cuenta de servicio son credenciales de larga duración. Usa los siguientes lineamientos para limitar el acceso a tus repositorios:

  • Considera usar una cuenta de servicio dedicada para interactuar con los repositorios.
  • Otorga la función mínima de Artifact Registry que requiera la cuenta de servicio. Por ejemplo, asigna la función de lector de Artifact Registry a una cuenta de servicio que solo descargue artefactos.
  • Si los grupos de tu organización requieren diferentes niveles de acceso a repositorios específicos, otorga acceso a nivel de repositorio en lugar de a nivel de proyecto.
  • Sigue las prácticas recomendadas para administrar credenciales.

Para crear una cuenta de servicio y configurar la autenticación, haz lo siguiente:

  1. Crea una cuenta de servicio que actúe en nombre de tu aplicación o elige una cuenta de servicio existente que uses para la automatización.

    Necesitarás la ubicación del archivo de claves de la cuenta de servicio para configurar la autenticación con Artifact Registry. En las cuentas existentes, puedes ver claves y crear claves nuevas en la página Cuentas de servicio.

    Ir a la página Cuentas de servicio

  2. Otorga el rol específico de Artifact Registry a la cuenta de servicio para proporcionar acceso al repositorio.

  3. Si deseas activar la cuenta de servicio en la sesión actual de la CLI de gcloud, ejecuta el siguiente comando:

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

    Dónde

    • ACCOUNT es la cuenta de usuario o servicio.
    • KEY-FILE es la ruta al archivo de claves JSON de la cuenta de servicio.
  4. Ejecuta el siguiente comando para imprimir la configuración del repositorio:

    gcloud artifacts print-settings npm [--project=PROJECT] \
    [--repository=REPOSITORY] [--location=LOCATION] --scope=@SCOPE-NAME --json-key=KEY-FILE
    

    Dónde

    • PROJECT es el ID del proyecto. Si se omite esta marca, se usa el proyecto actual o predeterminado.
    • REPOSITORY es el ID del repositorio. Si configuraste un repositorio predeterminado de Artifact Registry, se usa cuando se omite esta marca del comando.
    • LOCATION es la ubicación regional o multirregional del repositorio.
    • SCOPE-NAME es el nombre del permiso de la Administración de socios de red que se debe asociar con el repositorio.

      El uso de permisos garantiza que siempre publiques e instales paquetes desde el repositorio correcto.

      Los paquetes sin permisos están asociados con tu registro predeterminado de la Administración de socios de red, por lo general, el registro público de la Administración de socios de red. Si no especificas un permiso, la configuración que se muestra establece tu repositorio de Artifact Registry como el registro predeterminado. Esto puede causar problemas si tus proyectos de Node.js deben instalar paquetes del registro público de la Administración de socios de red y de tu repositorio de Artifact Registry.

    • KEY-FILE es la ruta al archivo de claves JSON de la cuenta de servicio.

  5. Agrega los parámetros de configuración que se muestran al archivo de configuración .npmrc en tus proyectos de Node.js. Por lo general, este archivo se encuentra en el mismo directorio que package.json. Asegúrate de incluir esta configuración en los proyectos de Node.js para los paquetes que publicas, así como en los proyectos que instalarán dependencias desde tu repositorio de npm.

  6. Si tienes otros repositorios de Node.js para conectarte, repite los pasos anteriores para obtener la configuración y agrégala al archivo .npmrc.

¿Qué sigue?