Configura l'autenticazione in Artifact Registry per npm

Devi autenticarti in Artifact Registry quando utilizzi un'applicazione di terze parti per connetterti a un repository.

Non è necessario configurare l'autenticazione per Cloud Build o Google Cloud ambienti di runtime come Google Kubernetes Engine e Cloud Run, ma devi verificare che siano configurate le autorizzazioni richieste.

Prima di iniziare

  1. Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il seguente comando: 

    gcloud init

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla gcloud CLI con la tua identità federata.

  2. (Facoltativo) Configura le impostazioni predefinite per i comandi gcloud CLI.
  3. Se ti connetti ai repository da Windows, installa PowerShell.
  4. Crea un account di servizio che agisca per conto della tua applicazione.
  5. Se non hai mai utilizzato npm, leggi la panoramica per scoprire di più sui pacchetti con ambito e sul file di configurazione per le impostazioni di autenticazione.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

Utilizzare un helper delle credenziali
Questa opzione offre la massima flessibilità. Quando includi l'helper nella configurazione di npm, Artifact Registry cerca le credenziali del account di servizio nell'ambiente.
Specificare una account di servizio account come credenziale
Utilizza questa opzione quando un'applicazione non supporta le credenziali predefinite dell'applicazione, ma supporta l'autenticazione con un nome utente e una password.

Autenticazione con un helper delle credenziali

google-artifactregistry-auth è una libreria client che ottiene le credenziali per i repository Artifact Registry.

Artifact Registry cerca le credenziali nel seguente ordine:

  1. Credenziali predefinite dell'applicazione (ADC), una strategia che cerca le credenziali nel seguente ordine:

    1. Credenziali definite nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

    2. Credenziali fornite dall'account di servizio predefinito per Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o Cloud Run Functions.

  2. Credenziali fornite da Google Cloud CLI, incluse le credenziali utente dal comando gcloud auth application-default login.

La variabile GOOGLE_APPLICATION_CREDENTIALS rende esplicito l'account per l'autenticazione, il che semplifica la risoluzione dei problemi. Se non utilizzi la variabile, verifica che tutti gli account che ADC potrebbe utilizzare dispongano delle autorizzazioni richieste. Ad esempio, il service account predefinito per le VM Compute Engine, i nodi Google Kubernetes Engine e le revisioni di Cloud Run ha accesso in sola lettura ai repository. Se intendi eseguire il caricamento da questi ambienti utilizzando ilaccount di serviziot predefinito, devi modificare le autorizzazioni.

Per creare un account di servizio e impostare la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS:

  1. Crea un service account che agisca per conto della tua applicazione oppure scegli un service account esistente da utilizzare per l'automazione CI/CD.

  2. Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.

  3. Assegna la posizione del file della chiave del account di servizio alla variabile GOOGLE_APPLICATION_CREDENTIALS in modo che l'helper delle credenziali di Artifact Registry possa ottenere la chiave quando si connette ai repository.

    export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE

    dove KEY-FILE è il percorso del file di chiave dell'account di servizio.

Per configurare l'autenticazione:

  1. Esegui questo comando per stampare la configurazione del repository:

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

    Dove

    • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto attuale o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, questo viene utilizzato quando questo flag viene omesso dal comando.
    • LOCATION è la posizione regionale o multiregionale del repository.

    • SCOPE-NAME è il nome dell'ambito npm da associare al repository.

      L'utilizzo degli ambiti garantisce che tu pubblichi e installi sempre i pacchetti dal repository corretto.

      I pacchetti senza ambito sono associati al registry npm predefinito, in genere il registry npm pubblico. Se non specifichi un ambito, la configurazione restituita imposta il repository Artifact Registry come registro predefinito. Ciò può causare problemi se i tuoi progetti Node.js devono installare pacchetti sia dal registro npm pubblico sia dal tuo repository Artifact Registry.

  2. Aggiungi le impostazioni di configurazione restituite al file di configurazione .npmrc nei tuoi progetti Node.js. Questo file si trova di solito nella stessa directory di package.json.

    Assicurati di includere queste impostazioni nei progetti Node.js per i pacchetti che pubblichi e per i progetti che installeranno le dipendenze dal tuo repository npm.

  3. Se hai altri repository Node.js a cui connetterti, ripeti i passaggi precedenti per ottenere le impostazioni e aggiungerle ai file .npmrc appropriati.

  4. Quando è tutto pronto per connettere un repository, ottieni un token di accesso per l'autenticazione.

Ogni repository di pacchetti Node.js di Artifact Registry è associato a un endpoint del registro https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY

