Guida introduttiva: Configurare un'applicazione per esporre un'API Web

In questa guida introduttiva si registrerà un'API Web con Microsoft Identity Platform e la si esporrà alle app client aggiungendo un ambito. Registrando l'API Web ed esponendola tramite ambiti, assegnando un ruolo proprietario e app, è possibile fornire l'accesso basato sulle autorizzazioni alle relative risorse agli utenti autorizzati e alle app client che accedono all'API.

Prerequisiti

• Un account Azure con una sottoscrizione attiva (creare un account gratuito)
• Completamento della guida introduttiva: Configurare un tenant

Registrare l'API Web

L'accesso alle API richiede la configurazione di ruoli e ambiti di accesso. Per esporre le API Web dell'applicazione di risorse alle applicazioni client, configurare gli ambiti di accesso e i ruoli per l'API. Per consentire a un'applicazione client di accedere a un'API Web, configurare le autorizzazioni per accedere all'API nella registrazione dell'app.

Per fornire l'accesso con ambito alle risorse nell'API Web, è prima di tutto necessario registrare l'API con Microsoft Identity Platform.

Seguire questa procedura nella sezione Registrare un'applicazione di Avvio rapido: Registrare un'app con Microsoft Identity Platform.

Ignorare la sezione URI di reindirizzamento (facoltativo). Non è necessario configurare un URI di reindirizzamento per un'API Web perché nessun utente è connesso in modo interattivo.

Assegnare il proprietario dell'applicazione

1. Nella registrazione dell'app, in Gestisci selezionare Proprietari e Aggiungi proprietari.
2. Nella nuova finestra trovare e selezionare i proprietari da assegnare all'applicazione. I proprietari selezionati vengono visualizzati nel pannello destro. Al termine, confermare con Seleziona. I proprietari dell'app verranno ora visualizzati nell'elenco del proprietario.

Nota

Assicurarsi che sia l'applicazione API che l'applicazione che si vuole aggiungere autorizzazioni a entrambi dispongono di un proprietario, altrimenti l'API non verrà elencata quando si richiedono autorizzazioni API.

Assegnare il ruolo dell'app

1. Nella registrazione dell'app, in Gestisci selezionare Ruoli app e Crea ruolo app.

2. Specificare quindi gli attributi del ruolo app nel riquadro Crea ruolo app. Per questa procedura dettagliata è possibile usare i valori di esempio o specificare valori personalizzati.

   Campo	Description	Esempio
   Nome visualizzato	Nome del ruolo dell'app	Record dipendenti
   Tipi di membri consentiti	Specifica se il ruolo dell'app può essere assegnato a utenti/gruppi e/o applicazioni	Applicazioni
   valore	Valore visualizzato nell'attestazione "ruoli" di un token	Employee.Records
   Descrizione	Descrizione più dettagliata del ruolo dell'app	Le applicazioni hanno accesso ai record dei dipendenti

3. Selezionare la casella di controllo per abilitare il ruolo dell'app.

Con l'API Web registrata, a cui è stato assegnato un ruolo e un proprietario dell'app, è possibile aggiungere ambiti al codice dell'API in modo che possa fornire autorizzazioni granulari per i consumer.

Aggiungere un ambito

Suggerimento

I passaggi descritti in questo articolo possono variare leggermente in base al portale da cui si inizia.

Per richiedere l'autorizzazione per eseguire le operazioni definite dall'API Web, il codice in un'applicazione client passa un token di accesso unitamente alle relative richieste alla risorsa protetta, ovvero l'API Web. L'API Web esegue quindi l'operazione richiesta solo se il token di accesso ricevuto contiene gli ambiti necessari per l'operazione.

Seguire innanzitutto questa procedura per creare un ambito di esempio denominato Employees.Read.All:

1. Accedere all'interfaccia di amministrazione di Microsoft Entra come almeno un'applicazione cloud Amministrazione istrator.

2. Se si ha accesso a più tenant, usare l'icona Impostazioni nel menu in alto per passare al tenant contenente la registrazione dell'app dal menu Directory e sottoscrizioni.

3. Passare a Identity>Applications> Registrazioni app e quindi selezionare la registrazione dell'app dell'API.

4. Selezionare Esporre un'API

5. Selezionare Aggiungi accanto all'URI ID applicazione se non ne è ancora stato configurato uno.

   È possibile usare il valore predefinito di api://<application-client-id> o un altro modello URI ID app supportato. L'URI dell'ID applicazione funge da prefisso per gli ambiti a cui verrà fatto riferimento nel codice dell'API e deve essere univoco a livello globale.

6. Selezionare Aggiungi un ambito:

   

