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 per gli ambienti di runtime come Google Kubernetes Engine e Cloud Run, ma devi verificare che le autorizzazioni richieste siano configurate.

Prima di iniziare

Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente:
```
gcloud init
```
Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Nota: se hai installato gcloud CLI in precedenza, assicurati di avere l'ultima versione eseguendo gcloud components update.
(Facoltativo) Configura le impostazioni predefinite per i comandi gcloud CLI.
Se ti connetti ai repository da Windows, installa PowerShell.
Crea un account di servizio che agisca per conto della tua applicazione.
Se non hai mai utilizzato npm, leggi la panoramica per scoprire di più sui pacchetti con ambito e il file di configurazione per le impostazioni di autenticazione.

Panoramica

Artifact Registry supporta i seguenti metodi di autenticazione.

Utilizzo di un helper per le 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.
Specifica di 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 per le credenziali

google-artifactregistry-auth è una libreria client che recupera 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 dal account di servizio predefinito per Compute Engine, Google Kubernetes Engine, Cloud Run, App Engine o le funzioni Cloud Run.
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 caricare da questi ambienti utilizzando il 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 service account che agisca per conto della tua applicazione oppure scegli un service account esistente da utilizzare per l'automazione CI/CD.
Concedi il ruolo Artifact Registry specifico al account di servizio per fornire l'accesso al repository.
Assegna la posizione del file della chiave del account di servizio alla variabile GOOGLE_APPLICATION_CREDENTIALS in modo che l'helper per le credenziali di Artifact Registry possa recuperare la chiave quando si connette ai repository.
```
export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
```
Dove KEY-FILE è il percorso del file della chiave del account di servizio .

Per configurare l'autenticazione:

Esegui il comando seguente 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 corrente 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 località regionale o multiregionale location del repository.
- SCOPE-NAME è il nome dell'ambito npm scope 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 registro npm predefinito, in genere il registro npm pubblico. Se non specifichi un ambito, la configurazione restituita imposta il repository Artifact Registry come registro predefinito. Questo può causare problemi se i tuoi progetti Node.js devono installare pacchetti sia dal registro npm pubblico sia dal repository Artifact Registry.
Aggiungi le impostazioni di configurazione restituite al file di configurazione .npmrc nei tuoi progetti Node.js. Questo file si trova in genere 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 aggiungile ai file .npmrc appropriati.
Quando sei 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 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 siano nel file di configurazione npm dell'utente, ~/.npmrc.
2. Esegui il comando seguente nella directory del progetto Node.js.
```
npx google-artifactregistry-auth
```
  Se il repository Artifact Registry è impostato come registro globale e i pacchetti non hanno un ambito, utilizza il comando seguente in modo che il comando possa scaricare l'helper per le 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 del token al file .npmrc dell'utente. L'archiviazione del token nel file .npmrc dell'utente isola le 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 località 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.

Configurare l'autenticazione password

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

Le chiavi del service account sono credenziali a lunga durata. Utilizza le seguenti 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 dal account di servizio. 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 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 service account che agisca per conto della tua applicazione oppure scegli un service account esistente da utilizzare per l'automazione.

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

Vai alla pagina Service account

Nota: le chiavi dei service account comportano un rischio per la sicurezza se non vengono gestite correttamente. Dovresti scegliere un'alternativa più sicura alle chiavi del service account 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 in Best practice per la gestione delle chiavi dei service account. Se non riesci a creare una chiave del service account, la creazione di chiavi del service account potrebbe essere disabilitata per la tua organizzazione. Per ulteriori informazioni, vedi Gestione delle risorse dell'organizzazione sicure per impostazione predefinita.
Se hai acquisito la chiave del service account da una fonte esterna, devi convalidarla prima dell'utilizzo. Per maggiori informazioni, consulta Requisiti di sicurezza per le credenziali di origine esterna.
Concedi il ruolo Artifact Registry specifico al account di servizio per fornire l'accesso al repository.
Se vuoi attivare il account di servizio nella sessione gcloud CLI corrente, 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 della chiave JSON del account di servizio .
Esegui il comando seguente 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 corrente 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 località regionale o multiregionale location del repository.
- SCOPE-NAME è il nome dell'ambito npm scope 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 registro npm predefinito, in genere il registro npm pubblico. Se non specifichi un ambito, la configurazione restituita imposta il repository Artifact Registry come registro predefinito. Questo può causare problemi se i tuoi progetti Node.js devono installare pacchetti sia dal registro npm pubblico sia dal repository Artifact Registry.
- KEY-FILE è il percorso del file della chiave JSON del account di servizio .
Nota: le impostazioni di configurazione restituite includono un indirizzo email segnaposto. È necessario un indirizzo email nella configurazione di npm per pubblicare i pacchetti npm. L'indirizzo email segnaposto non viene utilizzato da Artifact Registry per l'autenticazione.
Aggiungi le impostazioni di configurazione restituite al file di configurazione .npmrc nei tuoi progetti Node.js. Questo file si trova in genere 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 aggiungile al file .npmrc.