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

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:

    An app registration's Expose an API pane in the Azure portal

  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 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:

Screenshot of the Expose an API pane showing two exposed scopes.

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