Esporre gli ambiti in un'API Web protetta

Si applica a: Inquilini della forza lavoro (altre informazioni)

Questo articolo illustra come aggiungere ambiti a un'applicazione per un'API Web protetta.

Prerequisiti

• Registrare una nuova app nell'interfaccia di amministrazione di Microsoft Entra, configurata solo per gli account in questa directory organizzativa. Per altri dettagli, vedere Registrare un'applicazione . Registrare i valori seguenti dalla pagina Panoramica dell'applicazione per usarli in un secondo momento:
  • ID applicazione (cliente)
  • ID della directory (cliente)

Ambiti e URI ID dell'applicazione

Gli ambiti hanno in genere il formato resourceURI/scopeName. Per Microsoft Graph, gli ambiti hanno scorciatoie. Ad esempio, User.Read è un collegamento per https://graph.microsoft.com/user.read.

Durante la registrazione dell'app, definire questi parametri:

• L’URI della risorsa
• Uno o più ambiti
• Un o più ruoli dell’app

Per impostazione predefinita, il portale di registrazione dell'applicazione consiglia di usare l'URI della risorsa api://{clientId}. Questo URI è univoco ma non leggibile. Se si modifica l'URI, assicurarsi che il nuovo valore sia univoco. Il portale di registrazione dell'applicazione garantisce l'uso di un dominio di pubblicazione configurato.

Per le applicazioni client, gli ambiti vengono visualizzati come autorizzazioni delegate e i ruoli dell'app vengono visualizzati come autorizzazioni dell'applicazione per l'API Web.

Gli ambiti vengono visualizzati anche nella finestra di consenso presentata agli utenti dell'app. Specificare pertanto le stringhe corrispondenti che descrivono l'ambito:

• Come visualizzato da un utente.
• Come visto da un amministratore del tenant, che può concedere il consenso amministrativo.

I ruoli dell'app non possono essere autorizzati da un utente (perché vengono usati da un'applicazione che chiama l'API Web per conto di se stesso). Un amministratore tenant deve fornire il consenso alle applicazioni client della tua API Web che espongono i ruoli applicativi. Per informazioni dettagliate, vedere Consenso amministratore.

Esporre le autorizzazioni delegate (ambiti)

Per esporre autorizzazioni delegate o ambiti, seguire la procedura descritta in Configurare un'applicazione per esporre un'API Web.

Se si segue lo scenario dell'API Web descritto in questo set di articoli, usare queste impostazioni:

• URI ID applicazione: accettare l’URI ID applicazione proposto (api://<clientId>) (se richiesto)
• Nome ambito: accesso_come_utente
• Chi può fornire il consenso: Amministratori e utenti
• Nome visualizzato per il consenso amministratore: Accedere a TodoListService come utente
• Descrizione consenso amministratore: Accede all’API Web TodoListService come utente
• Nome visualizzato per il consenso utente: Accedere a TodoListService come utente
• Descrizione consenso utente: Accede all’API Web TodoListService come utente
• Stato: Abilitato

Suggerimento

Per l'URI ID applicazione, è possibile impostarlo sull'autorità fisica dell'API, ad esempio https://graph.microsoft.com. Ciò può essere utile se l'URL dell'API che deve essere chiamato è noto.

Se l'API Web viene chiamata da un servizio o da un'app daemon

Esporre autorizzazioni dell'applicazione anziché le autorizzazioni delegate se l'API deve essere accessibile da daemon, servizi o altre applicazioni non interattive (da parte di un utente). Poiché le applicazioni di tipo daemon e di servizio eseguono l'autenticazione automatica con la propria identità, non esiste alcun utente a "delegare" l'autorizzazione.

Esporre le autorizzazioni dell'applicazione (ruoli dell'app)

Per esporre le autorizzazioni dell'applicazione, seguire i passaggi descritti in Aggiungere ruoli dell'app all'app.

Nel riquadro Crea ruolo app in Tipi di membri consentiti, selezionare Applicazioni. In alternativa, aggiungere il ruolo usando l'Editor manifesto dell'applicazione come descritto nell'articolo.

Limitare i token di accesso ad app client specifiche

I ruoli dell'app sono il meccanismo usato dallo sviluppatore di applicazioni per esporre le autorizzazioni dell'app. Il codice dell'API Web deve verificare la presenza di ruoli dell'app nei token di accesso ricevuti dai chiamanti.

Per aggiungere un altro livello di sicurezza, un amministratore tenant di Microsoft Entra può configurare il tenant in modo che Microsoft Identity Platform rilascia token di sicurezza solo per le app client approvate dall'amministratore tenant per l'accesso all'API.

Per aumentare la sicurezza limitando il rilascio dei token solo alle app client a cui sono stati assegnati ruoli dell'app:

1. Nell'interfaccia di amministrazione di Microsoft Entra selezionare l'app inRegistrazioni per l'app>.
2. Nella pagina Panoramica dell'applicazione, in Essentials individuare e selezionare il collegamento Applicazione gestita nella directory locale per passare alla relativa pagina Panoramica dell'applicazione aziendale.
3. In Gestione selezionare Proprietà.
4. Impostare Assegnazione obbligatoria? su Sì.
5. Seleziona Salva.

Microsoft Entra ID verificherà ora le assegnazioni di ruolo dell'app delle applicazioni client che richiedono token di accesso per l'API Web. Se a un'app client non sono stati assegnati ruoli dell'app, Microsoft Entra ID restituisce un messaggio di errore al client simile a _invalid_client: AADSTS501051: Application \<application name\> isn't assigned to a role for the \<web API\>_.

Avvertimento

NON usare codici di errore AADSTS o le relative stringhe di messaggio come valori letterali nel codice dell'applicazione. I codici di errore "AADSTS" e le stringhe di messaggio di errore restituite dall'ID Microsoft Entra non sono modificabili*, e possono essere modificati da Microsoft in qualsiasi momento e senza la propria conoscenza. Se si effettuano decisioni di diramazione nel codice in base ai valori dei codici AADSTS o delle relative stringhe di messaggio, si mette a rischio la funzionalità e la stabilità dell'applicazione.

Passo successivo

L’articolo successivo in questo scenario è Configurazione del codice dell’app.