Gestire i token di accesso personale tramite l'API REST

Articolo
10/25/2024

Servizi di Azure DevOps

Quando si ha a che fare con un ampio set di token di accesso personale (PAT) di cui si è proprietari, potrebbe diventare complesso gestire la manutenzione di questi token usando solo l'interfaccia utente.

Con l'API di gestione del ciclo di vita del token di accesso personale, è possibile gestire facilmente i token di accesso personale associati alle organizzazioni usando processi automatizzati. Questo set completo di API consente di gestire le api, consentendo di creare nuovi PT e rinnovare o scadere i PT esistenti.

In questo articolo viene illustrato come configurare un'applicazione che esegue l'autenticazione con un token di Microsoft Entra ed effettua chiamate con l'API del ciclo di vita del token di accesso personale. Se si desidera visualizzare solo l'elenco completo degli endpoint disponibili, visualizzare qui il riferimento all'API.

Prerequisiti

Autorizzazioni: a seconda dei criteri di sicurezza del tenant, l'applicazione potrebbe richiedere autorizzazioni per accedere alle risorse nell'organizzazione. In questo momento, l'unico modo per procedere con l'uso di questa app in questo tenant consiste nel chiedere a un amministratore di concedere l'autorizzazione all'app prima di poterla usare.

Autenticazione:
- Per usare l'API, eseguire l'autenticazione con un token Microsoft Entra tramite Microsoft Entra ID OAuth. Per altre informazioni, vedere la sezione relativa all'autenticazione.
- Avere un tenant di Microsoft Entra con una sottoscrizione di Azure attiva.

Nota

Non è possibile usare entità servizio o identità gestite per creare o revocare LET.

Eseguire l'autenticazione con i token di Microsoft Entra

A differenza di altre API di Azure DevOps Services, gli utenti devono fornire un token di accesso a Microsoft Entra per usare questa API anziché un token di accesso personale. I token Microsoft Entra sono un meccanismo di autenticazione più sicuro rispetto all'uso di TOKEN. Dato che questa API è in grado di creare e revocare LET, si vuole garantire che tali funzionalità potenti vengano concesse solo agli utenti autorizzati.

Per acquisire e aggiornare i token di accesso di Microsoft Entra, eseguire le attività seguenti:

Importante

Soluzioni "on-behalf-of application", ad esempio il flusso "credenziali client" e qualsiasi flusso di autenticazione che non rilascia un token di accesso Microsoft Entra non è valido per l'uso con questa API. Se l'autenticazione a più fattori è abilitata nel tenant di Microsoft Entra, è sicuramente necessario usare il flusso "codice di autorizzazione".

Dopo aver creato un'applicazione con un flusso di autenticazione funzionante per la gestione dei token di Microsoft Entra, è possibile usare questi token per effettuare chiamate all'API di gestione del ciclo di vita PAT.

Per chiamare direttamente l'API, fornire un token di accesso Microsoft Entra come Bearer token nell'intestazione Authorization della richiesta. Per altre informazioni e un elenco completo delle richieste disponibili, vedere le informazioni di riferimento sull'API PAT.

Nella sezione seguente viene illustrato come creare un'app che autentica un utente con un token di accesso Microsoft Entra. L'app usa la libreria Microsoft Authentication Library (MSAL) e chiama l'API di gestione del ciclo di vita PAT.

MSAL include più flussi di autenticazione conformi che è possibile usare all'interno dell'app per acquisire e aggiornare i token Microsoft Entra. Un elenco completo dei flussi MSAL è disponibile nella documentazione dei flussi di autenticazione di Microsoft Authentication Library. Una guida alla scelta del metodo di autenticazione appropriato per l'applicazione è disponibile in Scelta del metodo di autenticazione appropriato per Azure DevOps.

Per iniziare, vedere uno degli esempi seguenti:

Clonare l'app Python Flask di esempio e configurarla con il tenant e l'organizzazione ADO
Generare un'applicazione di esempio nel portale di Azure per la lingua preferita e configurarla per l'API di gestione del ciclo di vita PAT

Clonare l'app Web Python Flask

È disponibile un'applicazione Web Python Flask di esempio per questa API che è possibile scaricare in GitHub e configurare l'uso con il tenant di Microsoft Entra e l'organizzazione Azure DevOps. L'applicazione di esempio usa il flusso del codice di autenticazione MSAL per acquisire un token di accesso Microsoft Entra.

Importante