Se non hai specificato un ambito con il comando print-settings, puoi eseguire il seguente comando per associare un ambito a un repository Artifact Registry.

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

Ottenere un token di accesso

I token di accesso sono validi per 60 minuti. Genera un token di accesso poco prima di eseguire comandi che interagiscono con i repository.

Per ottenere un token, utilizza una di queste opzioni:

  • Utilizza il comando npx per aggiornare il token di accesso.

    1. Assicurati che le credenziali per la connessione al registro npm pubblico si trovino nel file di configurazione npm dell'utente, ~/.npmrc.

    2. Esegui questo comando nella directory del progetto Node.js.

      npx google-artifactregistry-auth

      Se il repository Artifact Registry è impostato come registro globale e i pacchetti non sono inclusi nell'ambito, utilizza il seguente comando in modo che possa scaricare l'helper delle credenziali dal registro npm pubblico anziché dal repository Artifact Registry.

      npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth

  • Aggiungi uno script al file package.json nel tuo progetto.

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

    Esegui lo script nella directory del progetto Node.js.

    npm run artifactregistry-login

Artifact Registry legge le impostazioni del repository Artifact Registry nel file .npmrc del progetto e le utilizza per aggiungere le credenziali token al file .npmrc dell'utente. L'archiviazione del token nel file .npmrc dell'utente isola le tue credenziali dal codice sorgente e dal sistema di controllo del codice sorgente.

  • --repo-config è il file .npmrc con le impostazioni del repository. Se non specifichi questo flag, la posizione predefinita è la directory corrente.
  • --credential-config è il percorso del file .npmrc in cui vuoi scrivere il token di accesso. Il valore predefinito è il file .npmrc dell'utente.

Configurazione dell'autenticazione con password

Utilizza questo approccio quando la tua applicazione Node.js richiede l'autenticazione con un nome utente e una password specifici.

Le chiavi del service account sono credenziali di lunga durata. Utilizza le seguenti linee guida per limitare l'accesso ai tuoi repository:

  • Valuta la possibilità di utilizzare un account di servizio dedicato per interagire con i repository.
  • Concedi il ruolo Artifact Registry minimo richiesto dalaccount di serviziot. Ad esempio, assegna il ruolo Lettore Artifact Registry a un account di servizio che scarica solo gli artefatti.
  • Se i gruppi della tua organizzazione richiedono diversi livelli di accesso a repository specifici, concedi l'accesso a livello di repository anziché a livello di progetto.
  • Segui le best practice per la gestione delle credenziali.

Per creare un account di servizio e configurare l'autenticazione:

  1. Crea un service account che agisca per conto della tua applicazione oppure scegli un service account esistente che utilizzi per l'automazione.

    Per configurare l'autenticazione con Artifact Registry, devi conoscere la posizione del file delle chiavi del account di servizio. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.

    Vai alla pagina Service account

  2. Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.

  3. Se vuoi attivare il account di servizio nella sessione corrente gcloud CLI, esegui il comando:

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

    Dove

    • ACCOUNT è l'utente o il account di servizio.
    • KEY-FILE è il percorso del file della chiave JSON dell'account di servizio.

  4. Esegui questo comando per stampare la configurazione del repository:

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

    Dove

    • PROJECT è l'ID progetto. Se questo flag viene omesso, viene utilizzato il progetto attuale o predefinito.
    • REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, questo viene utilizzato quando questo flag viene omesso dal comando.
    • LOCATION è la posizione regionale o multiregionale del repository.

    • SCOPE-NAME è il nome dell'ambito npm da associare al repository.

      L'utilizzo degli ambiti garantisce che tu pubblichi e installi sempre i pacchetti dal repository corretto.

      I pacchetti senza ambito sono associati al registry npm predefinito, in genere il registry npm pubblico. Se non specifichi un ambito, la configurazione restituita imposta il repository Artifact Registry come registro predefinito. Ciò può causare problemi se i tuoi progetti Node.js devono installare pacchetti sia dal registro npm pubblico sia dal tuo repository Artifact Registry.

    • KEY-FILE è il percorso del file della chiave JSON dell'account di servizio.

  5. Aggiungi le impostazioni di configurazione restituite al file di configurazione .npmrc nei tuoi progetti Node.js. Questo file si trova di solito nella stessa directory di package.json. Assicurati di includere queste impostazioni nei progetti Node.js per i pacchetti che pubblichi e per i progetti che installeranno le dipendenze dal tuo repository npm.

  6. Se hai altri repository Node.js a cui connetterti, ripeti i passaggi precedenti per ottenere le impostazioni e aggiungerle al file .npmrc.

Passaggi successivi