Accedere agli utenti e chiamare un'API in un'applicazione di esempio Web Node.js

Articolo
06/20/2024

Questa guida usa un'applicazione Web di esempio Node.js per illustrare come aggiungere l'autenticazione e l'autorizzazione. L'applicazione di esempio consente agli utenti di accedere a un'app Web Node.js, che chiama quindi un'API .NET. È possibile abilitare l'autenticazione e l'autorizzazione usando i dettagli del tenant esterno. L'applicazione Web di esempio usa Microsoft Authentication Library (MSAL) per Node per gestire l'autenticazione.

In questo articolo vengono completate le attività seguenti:

Registrare e configurare un'API Web nell'interfaccia di amministrazione di Microsoft Entra.
Registrare e configurare un'applicazione Web client nell'interfaccia di amministrazione di Microsoft Entra.
Creare un flusso utente di iscrizione e accesso nell'interfaccia di amministrazione di Microsoft Entra e quindi associarla a un'app Web client.
Aggiornare un'applicazione Web Node di esempio e ASP.NET API Web per usare i dettagli del tenant esterno.
Eseguire e testare l'applicazione Web e l'API di esempio.

Prerequisiti

Visual Studio Code o un altro editor di codice.
Node.js.
.NET 7.0 o versione successiva.
Un tenant esterno. Se non se ne dispone già, iscriversi per ottenere una versione di prova gratuita.

Registrare un'applicazione Web e/o un'API Web

In questo passaggio si creano le registrazioni dell'applicazione Web e dell'API Web e si specificano gli ambiti dell'API Web.

Registrare un'applicazione API Web

Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno uno sviluppatore di applicazioni.
Se si ha accesso a più tenant, usare l'iconaImpostazioni nel menu in alto per passare al tenant esterno dal menu Directory e sottoscrizioni.
Passare a Identità>Applicazioni>Registrazioni app.
Seleziona + Nuova registrazione.
Nella pagina Registra un'applicazione visualizzata immettere le informazioni sulla registrazione dell'applicazione:
1. Nella sezione Nome immettere un nome di applicazione significativo che verrà visualizzato agli utenti dell'app, ad esempio ciam-ToDoList-api.
2. In Tipi di account supportati selezionare Account solo in questa directory organizzativa.
Selezionare Registra per creare l'applicazione.
Il riquadro Panoramica dell'applicazione viene visualizzato al termine della registrazione. Registrare l'ID directory (tenant) e l'ID applicazione (client) da usare nel codice sorgente dell'applicazione.

Configurare gli ambiti dell'API

Questa API deve esporre le autorizzazioni, che un client deve acquisire per chiamare l'API:

Un'API deve pubblicare almeno un ambito, detto anche Autorizzazione delegata, affinché le app client possano ottenere correttamente un token di accesso per un utente. Per pubblicare un ambito, seguire questa procedura:

Nella pagina Registrazioni app, selezionare l'applicazione API creata (ciam-ToDoList-api) per aprire la relativa pagina di Panoramica.
In Gestisci selezionare Esponi un'API.
Nella parte superiore della pagina, accanto a URI ID applicazione, selezionare il collegamento Aggiungi per generare un URI univoco per questa app.
Accettare l'URI dell'ID applicazione proposto, ad esempio api://{clientId}, e selezionare Salva. Quando l'applicazione Web richiede un token di accesso per l'API Web, aggiunge l'URI come prefisso per ogni ambito definito per l'API.
In Ambiti definiti da questa API selezionare Aggiungi un ambito.

Immettere i valori seguenti che definiscono un accesso in lettura all'API, quindi selezionare Aggiungi ambito per salvare le modifiche:

Proprietà	valore
Nome ambito	ToDoList.Read
Utenti che possono fornire il consenso	Solo amministratori
Nome visualizzato consenso dell'amministratore	Lettura dell'elenco di attività degli utenti tramite "TodoListApi"
Descrizione consenso dell'amministratore	Consente all'app di leggere l'elenco di attività dell'utente tramite "TodoListApi".
Provincia	Abilitato

Selezionare di nuovo Aggiungi ambito e immettere i valori seguenti che definiscono un ambito di accesso in lettura e scrittura all'API. Selezionare Aggiungi ambito per salvare le modifiche:

Proprietà	valore
Nome ambito	ToDoList.ReadWrite
Utenti che possono fornire il consenso	Solo amministratori
Nome visualizzato consenso dell'amministratore	Lettura e scrittura nell'elenco di attività degli utenti tramite "TodoListApi"
Descrizione consenso dell'amministratore	Consente all'app di leggere e scrivere nell'elenco di attività dell'utente tramite "TodoListApi"
Provincia	Abilitato

In Gestisci, selezionare Manifesto per aprire l'editor del manifesto dell'API.
Impostare la proprietà accessTokenAcceptedVersion su 2.
Seleziona Salva.