È consigliabile iniziare a usare l'applicazione Web Python Flask di esempio in GitHub, ma se si preferisce usare un linguaggio o un tipo di applicazione diverso, usare l'opzione Avvio rapido per ricreare un'applicazione di test equivalente.

Dopo aver clonato l'app di esempio, seguire le istruzioni nel file LEGGIMI del repository. ReadME spiega come registrare un'applicazione nel tenant di Microsoft Entra, configurare l'esempio per usare il tenant di Microsoft Entra ed eseguire l'app clonata.

Generare un'applicazione di avvio rapido portale di Azure

È invece possibile generare un'app di esempio con il codice MSAL generato usando l'opzione Avvio rapido nella pagina dell'applicazione in portale di Azure. L'applicazione di test di avvio rapido segue il flusso del codice di autorizzazione, ma esegue questa operazione con un endpoint dell'API Microsoft Graph. Gli utenti devono aggiornare la configurazione dell'applicazione in modo che punti all'endpoint per l'API di gestione del ciclo di vita PAT.

Per seguire questo approccio, seguire le istruzioni di avvio rapido per il tipo di applicazione preferito nella home page della documentazione Sviluppo di MICROSOFT Entra ID. L'esempio seguente viene illustrato con un'app di avvio rapido Python Flask.

Esempio: Introduzione a un'applicazione di avvio rapido Python Flask

Dopo aver registrato l'applicazione in un tenant di Microsoft Entra con una sottoscrizione di Azure attiva, passare all'applicazione registrata in Microsoft Entra ID ->App Registrations (Registrazioni app) nel portale di Azure.
Selezionare l'applicazione e passare a Autorizzazioni API.
Selezionare Aggiungi un'autorizzazione e selezionare Azure DevOps -> controllare user_impersonation -> selezionare Aggiungi autorizzazioni.
Selezionare Avvio rapido.
Selezionare il tipo di applicazione: per Python Flask selezionare Applicazione Web.
Selezionare la piattaforma dell'applicazione. Per questa esercitazione selezionare Python.
Assicurarsi di soddisfare i prerequisiti necessari, quindi consentire portale di Azure di apportare le modifiche necessarie per configurare l'applicazione. L'URL di risposta è l'URL di reindirizzamento impostato alla creazione dell'applicazione + "/getAToken".
Scaricare l'applicazione Avvio rapido ed estrarre i file.
Installare i requisiti dell'applicazione ed eseguire l'applicazione per assicurarsi di avere tutte le dipendenze necessarie. L'applicazione viene inizialmente configurata per raggiungere un endpoint nell'API Microsoft Graph. Informazioni su come modificare questo endpoint nell'endpoint di base dell'API PAT Lifecycle Management seguendo le istruzioni di configurazione nella sezione seguente.

Configurare un'applicazione di avvio rapido

Dopo aver scaricato e installato l'applicazione di avvio rapido, l'utente viene configurato per l'uso di un endpoint dell'API di test da Microsoft Graph. Modificare il file di configurazione generato in modo che chiami invece l'API di gestione del ciclo di vita PAT.

Suggerimento

La raccolta e l'organizzazione vengono usate in modo intercambiabile in questi documenti. Se una variabile di configurazione richiede un nome di raccolta, sostituirla con il nome dell'organizzazione.

Eseguire le attività seguenti:

Aggiornare la variabile di configurazione ENDPOINT a https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview per le API di gestione del ciclo di vita PAT
Aggiornare la variabile di configurazione SCOPE a "499b84ac-1321-427f-aa17-267ca6975798/.default" per fare riferimento alla risorsa Azure DevOps e a tutti i relativi ambiti.

L'esempio seguente illustra come è stata eseguita questa configurazione per l'applicazione Python Flask di avvio rapido generata tramite il portale di Azure nella sezione precedente.

Assicurarsi di seguire le istruzioni per proteggere il segreto client, inizialmente inserito in testo normale nel file di configurazione dell'applicazione. Come procedura consigliata, rimuovere la variabile di testo normale dal file di configurazione e usare una variabile di ambiente o Azure KeyVault per proteggere il segreto dell'applicazione.

È invece possibile scegliere di usare un certificato anziché un segreto client. L'uso dei certificati è l'opzione consigliata se l'applicazione viene usata nell'ambiente di produzione. Le istruzioni per l'uso di un certificato sono disponibili nel passaggio finale della configurazione dell'applicazione di avvio rapido.

Attenzione

Non lasciare mai un segreto client di testo normale nel codice dell'applicazione di produzione.

Esempio: Configurare un'applicazione di avvio rapido Python Flask per l'API di gestione del ciclo di vita PAT

