Condividi tramite

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

  • Articolo

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 di proprietario e app, è possibile fornire l'accesso basato sulle autorizzazioni per le relative risorse agli utenti autorizzati e alle app client che accedono all'API.

Prerequisiti

Registrare l'API Web

L'accesso alle API richiede la configurazione degli ambiti dell'accesso e dei ruoli. Per esporre le API Web dell'applicazione di risorse alle applicazioni client, configurare gli ambiti dell'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.

  1. Accedere all'Interfaccia di amministrazione di Microsoft Entra almeno come Amministratore applicazione cloud.
  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. Eseguire i passaggi per registrare un'applicazione e 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 all'applicazione

  1. In Gestisci nella registrazione dell'app selezionare Proprietari e Aggiungi proprietari.
  2. Nella nuova finestra trovare e selezionare uno o più 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 sia l'applicazione a cui si vogliono aggiungere autorizzazioni abbiano un proprietario, altrimenti l'API non verrà elencata quando si richiedono autorizzazioni API.

Assegnare il ruolo dell'app

  1. In Gestisci nella registrazione dell'app selezionare Ruoli dell'app e Crea un ruolo app.

  2. Specificare quindi gli attributi del ruolo app nel riquadro Crea un 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 dei dipendenti
    Tipi di membro consentiti Specifica se il ruolo dell'app può essere assegnato a utenti/gruppi e/o applicazioni Applicazioni
    valore Valore visualizzato nell'attestazione "roles" 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 e quindi selezionare Applica.

Aggiungere un ambito

Suggerimento

La procedura descritta in questo articolo può variare leggermente in base al portale di partenza.

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

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. Seleziona Esponi un'API.

  2. Nella parte superiore della pagina selezionare Aggiungi accanto a URI ID applicazione. Il valore predefinito è api://<application-client-id>. 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. Seleziona Salva.

  3. Selezionare Aggiungi un ambito:

    Riquadro Esporre un'API di una registrazione dell'app nel portale di Azure

  4. 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. Gli amministratori devono essere usati solo per le 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. Accesso in sola lettura ai record Employee
    Descrizione del consenso amministratore Descrizione più dettagliata dell'autorizzazione concessa dall'ambito che verrà visualizzata solo dagli amministratori. Consentire all'applicazione di avere accesso in sola lettura a tutti i dati employee.
    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. Accesso in sola lettura ai record dei dipendenti
    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. Consentire all'applicazione di avere accesso in sola lettura ai dati dei dipendenti.
    Stato Indica se l'ambito è abilitato o disabilitato. Abilitato

  5. Seleziona Aggiungi ambito.

  6. (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 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 Employees.Write.All di esempio, seguire la procedura descritta nella sezione Aggiungere un ambito e specificare questi valori nel riquadro Aggiungi un ambito . Al termine, selezionare Aggiungi ambito :

Campo Valore di esempio
Nome ambito Employees.Write.All
Utenti che possono fornire il consenso Solo amministratori
Nome visualizzato per il consenso amministratore Accesso in scrittura ai record employee
Descrizione del consenso amministratore Consentire all'applicazione di avere accesso in scrittura a tutti i dati employee.
Nome visualizzato per il consenso utente Nessuno (lasciare vuoto)
Descrizione del consenso utente Nessuno (lasciare vuoto)
Stato Abilitato

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:

Screenshot del riquadro Esporre un'API che mostra due ambiti esposti.

La stringa completa dell'ambito è la concatenazione dell'URI ID applicazione dell'API Web e del 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.

Passaggio successivo

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