Chiavi API con ambito

Per fare di NuGet un ambiente più sicuro per la distribuzione dei pacchetti, è possibile assumere il controllo delle chiavi API tramite l'aggiunta di ambiti.

La possibilità di fornire l'ambito alle chiavi API garantisce un maggior controllo sulle API. È possibile:

• Creare più chiavi API con ambito che possono essere usate per diversi pacchetti con date di scadenza variabili.
• Ottenere le chiavi API in modo sicuro.
• Modificare le chiavi API esistenti per cambiare l'applicabilità di pacchetto.
• Aggiornare o eliminare le chiavi API esistenti senza intralciare le operazioni che usano altre chiavi.

Perché sono supportate le chiavi API con ambito?

Gli ambiti per le chiavi API sono supportati per rendere disponibili autorizzazioni più dettagliate. In precedenza NuGet offriva un'unica chiave API per un account, e tale approccio presentava diversi inconvenienti:

• Una sola chiave API per controllare tutti i pacchetti. Con una sola chiave API per la gestione di tutti i pacchetti, è difficile condividere in modo sicuro la chiave quando più sviluppatori lavorano su pacchetti diversi e condividono un account editore.
• Tutte le autorizzazioni o nessuna autorizzazione. Chiunque abbia accesso alla chiave API dispone di tutte le autorizzazioni per i pacchetti (pubblicazione, push e rimozione dall'elenco). In molti casi questa situazione non è ottimale in un ambiente con più team.
• Singolo punto di errore. Un'unica chiave API significa anche un singolo punto di guasto. Se la chiave viene compromessa, tutti i pacchetti associati all'account potrebbero risultare compromessi. L'aggiornamento della chiave API è l'unico modo per risolvere il problema ed evitare un'interruzione del flusso di lavoro CI/CD. Possono anche esistere casi in cui si vuole revocare l'accesso alla chiave API per un utente (ad esempio quando un dipendente lascia l'organizzazione). Al momento non esiste un metodo ben definito per gestire questa situazione.

Con le chiavi API con ambito si tenta di risolvere questi problemi, assicurandosi nel contempo che nessuno dei flussi di lavoro esistenti interrompa l'esecuzione.

Acquisire una chiave API

1. Accedi al tuo account nuget.org o crea un account se non ne hai già uno.

2. Selezionare il nome utente in alto a destra e quindi selezionare Chiavi API.

3. Selezionare Crea e specificare un nome per la chiave.

4. In Seleziona ambiti selezionare Push.

5. In Seleziona modello Glob pacchetti>immettere *.

6. Seleziona Crea.

7. Selezionare Copia per copiare la nuova chiave.

   

Importante

• Mantenere sempre la chiave API un segreto. La chiave API è simile a una password che consente a chiunque di gestire i pacchetti per conto dell'utente. Eliminare o rigenerare la chiave API se viene accidentalmente visualizzata.
• Salvare la chiave in una posizione sicura, perché non è possibile copiare di nuovo la chiave in un secondo momento. Se si torna alla pagina della chiave API, è necessario rigenerarla per copiarla. È anche possibile rimuovere la chiave API se non si vuole più eseguire il push dei pacchetti.

L'ambito consente di creare chiavi API separate per scopi diversi. Ogni chiave ha un intervallo di tempo di scadenza ed è possibile definire l'ambito della chiave a pacchetti o modelli GLOB specifici. È anche possibile definire l'ambito di ogni chiave per operazioni specifiche: eseguire il push di nuovi pacchetti e versioni dei pacchetti, eseguire il push solo di nuove versioni del pacchetto o annullare l'elenco.

Tramite la definizione dell'ambito, è possibile creare chiavi API per persone diverse che gestiscono i pacchetti per l'organizzazione in modo che abbiano solo le autorizzazioni necessarie.

Creare chiavi API con ambito

È possibile creare più chiavi API in base alle esigenze. Una chiave API può essere applicata a uno o più pacchetti, avere ambiti diversi che concedono privilegi specifici ed essere associata a una data di scadenza specifica.

Nell'esempio seguente la chiave API con nome Contoso service CI può essere usata per eseguire il push di pacchetti per pacchetti Contoso.Service specifici ed è valida per 365 giorni. Si tratta di uno scenario tipico in cui diversi team all'interno della stessa organizzazione lavorano su pacchetti diversi e i membri del team vengono dotati della chiave che concede loro privilegi solo per il pacchetto su cui stanno lavorando. La scadenza viene usata come meccanismo per evitare la presenza di chiavi non aggiornate o dimenticate.

Usare i criteri GLOB

Se si sta lavorando su più pacchetti e si ha un lungo elenco di pacchetti da gestire, è possibile scegliere di usare i criteri GLOB per selezionare più pacchetti contemporaneamente. Se ad esempio si vuole concedere a una chiave ambiti specifici per tutti i pacchetti il cui ID inizia con Fabrikam.Service, è possibile eseguire questa operazione specificando fabrikam.service.* nella casella di testo del criterio Glob.

L'uso di criteri GLOB per determinare le autorizzazioni della chiave API è valido anche per i nuovi pacchetti corrispondenti al criterio GLOB. Ad esempio, se si tenta di eseguire il push di un nuovo pacchetto denominato Fabrikam.Service.Framework, è possibile farlo con la chiave creata in precedenza, perché il pacchetto corrisponde al criterio GLOB fabrikam.service.*.

Ottenere le chiavi API in modo sicuro

Per la sicurezza, una chiave appena creata non viene mai visualizzata sullo schermo ed è disponibile unicamente tramite il pulsante Copia. Analogamente la chiave non è accessibile dopo l'aggiornamento della pagina.

Modificare chiavi API esistenti

È anche possibile che si voglia aggiornare le autorizzazioni e gli ambiti per le chiavi senza modificare le chiavi stesse. Se si ha una chiave con uno o più ambiti specifici per un singolo pacchetto, è possibile scegliere di applicare lo stesso ambito o gli stessi ambiti su uno o molti altri pacchetti.

Aggiornare o eliminare chiavi API esistenti

Il proprietario dell'account può scegliere di aggiornare la chiave, nel qual caso l'autorizzazione (per i pacchetti), l'ambito e la scadenza rimangono invariati, ma viene emessa una nuova chiave e la chiave precedente diventa inutilizzabile. Questo è utile per la gestione delle chiavi non aggiornate o nei casi in cui esiste il rischio di perdita di chiavi API.

È anche possibile scegliere di eliminare queste chiavi se non sono più necessarie. Se si elimina una chiave, questa viene rimossa e diventa inutilizzabile.

Domande frequenti

Che cosa accade alla chiave API precedente (legacy)?

La chiave API precedente (legacy) continua a funzionare e può funzionare fino a quando si vuole usarla. Tuttavia queste chiavi vengono ritirate se non sono state usate da più di 365 giorni per eseguire il push di un pacchetto. Per altre informazioni, vedere il post di blog Changes to expiring API keys (Modifiche per le chiavi API in scadenza). Questa chiave non può più essere aggiornata. È necessario eliminare la chiave legacy e creare una nuova chiave con ambito.

Nota

Questa chiave ha tutte le autorizzazioni per tutti i pacchetti e non scade mai. È consigliabile eliminare questa chiave e creare nuove chiavi dotate di autorizzazioni con ambito e scadenza definita.

Quante chiavi API è possibile creare?

Non c'è limite al numero di chiavi API che è possibile creare. Tuttavia è consigliabile mantenere un numero di chiavi gestibile, per non avere molte chiavi non aggiornate e non riuscire a controllare da chi e dove vengono usate.

È possibile eliminare la chiave API legacy o interromperne l'uso ora?

Sì. È possibile, ed è probabilmente necessario, eliminare la chiave API legacy.

È possibile riottenere una chiave API eliminata per errore?

No. Dopo aver eliminato una chiave, è solo possibile creare nuove chiavi. Non è possibile recuperare le chiavi eliminate accidentalmente.

La chiave API precedente continua a funzionare dopo l'aggiornamento della chiave API?

No. Quando si aggiorna una chiave, viene generata una nuova chiave con lo stesso ambito, la stessa autorizzazione e la stessa scadenza della chiave precedente. La chiave precedente cessa di esistere.

È possibile concedere più autorizzazioni a una chiave API esistente?

Non è possibile modificare l'ambito, ma è possibile modificare l'elenco dei pacchetti ai quali la chiave è applicabile.

Come si capisce se una delle proprie chiavi è scaduta o sta per scadere?

Se una qualsiasi chiave scade viene visualizzato un messaggio di avviso nella parte superiore della pagina. Viene anche inviato un avviso tramite posta elettronica al titolare dell'account dieci giorni prima della scadenza della chiave, per consentire l'adozione delle misure necessarie con il dovuto anticipo.