Dopo aver scaricato l'applicazione di avvio rapido, installare le relative dipendenze e verificare che venga eseguita nell'ambiente in uso, aprire il app_config.py file nell'editor preferito. Il file dovrebbe essere simile al frammento di codice seguente; per maggiore chiarezza, i commenti che fanno riferimento alla configurazione predefinita dell'API Microsoft Graph sono stati rimossi:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret,
# like Azure Key Vault. Or, use an environment variable as described in Flask's documentation:
# https://flask.palletsprojects.com/en/1.1.x/config/#configuring-from-environment-variables
# CLIENT_SECRET = os.getenv("CLIENT_SECRET")
# if not CLIENT_SECRET:
#     raise ValueError("Need to define CLIENT_SECRET environment variable")

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  

SCOPE = ["User.ReadBasic.All"]

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Aggiornare l'ID client o il segreto client all'applicazione con l'ID client e il segreto client della registrazione dell'app. Quando si esegue l'ambiente di produzione, assicurarsi di proteggere il segreto client usando una variabile di ambiente, Azure KeyVault o passando a un certificato.
```
CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

CLIENT_SECRET = "YOUR_CLIENT_SECRET_HERE" 
# Placeholder - for use ONLY during testing.
# In a production app, we recommend you use a more secure method of storing your secret.
```

Modificare la variabile con l'URL ENDPOINT della raccolta e l'endpoint API di Azure DevOps. Ad esempio, per una raccolta denominata "testCollection", il valore sarà:

# Fill in the url to the user's ADO collection + the PAT lifecycle management API endpoint here

ENDPOINT = 'https://vssps.dev.azure.com/{YOUR_COLLECTION_NAME_HERE}/_apis/Tokens/Pats?api-version=6.1-preview'

Per una raccolta denominata "testCollection", questo endpoint sarà:

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview'

Modificare la SCOPE variabile in modo che faccia riferimento alla risorsa API di Azure DevOps. La stringa di caratteri è l'ID risorsa per l'API Azure DevOps e l'ambito .default fa riferimento a tutti gli ambiti per tale ID risorsa.
```
SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
```
Se l'applicazione è configurata per un tenant specifico (anziché per la configurazione multi-tenant), usare il valore alternativo per la AUTHORITY variabile, aggiungendo il nome del tenant specifico in "Enter_the_Tenant_Name_Here".
```
# For single-tenant app:
AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"

# For multi-tenant app:
AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"
```

Verificare che il file finale app_config.py corrisponda al seguente, con il CLIENT_ID, l'ID tenant e l'URL della raccolta. Per motivi di sicurezza, assicurarsi che il CLIENT_SECRET sia stato spostato in una variabile di ambiente, azure KeyVault o scambiato con un certificato per l'applicazione registrata:

import os

CLIENT_ID = "YOUR_CLIENT_ID_HERE" 
# Application (client) ID of app registration

# Note that the CLIENT_SECRET has been removed and moved to an environment variable or Azure KeyVault

AUTHORITY = "https://login.microsoftonline.com/YOUR_AAD_TENANT_ID_HERE"  # For multi-tenant app
# AUTHORITY = "https://login.microsoftonline.com/Enter_the_Tenant_Name_Here"

REDIRECT_PATH = "/getAToken"  
# Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set in the app's registration in the Azure portal.

ENDPOINT = 'https://vssps.dev.azure.com/testCollection/_apis/Tokens/Pats?api-version=6.1-preview' 
# Used to configure user's collection URL and the desired API endpoint

SCOPE = ["499b84ac-1321-427f-aa17-267ca6975798/.default"]
# Means "All scopes for the Azure DevOps API resource"

SESSION_TYPE = "filesystem"  
# Specifies the token cache should be stored in server-side session

Eseguire di nuovo l'applicazione per testare che è possibile ottenere tutti i token PAT per l'utente richiedente. Dopo la verifica, è possibile modificare il contenuto di 'app.py' e la 'ms-identity-python-webapp-master\templates' directory per supportare l'invio di richieste agli endpoint dell'API di gestione del ciclo di vita PAT rimanenti. Per un esempio di applicazione di avvio rapido Python Flask modificata per supportare le richieste a tutti gli endpoint api di gestione del ciclo di vita PAT, vedere questo repository di esempio in GitHub.

Aggiornare automaticamente un token di accesso di Microsoft Entra

