API Web protetta: registrazione dell’app

  • Articolo

Questo articolo illustra come registrare un'applicazione per un'API Web protetta.

Per i passaggi comuni per registrare un’app, vedere Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

Versione accettata del token

Microsoft Identity Platform può emettere token v1.0 e token v2.0. Per altre informazioni su questi tipi di token, vedere Token di accesso.

La versione del token che l'API può accettare dipende dalla selezione di Tipi di account supportati quando si crea la registrazione dell'applicazione API Web nel portale di Azure.

  • ll valore dei Tipi di account supportati è Account in qualsiasi directory organizzativa e account Microsoft personali (ad esempio Skype, Xbox, Outlook.com), la versione del token accettata deve essere v2.0.
  • In caso contrario, la versione del token accettata può essere v1.0.

Dopo aver creato l'applicazione, è possibile determinare o modificare la versione del token accettata seguendo questa procedura:

  1. Nell'interfaccia di amministrazione di Microsoft Entra, selezionare l'app e quindi selezionare Manifesto.
  2. Trovare la proprietà accessTokenAcceptedVersion nel manifesto.
  3. Il valore specifica a Microsoft Entra quale versione del token accetta l'API Web.
    • Se il valore è 2, l'API Web accetta i token v2.0.
    • Se il valore è null, l’API Web accetta token v1.0.
  4. Se è stata modificata la versione del token, selezionare Salva.

L'API Web specifica la versione del token accettata. Quando un client richiede un token per l'API Web da Microsoft Identity Platform, il client ottiene un token che indica quale versione del token accetta l'API Web.

Nessun URI di reindirizzamento

Le API Web non devono registrare un URI di reindirizzamento perché nessun utente ha eseguito l'accesso interattivo.

API esposta

Altre impostazioni specifiche delle API Web sono l'API esposta e gli ambiti esposti o i ruoli dell'app.

Ambiti e URI ID applicazione

Gli ambiti hanno in genere il formato resourceURI/scopeName. Per Microsoft Graph, gli ambiti hanno collegamenti. 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 di usare 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 visualizzato da un amministratore tenant, che può concedere il consenso dell'amministratore.

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 stessa). Un amministratore tenant dovrà fornire il consenso alle applicazioni client dell'API Web che espone i ruoli dell'app. 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: access_as_user
  • 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 dell'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 alle app client approvate per l'accesso alle 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 in Identità>Applicazioni>Registrazioni 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\>_.

Avviso

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 Entra di Microsoft sono non immutabili 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.

Passaggio successivo

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