Condividi tramite

Configurare un'applicazione per esporre un'API Web

In questa guida pratica si registrerà un'API Web con Microsoft Identity Platform ed esporla 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 responsabile all'applicazione

  1. Nella registrazione dell'app, sotto Gestisci, 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 un proprietario sia assegnato all'applicazione API che all'applicazione a cui si vogliono aggiungere autorizzazioni, altrimenti l'API non verrà elencata quando si richiedono autorizzazioni API.

Assegnare il ruolo dell'app

  1. Nella registrazione dell'app, sotto Gestisci, selezionare Ruoli dell'app, e Crea un ruolo per l'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 Descrizione Esempio
    Nome visualizzato Nome del ruolo dell'app Registrazioni 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

Una volta registrata l'API Web, assegnato un ruolo di app e un proprietario, è possibile aggiungere scopi al codice dell'API per fornire autorizzazioni granulari ai consumatori.

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 Descrizione Esempio
    Nome dell'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 del consenso dell'amministratore Breve descrizione dello scopo dell'ambito che verrà visualizzata solo dagli amministratori. Accesso in sola lettura ai record dei dipendenti
    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ù in dettaglio 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-autorizza solo le applicazioni client attendibili, perché i tuoi utenti non avranno la possibilità di rifiutare il consenso.

    1. In Applicazioni client autorizzate selezionare Aggiungi applicazione client.
    2. Immettere l'ID applicazione (client) dell'applicazione client che si desidera 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 (PCA) e agli utenti non verrà richiesto il consenso quando vi accedono.

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 dell'ambito Employees.Write.All
Utenti che possono fornire il consenso Solo amministratori
Nome visualizzato del consenso dell'amministratore Accesso in scrittura ai record dei dipendenti
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 pannello Mostra un'API che visualizza due ambiti esposti.

La stringa completa dell'ambito è la concatenazione dell'URI ID applicazione della tua API Web e del nome 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 dichiarazione 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 hai esposto la tua API Web configurandone gli ambiti, configura la registrazione dell'app client con il permesso di accedervi.

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