Una volta configurata correttamente l'applicazione e l'utente ha acquisito un token di accesso, il token può essere usato per un massimo di un'ora. Il codice MSAL fornito in entrambi gli esempi precedenti aggiorna automaticamente il token dopo la scadenza. L'aggiornamento del token impedisce all'utente di eseguire di nuovo l'accesso e acquisire un nuovo codice di autorizzazione. Tuttavia, gli utenti potrebbero dover eseguire di nuovo l'accesso dopo 90 giorni dopo la scadenza del token di aggiornamento.

Esplorare le API di gestione del ciclo di vita PAT

Nell'applicazione di esempio e nelle applicazioni di avvio rapido di GitHub precedenti, l'applicazione è preconfigurata per effettuare richieste con i token Microsoft Entra acquisiti. Per altre informazioni, vedere la documentazione di riferimento sulle API.

Domande frequenti

D: Perché è necessario eseguire l'autenticazione con un token Microsoft Entra? Perché un pat non è sufficiente?

R: Con questa API di gestione del ciclo di vita PAT, è stata aperta la possibilità di creare nuovi TOKEN di accesso e revocare le connessioni PAT esistenti. Nelle mani sbagliate, gli attori malintenzionati potrebbero usare questa API per creare più punti di ingresso nelle risorse di Azure DevOps dell'organizzazione. Applicando l'autenticazione di Microsoft Entra, ci auguriamo che questa API potente sia più sicura rispetto a questo utilizzo non autorizzato.

D: È necessario avere un tenant di Microsoft Entra con una sottoscrizione di Azure attiva per usare questa API?

R: Sfortunatamente, questa API è disponibile solo per gli utenti che fanno parte di un tenant di Microsoft Entra con una sottoscrizione di Azure attiva.

D: È possibile ottenere un esempio di questa applicazione di esempio per un altro tipo di linguaggio/framework/applicazione?

R: Amiamo che vuoi usare l'API nella tua lingua preferita. Se si ha una richiesta per un esempio, passare alla community di sviluppo per verificare se un altro utente ha un esempio da condividere. Se si ha un'applicazione di esempio che si vuole condividere con il pubblico di Azure DevOps più ampio, segnalarlo ed è possibile esaminarla in modo più ampio su questi documenti.

D: Qual è la differenza tra questa API token e l'API di amministrazione del token?

R: Questa API token e l'API di amministrazione del token, mentre simili, servono casi d'uso e gruppi di destinatari diversi:

Questa API di token è in gran parte destinata agli utenti che vogliono gestire i token DI dominio di cui sono proprietari in una pipeline automatizzata. Questa API consente. Offre la possibilità di creare nuovi token e aggiornarli esistenti.
L'API di amministrazione del token è destinata agli amministratori dell'organizzazione. Gli amministratori possono usare questa API per recuperare e revocare le autorizzazioni OAuth, inclusi i token di accesso personale (PAT) e i token di sessione autodescrittura, degli utenti nelle organizzazioni.

D: Come è possibile rigenerare/ruotare i PT tramite l'API? Ho visto questa opzione nell'interfaccia utente, ma non vedo un metodo simile nell'API.

R: Grande domanda! La funzionalità "Rigenera" disponibile nell'interfaccia utente esegue effettivamente alcune azioni, che sono completamente replicabili tramite l'API.

Per ruotare il pat, seguire questa procedura:

Comprendere i metadati del pat usando una chiamata GET .
Creare un nuovo pat con i metadati del pat precedente usando una chiamata POST .
Revocare il pat precedente usando una chiamata DELETE

D: Viene visualizzato un popup "Need admin approval" (Richiesta approvazione amministratore) quando si tenta di procedere con l'uso di questa app. Come posso usare questa app senza l'approvazione dell'amministratore?

R: Sembra che il tenant disponga di criteri di sicurezza, che richiedono che all'applicazione vengano concesse le autorizzazioni per accedere alle risorse nell'organizzazione. In questo momento, l'unico modo per procedere con l'uso di questa app in questo tenant consiste nel chiedere a un amministratore di concedere l'autorizzazione all'app prima di poterla usare.

D: Perché viene visualizzato un errore simile a "Le entità servizio non sono autorizzate a eseguire questa azione" quando si tenta di chiamare l'API di gestione del ciclo di vita PAT usando un'entità servizio o un'identità gestita?

R: Le entità servizio e le identità gestite non sono consentite. Dato che questa API è in grado di creare e revocare LET, si vuole garantire che tali funzionalità potenti vengano concesse solo agli utenti autorizzati.

Passaggi successivi

Informazioni sugli endpoint dell'API di gestione del ciclo di vita pat

Condividi tramite