Gestire i token di accesso personale tramite l'API REST

Articolo
10/23/2023

Servizi di Azure DevOps

Quando si ha a che fare con un ampio set di token di accesso personale (PAT) di cui si è proprietari, può 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 di cui si è proprietari, consentendo di creare nuovi token di accesso personale e rinnovare o scadere i token di accesso personali esistenti.

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

Prerequisiti

Per usare l'API, è necessario eseguire l'autenticazione con un token Microsoft Entra, che può essere eseguito tramite Microsoft Entra ID OAuth. Per altre informazioni su come eseguire questa operazione, vedere la sezione relativa all'autenticazione seguente.

A tale scopo, è necessario soddisfare alcuni prerequisiti:

È necessario disporre di un tenant di Microsoft Entra con una sottoscrizione di Azure attiva.
A seconda dei criteri di sicurezza del tenant, potrebbe essere necessario concedere all'applicazione 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.

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 PAT. 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, è necessario:

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".

Attenzione

La presenza di un tenant di Microsoft Entra con una sottoscrizione di Azure attiva è un prerequisito per l'uso di questa API.

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, è necessario fornire un token di accesso Microsoft Entra come Bearer token nell'intestazione Authorization della richiesta. Per visualizzare gli esempi 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 usando la libreria MSAL e chiama l'API PAT Lifecycle Management.

Microsoft Authentication Library (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 "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, seguire uno dei due 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

È stata fornita un'applicazione Web Python Flask di esempio per questa API che è possibile scaricare in GitHub e può essere configurata per 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 dovranno 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. Verrà illustrato un esempio in cui questa operazione è stata eseguita per 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 ->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 nel pannello di spostamento a sinistra.
Selezionare il tipo di applicazione: per Python Flask selezionare Applicazione Web.
Selezionare la piattaforma dell'applicazione. Per questa esercitazione selezionare "Python".
Assicurarsi di aver soddisfatto i prerequisiti necessari, quindi consentire portale di Azure di apportare le modifiche necessarie per configurare l'applicazione. L'URL di risposta sarà 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 verrà configurato per l'uso di un endpoint dell'API di test da Microsoft Graph. Sarà necessario modificare il file di configurazione generato in modo che chiami invece l'API PAT Lifecycle Management.

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.

A tale scopo, è necessario eseguire alcune operazioni:

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 verrà usata in 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, installato le relative dipendenze e testato che viene eseguito 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_edizione Standard CRET sia stato spostato in una variabile di ambiente, Azure KeyVault o scambiata 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 aver verificato di avere verificato, è possibile modificare il contenuto di 'app.py' e la 'ms-identity-python-webapp-master\templates' directory per supportare l'invio di richieste al resto degli endpoint dell'API di gestione del ciclo di vita pat. 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 aggiornerà automaticamente il token dopo la scadenza. L'aggiornamento del token impedisce all'utente di dover accedere di nuovo e acquisire un nuovo codice di autorizzazione. Tuttavia, gli utenti potrebbero dover accedere di nuovo dopo 90 giorni alla scadenza del token di aggiornamento.

Esplorare l'API di gestione del ciclo di vita PAT

Nell'applicazione di esempio GitHub precedente e nelle applicazioni di avvio rapido l'applicazione è stata preconfigurata per effettuare richieste con i token di Microsoft Entra acquisiti. Per altre informazioni sugli endpoint, sui parametri che accettano e su cosa vengono restituiti nelle risposte, 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, questa API può essere usata da utenti malintenzionati per creare più punti di ingresso nelle risorse ADO 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. Amministrazione 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, è necessario:

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 abbia impostato 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.

Passaggi successivi

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