Altre informazioni sul principio dei privilegi minimi durante la pubblicazione di autorizzazioni per un'API Web.

Configurare i ruoli dell'app

Un'API deve pubblicare almeno un ruolo dell'app per le applicazioni, detto anche Autorizzazione dell'applicazione, affinché le app client possano ottenere autonomamente un token di accesso. Le autorizzazioni dell'applicazione sono il tipo di autorizzazioni che le API devono pubblicare quando vogliono consentire alle applicazioni client di eseguire correttamente l'autenticazione in modo autonomo, senza richiedere l'accesso degli utenti. Per pubblicare un'autorizzazione dell'applicazione, seguire questa procedura:

Nella pagina Registrazioni app, selezionare l'applicazione creata, ad esempio ciam-ToDoList-api, per aprire la relativa pagina di Panoramica.
In Gestisci selezionare Ruoli dell'app.

Selezionare Crea un ruolo app, quindi immettere i valori seguenti e selezionare Applica per salvare le modifiche:

Proprietà	valore
Nome visualizzato	ToDoList.Read.All
Tipi di membro consentiti	Applicazioni
Valore	ToDoList.Read.All
Descrizione	Consente all'app di leggere l'elenco di attività di ogni utente tramite "TodoListApi"

Selezionare di nuovo Crea un ruolo app, immettere i valori seguenti per il secondo ruolo dell'app, quindi selezionare Applica per salvare le modifiche:

Proprietà	valore
Nome visualizzato	ToDoList.ReadWrite.All
Tipi di membro consentiti	Applicazioni
Valore	ToDoList.ReadWrite.All
Descrizione	Consente all'app di leggere e scrivere nell'elenco di attività di ogni utente tramite "TodoListApi"

Configurare le attestazioni facoltative

È possibile usare l'attestazione facoltativa idtyp per aiutare l'API Web a determinare se un token è un token dell'app o un token dell'app e dell'utente. Sebbene sia possibile usare una combinazione di attestazioni scp e roles per lo stesso scopo, l'uso dell'attestazione idtyp è il modo più semplice per distinguere un token dell'app da un token dell'app e dell'utente. Ad esempio, il valore di questa attestazione è app quando il token è un token solo di app.

Registrare l'app Web

Per consentire all'applicazione di accedere agli utenti con Microsoft Entra, Microsoft Entra per ID esterno deve essere a conoscenza dell'applicazione creata. La registrazione dell'app stabilisce una relazione di trust tra l'app e Microsoft Entra. Quando si registra un'applicazione, l'ID esterno genera un identificatore univoco noto come ID applicazione (client), un valore usato per identificare l'app durante la creazione di richieste di autenticazione.

I passaggi seguenti illustrano come registrare l'app nell'interfaccia di amministrazione di Microsoft Entra:

Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno uno sviluppatore di applicazioni.
Se si ha accesso a più tenant, usare l'iconaImpostazioni nel menu in alto per passare al tenant esterno dal menu Directory e sottoscrizioni.
Passare a Identità>Applicazioni>Registrazioni app.
Seleziona + Nuova registrazione.
Nella pagina Registra un'applicazione che viene visualizzata;
1. Immettere un Nome di un'applicazione significativa da mostrare agli utenti dell'app, ad esempio ciam-client-app.
2. In Tipi di account supportati selezionare Account solo in questa directory organizzativa.
Selezionare Registra.
Il riquadro Panoramica dell'applicazione viene visualizzato al termine della registrazione. Registrare l'ID applicazione (client) da usare nel codice sorgente dell'applicazione.

Per specificare il tipo di app per la registrazione dell'app, seguire questa procedura:

In Gestisci selezionare Autenticazione.
Nella pagina Configurazioni della piattaforma, selezionare Aggiungere una piattaforma, quindi selezionare l'opzione Web.
Per gli URI di reindirizzamento, immettere http://localhost:3000/auth/redirect.
Selezionare Configurare per salvare le modifiche.

Creare un segreto client

Creare un segreto client per l'applicazione registrata. L'applicazione usa il segreto client per dimostrare la propria identità quando richiede i token.

