Configura l'autenticazione ad Artifact Registry per npm

Quando utilizzi un'applicazione di terze parti per connetterti a un repository, devi eseguire l'autenticazione in Artifact Registry.

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

Prima di iniziare

Installa Google Cloud CLI, quindi initialize eseguendo questo comando:
```
gcloud init
```
Nota: se hai già installato gcloud CLI in precedenza, assicurati di disporre della versione più recente eseguendo gcloud components update.
(Facoltativo) Configura i valori predefiniti per la gcloud CLI;interfaccia a riga di comando gcloud.
Se ti colleghi ai repository da Windows, installa PowerShell.
Crea un account di servizio per agire per conto della tua applicazione.
Se non hai mai utilizzato npm, leggi la panoramica per informazioni sui pacchetti con ambito e sul file di configurazione per le impostazioni di autenticazione.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

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

Autenticazione con un assistente per le credenziali

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

Artifact Registry cerca le credenziali nel seguente ordine:

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 Functions.
Credenziali fornite da Google Cloud CLI, incluse le credenziali utente del comando gcloud auth application-default login.

La variabile GOOGLE_APPLICATION_CREDENTIALS rende esplicita l'account per l'autenticazione, il che semplifica la risoluzione dei problemi. Se non utilizzi la variabile, verifica che tutti gli account che potrebbero essere utilizzati da ADC dispongano delle autorizzazioni richieste. Ad esempio, l'account di servizio predefinito per le VM di Compute Engine, i nodi Google Kubernetes Engine e le revisioni di Cloud Run ha accesso di sola lettura ai repository. Se intendi caricare da questi ambienti utilizzando l'account di servizio predefinito, devi modificare le autorizzazioni.

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

Crea un account di servizio che agisca per conto della tua applicazione oppure scegli un account di servizio esistente che utilizzi per l'automazione CI/CD.
Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.
Assegna il percorso del file della chiave dell'account di servizio alla variabile GOOGLE_APPLICATION_CREDENTIALS, in modo che l'helper per le credenziali di Artifact Registry possa ottenere la tua chiave durante la connessione ai repository.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
Dove KEY-FILE è il percorso del file della chiave dell'account di servizio.

Per configurare l'autenticazione:

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 usato il progetto corrente o predefinito.
- REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
- LOCATION è la località a livello di una o più regioni per il repository.
- SCOPE-NAME è il nome dell'ambito npm da associare al repository.
  
  L'utilizzo degli ambiti garantisce la pubblicazione e l'installazione sempre dei pacchetti dal repository corretto.
  
  I pacchetti senza ambito sono associati al registro npm predefinito, in genere il registro pubblico npm. Se non specifichi un ambito, la configurazione restituita imposta il repository Artifact Registry come registro predefinito. Questo può causare problemi se i progetti Node.js devono installare pacchetti sia dal registro npm pubblico sia dal repository Artifact Registry.
Aggiungere le impostazioni di configurazione restituite al file di configurazione .npmrc nei progetti Node.js. Questo file si trova solitamente 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.
Se hai altri repository Node.js a cui connetterti, ripeti i passaggi precedenti per ottenere le impostazioni e aggiungerle ai file .npmrc appropriati.
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 comando seguente 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 i comandi che interagiscono con i repository.

Per ottenere un token, utilizza una delle seguenti opzioni:

Usa il comando npx per aggiornare il token di accesso.
1. Assicurati che le credenziali per la connessione al registro npm pubblico siano presenti 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 tuoi pacchetti non hanno un ambito, utilizza il comando seguente in modo che il comando possa scaricare l'helper delle credenziali dal registry pubblico npm 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 tuo progetto e le utilizza per aggiungere le credenziali del 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 tuo file utente .npmrc.

Configurazione dell'autenticazione tramite password

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

Le chiavi dell'account di servizio sono credenziali di lunga durata. Segui queste linee guida per limitare l'accesso ai repository:

Valuta la possibilità di utilizzare un account di servizio dedicato per interagire con i repository.
Concedi il ruolo Artifact Registry minimo richiesto dall'account di servizio. Ad esempio, assegna Lettore Artifact Registry a un account di servizio che scarica solo artefatti.
Se i gruppi della tua organizzazione richiedono livelli di accesso diversi 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:

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

Avrai bisogno della posizione del file della chiave dell'account di servizio per configurare l'autenticazione con Artifact Registry. Per gli account esistenti, puoi visualizzare le chiavi e crearne di nuove nella pagina Account di servizio.

Vai alla pagina Account di servizio

Nota: le chiavi degli account di servizio comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi degli account di servizio quando è possibile. Se devi eseguire l'autenticazione con una chiave dell'account di servizio, sei responsabile della sicurezza della chiave privata e di altre operazioni descritte nelle Best practice per la gestione delle chiavi degli account di servizio. Se non ti viene consentito di creare una chiave dell'account di servizio, la creazione di chiavi dell'account di servizio potrebbe essere disabilitata per la tua organizzazione. Per maggiori informazioni, consulta Gestione di risorse dell'organizzazione sicure per impostazione predefinita.
Concedi il ruolo Artifact Registry specifico all'account di servizio per fornire l'accesso al repository.
Se vuoi attivare l'account di servizio nella sessione corrente dell'interfaccia a riga di comando gcloud, esegui il comando:
```
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
```
Dove
- ACCOUNT è l'account utente o di servizio.
- KEY-FILE è il percorso del file di chiave JSON dell'account di servizio.
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 usato il progetto corrente o predefinito.
- REPOSITORY è l'ID del repository. Se hai configurato un repository Artifact Registry predefinito, viene utilizzato quando questo flag viene omesso dal comando.
- LOCATION è la località a livello di una o più regioni per il repository.
- SCOPE-NAME è il nome dell'ambito npm da associare al repository.
  
  L'utilizzo degli ambiti garantisce la pubblicazione e l'installazione sempre dei pacchetti dal repository corretto.
  
  I pacchetti senza ambito sono associati al registro npm predefinito, in genere il registro pubblico npm. Se non specifichi un ambito, la configurazione restituita imposta il repository Artifact Registry come registro predefinito. Questo può causare problemi se i progetti Node.js devono installare pacchetti sia dal registro npm pubblico sia dal repository Artifact Registry.
- KEY-FILE è il percorso del file di chiave JSON dell'account di servizio.
Nota: le impostazioni di configurazione restituite includono un indirizzo email segnaposto. Per pubblicare i pacchetti npm, è necessario un indirizzo email nella configurazione npm. L'indirizzo email segnaposto non viene utilizzato da Artifact Registry per l'autenticazione.
Aggiungere le impostazioni di configurazione restituite al file di configurazione .npmrc nei progetti Node.js. Questo file si trova solitamente 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.
Se hai altri repository Node.js a cui connetterti, ripeti i passaggi precedenti per ottenere le impostazioni e aggiungerle al file .npmrc.