7. Specificare quindi gli attributi dell'ambito nel riquadro Aggiungi un ambito. Per questa procedura dettagliata è possibile usare i valori di esempio o specificare valori personalizzati.

   Campo	Description	Esempio
   Nome ambito	Nome dell'ambito. Una convenzione di denominazione standard è resource.operation.constraint.	Employees.Read.All
   Utenti che possono fornire il consenso	Indica se il consenso per l'ambito può essere fornito dagli utenti oppure se è necessario il consenso amministratore. Selezionare Solo amministratori per autorizzazioni con privilegi più elevati.	Amministratori e utenti
   Nome visualizzato per il consenso amministratore	Breve descrizione dello scopo dell'ambito che verrà visualizzata solo dagli amministratori.	Read-only access to Employee records
   Descrizione del consenso amministratore	Descrizione più dettagliata dell'autorizzazione concessa dall'ambito che verrà visualizzata solo dagli amministratori.	Allow the application to have read-only access to all Employee data.
   Nome visualizzato per il consenso utente	Breve descrizione dello scopo dell'ambito. Viene visualizzata agli utenti solo se si imposta Utenti autorizzati al consenso su Amministratori e utenti.	Read-only access to your Employee records
   Descrizione del consenso utente	Descrizione più dettagliata dell'autorizzazione concessa dall'ambito. Viene visualizzata agli utenti solo se si imposta Utenti autorizzati al consenso su Amministratori e utenti.	Allow the application to have read-only access to your Employee data.

8. Impostare Stato su Abilitato e quindi selezionare Aggiungi ambito.

9. (Facoltativo) Per rimuovere la richiesta del consenso degli utenti dell'app per gli ambiti definiti, è possibile pre-autorizzare l'accesso dell'applicazione client all'API Web. Pre-autorizzare solo le applicazioni client attendibili, perché gli utenti non hanno la possibilità di rifiutare il consenso.

   1. In Applicazioni client autorizzate selezionare Aggiungi applicazione client
   2. Immettere il valore di ID applicazione (client) dell'applicazione client da pre-autorizzare, ad esempio quello di un'applicazione Web già registrata.
   3. In Ambiti autorizzatiselezionare gli ambiti per cui rimuovere la richiesta di consenso, quindi selezionare Aggiungi applicazione.

   Se è stato eseguito questo passaggio facoltativo, l'app client è ora un'app client pre-autorizzata e agli utenti non verrà richiesto il consenso per accedervi.

Aggiungere un ambito che richiede il consenso dell'amministratore

Aggiungere quindi un altro ambito di esempio denominato Employees.Write.All per il quale solo gli amministratori possono concedere il consenso. Gli ambiti che richiedono il consenso dell'amministratore vengono usati in genere per fornire l'accesso a operazioni con privilegi più elevati e spesso da applicazioni client che vengono eseguite come servizi back-end o daemon che non eseguono l'accesso utente interattivo.

Per aggiungere l'ambito di esempio Employees.Write.All, seguire la procedura descritta nella sezione Aggiungere un ambito e specificare questi valori nel riquadro Aggiungi un ambito:

Campo	Valore di esempio
Nome ambito	Employees.Write.All
Utenti che possono fornire il consenso	Solo amministratori
Nome visualizzato per il consenso amministratore	Write access to Employee records
Descrizione del consenso amministratore	Allow the application to have write access to all Employee data.
Nome visualizzato per il consenso utente	Nessuno (lasciare vuoto)
Descrizione del consenso utente	Nessuno (lasciare vuoto)

Impostare Stato su Abilitato e quindi selezionare Aggiungi ambito.

Verificare gli ambiti esposti

Se sono stati aggiunti entrambi gli ambiti di esempio descritti nelle sezioni precedenti, questi verranno visualizzati nel riquadro Esporre un'API della registrazione dell'app dell'API Web, simile all'immagine seguente:

Come illustrato nell'immagine, la stringa completa di un ambito è costituita dalla concatenazione del valore URI ID applicazione dell'API Web e del valore di Nome ambito dell'ambito.

Se, ad esempio, l'URI ID applicazione dell'API Web è https://contoso.com/api e il nome dell'ambito è Employees.Read.All, l'ambito completo è:

https://contoso.com/api/Employees.Read.All

Uso degli ambiti esposti

Nell'articolo successivo di questa serie viene configurata la registrazione di un'app client con accesso all'API Web e gli ambiti definiti seguendo i passaggi descritti in questo articolo.

Una volta concessa la registrazione di un'app client per accedere all'API Web, il client può essere rilasciato un token di accesso OAuth 2.0 da Identity Platform. Quando il client chiama l'API Web, presenta un token di accesso con attestazione di ambito (scp) impostata sulle autorizzazioni specificate nella registrazione dell'app del client.

Se necessario, è possibile esporre altri ambiti successivamente. Tenere presente che l'API Web può esporre più ambiti associati a operazioni diverse. La risorsa può controllare l'accesso all'API Web in fase di esecuzione valutando le attestazioni di ambito (scp) nel token di accesso OAuth 2.0 ricevuto.

Passaggi successivi

Ora che l'API Web è stata esposta configurandone gli ambiti, configurare la registrazione dell'app client con l'autorizzazione per accedere agli ambiti.

Configurare la registrazione di un'app per l'accesso all'API Web