Nella pagina Registrazioni app, selezionare l'applicazione creata (come ad esempio ciam-client-app) per aprire la relativa pagina di Panoramica.
In Gestisci, selezionare Certificati e segreti.
Selezionare Nuovo segreto client.
Nella casella Descrizione, immettere una descrizione per il segreto client, (ad esempio, segreto client dell'app ciam).
In Scadenza, selezionare una durata per la quale il segreto è valido (in base alle regole di sicurezza dell'organizzazione), quindi selezionare Aggiungi.
Registrare il Valore del segreto. Questo valore verrà usato per la configurazione in un passaggio successivo. Il valore del segreto non verrà visualizzato di nuovo e non sarà recuperabile in alcun modo, una volta usciti da Certificati e segreti. Accertarsi di registrarlo.

Concedere le autorizzazioni per l'app all'API Web

Per concedere all'app client (ciam-client-app) le autorizzazioni API, seguire questa procedura:

Nella pagina Registrazioni app, selezionare l'applicazione creata (come ad esempio ciam-client-app) per aprire la relativa pagina di Panoramica.
In Gestisci selezionare Autorizzazioni API.
In Autorizzazioni configurate selezionare Aggiungi un'autorizzazione.
Selezionare la scheda API usate dall'organizzazione.
Nell'elenco delle API, selezionare l'API, ad esempio ciam-ToDoList-api.
Selezionare l'opzione Autorizzazioni delegate.
Nell'elenco delle autorizzazioni selezionare ToDoList.Read, ToDoList.ReadWrite. Usare la casella di ricerca, se necessario.
Selezionare il pulsante Aggiungi autorizzazioni. A questo punto, le autorizzazioni sono state assegnate correttamente. Poiché il tenant è un tenant del cliente, nemmeno gli utenti consumer stessi possono fornire il consenso a queste autorizzazioni. Per risolvere questo problema, l'amministratore deve fornire il consenso a queste autorizzazioni per conto di tutti gli utenti nel tenant:
1. Selezionare Concedi consenso amministratore per <nome del tenant>, quindi selezionare Sì.
2. Selezionare Aggiorna, quindi verificare che Concesso per <nome del tenant> venga visualizzato in Stato per entrambi gli ambiti.
Nell'elenco Autorizzazioni configurate, selezionare le autorizzazioni ToDoList.Read e ToDoList.ReadWrite, una alla volta, quindi copiare l'URI completo dell'autorizzazione per un uso successivo. L'URI completo delle autorizzazioni è simile a api://{clientId}/{ToDoList.Read} o api://{clientId}/{ToDoList.ReadWrite}.

Creare un flusso utente

Seguire questa procedura per creare un flusso utente che un cliente può usare per accedere o registrarsi a un'applicazione.

Accedere all'interfaccia di amministrazione di Microsoft Entra, almeno come Amministratore del flusso utente con ID esterno.
Se si ha accesso a più tenant, usare l'iconaImpostazioni nel menu in alto per passare al tenant esterno dal menu Directory e sottoscrizioni.
Passare a Identità>Identità esterne>Flussi utente.
Selezionare + Nuovo flusso utente.
Nella pagina Crea:
1. Immettere un Nome per il flusso utente, ad esempio SignInSignUpSample.
2. Nell'elenco Provider di identità, selezionare Account di posta elettronica. Questo provider di identità consente agli utenti di accedere o registrarsi usando il proprio indirizzo e-mail.
  
  Nota
  
  I provider di identità aggiuntivi verranno elencati qui solo dopo aver configurato la federazione con loro. Ad esempio, se si configura la federazione con Google o Facebook, sarà possibile selezionare tali provider di identità aggiuntivi qui.
3. In Account di posta elettronica, è possibile selezionare una delle due opzioni. Per questa esercitazione, selezionare E-mail con password.
  - E-mail con password: consente ai nuovi utenti di registrarsi e accedere usando un indirizzo e-mail come nome di accesso e una password come credenziale di primo fattore.
  - Passcode monouso per e-mail: consente ai nuovi utenti di registrarsi e accedere usando un indirizzo e-mail come nome di accesso e passcode monouso tramite e-mail come credenziale di primo fattore. Il passcode monouso per e-mail deve essere abilitato a livello di tenant (tutti i provider di identità>Passcode monouso per e-mail) affinché questa opzione sia disponibile a livello di flusso utente.
4. In Attributi utentescegliere gli attributi da raccogliere dall'utente al momento della registrazione. Selezionando Mostra altro, è possibile scegliere attributi e attestazioni per paese/area geografica, nome visualizzatoe codice postale. Seleziona OK. (Agli utenti vengono richiesti gli attributi solo quando si registrano per la prima volta)
Seleziona Crea. Il nuovo flusso utente viene visualizzato nell'elenco Flussi utente. Se necessario, aggiornare la pagina.

Per abilitare la reimpostazione della password self-service, seguire la procedura descritta nell'articolo Abilitare la reimpostazione della password self-service.

Associare l'applicazione Web al flusso utente

Anche se molte applicazioni possono essere associate al flusso utente, una singola applicazione può essere associata a un solo flusso utente. Un flusso utente consente la configurazione dell'esperienza utente per applicazioni specifiche. Ad esempio, è possibile configurare un flusso utente che richiede agli utenti di accedere o registrarsi con l'indirizzo di posta elettronica.

Nel menu della barra laterale, selezionare Identità.
Selezionare Identità esterne, quindi Flussi utente.
Nella pagina Flussi utente, selezionare il nome del flusso utente creato in precedenza, ad esempio SignInSignUpSample.
In Usa, selezionare Applicazioni.
Seleziona Aggiungi applicazione.
Selezionare l'applicazione dall'elenco, ad esempio ciam-client-app o usare la casella di ricerca per trovare l'applicazione e quindi selezionarla.
Scegli Seleziona.

Clonare o scaricare un'applicazione Web di esempio e un'API Web

Per ottenere l'applicazione di esempio, è possibile clonarla da GitHub o scaricarla come file ZIP.

Per clonare l'esempio, aprire un prompt dei comandi e passare alla posizione in cui si vuole creare il progetto e immettere il comando seguente:
```
git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
```
Scaricare il file ZIP. Estrarlo in un percorso di file in cui la lunghezza del nome è inferiore a 260 caratteri.

Installare le dipendenze del progetto

Aprire una finestra della console e passare alla directory contenente l'app di esempio Node.js/Express:
```
cd 2-Authorization\4-call-api-express\App
```
Eseguire i comandi seguenti per installare le dipendenze dell'app Web:
```
npm install && npm update
```

Configurare l'app Web e l'API di esempio

Per usare la registrazione dell'app nell'esempio di app Web client:

Nell'editor di codice, aprire il file App\authConfig.js.
Trovare il segnaposto:
- Enter_the_Application_Id_Here e sostituirlo con l'ID applicazione (client) dell’app registrata precedentemente.
- Enter_the_Tenant_Subdomain_Here e sostituirlo con il sottodominio della directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se non si ha il nome del tenant, vedere come leggere i dettagli del tenant.
- Enter_the_Client_Secret_Here e sostituirlo con il valore del segreto dell'app copiato in precedenza.
- Enter_the_Web_Api_Application_Id_Here e sostituirlo con l'ID applicazione (client) dell'API Web copiata in precedenza.

Per usare la registrazione dell'app nell'esempio di API Web:

Nell'editor di codice, aprire il file API\ToDoListAPI\appsettings.json.
Trovare il segnaposto:
- Enter_the_Application_Id_Here e sostituirlo con l'ID applicazione (client) dell'API Web copiata.
- Enter_the_Tenant_Id_Here e sostituirlo con l'ID directory (tenant) copiato in precedenza.
- Enter_the_Tenant_Subdomain_Here e sostituirlo con il sottodominio della directory (tenant). Ad esempio, se il dominio primario del tenant è contoso.onmicrosoft.com, usare contoso. Se non si ha il nome del tenant, vedere come leggere i dettagli del tenant.

Eseguire e testare un'app Web e un'API di esempio

Aprire una finestra della console, quindi eseguire l'API Web usando i comandi seguenti:
```
cd 2-Authorization\4-call-api-express\API\ToDoListAPI
dotnet run
```
Eseguire il client dell'app Web usando i comandi seguenti:
```
cd 2-Authorization\4-call-api-express\App
npm start
```
Aprire il browser, quindi passare a http://localhost:3000.
Per accedere, selezionare il pulsante Accedi. Viene richiesto di accedere.
Nella pagina di accesso digitare l'Indirizzo e-mail, selezionare Avanti, digitare la Password, quindi selezionare Accedi. Se non si ha un account, selezionare il collegamento Nessun account? Creane uno per avviare il flusso di registrazione.
Se si sceglie l'opzione per iscriversi, dopo aver compilato l'indirizzo e-mail, il passcode monouso, la nuova password e altri dettagli dell'account, completare l'intero flusso di iscrizione. Si dovrebbe visualizzare una pagina simile a quella raffigurata nello screenshot seguente. Se si sceglie l'opzione di accesso, viene visualizzata una pagina simile.

Call API (Chiama API)

Per chiamare l'API, selezionare il collegamento Visualizza l'elenco di attività da completare. Si dovrebbe visualizzare una pagina simile a quella raffigurata nello screenshot seguente.
Modificare l'elenco attività creando e rimuovendo elementi.

Funzionamento

Si attiva una chiamata API ogni volta che si visualizza, si aggiunge o si rimuove un'attività. Ogni volta che si attiva una chiamata API, l'app Web client acquisisce un token di accesso con le autorizzazioni necessarie (ambiti) per chiamare un endpoint API. Ad esempio, per leggere un'attività, l'app Web client deve acquisire un token di accesso con ToDoList.Read autorizzazione/ambito.

L'endpoint dell'API Web deve verificare se le autorizzazioni o gli ambiti nel token di accesso, forniti dall'app client, sono validi. Se il token di accesso è valido, l'endpoint risponde alla richiesta HTTP; in caso contrario, risponde con un errore HTTP 401 Unauthorized.

Condividi tramite

Prerequisiti