API Web protetta: registrazione dell'app

  • Articolo

Questo articolo illustra le specifiche della registrazione delle app per un'API Web protetta.

Per i passaggi comuni per registrare un'app, vedere Guida introduttiva: Registrare un'applicazione con Microsoft Identity Platform.

Versione del token accettata

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

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

  • Se il valore 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 accettato può essere v1.0.

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

  1. Nella portale di Azure 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 i 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:

  • URI della risorsa
  • Uno o più ambiti
  • Uno o più ruoli dell'app

Per impostazione predefinita, il portale di registrazione dell'applicazione consiglia di usare l'URI api://{clientId}della risorsa . 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 illustrato da un utente.
  • Come illustrato 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 stesso). Un amministratore tenant dovrà fornire il consenso alle applicazioni client dell'API Web che espone i ruoli dell'app. Per informazioni dettagliate, vedere Amministrazione consenso.

Esporre 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 dell'ID applicazione proposto (api://< clientId>) (se richiesto)
  • Nome ambito: access_as_user
  • Chi può fornire il consenso: Amministrazione e utenti
  • Amministrazione nome visualizzato del consenso: Accedere a TodoListService come utente
  • Amministrazione descrizione del consenso: accede all'API Web TodoListService come utente
  • Nome visualizzato consenso utente: Accesso a TodoListService come utente
  • Descrizione del 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 le 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 la procedura descritta 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 del manifesto dell'applicazione come descritto nell'articolo.

Limitare i token di accesso a 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 esequisi i token di sicurezza solo per le 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 Applicazioni> di identità>Registrazioni app.
  2. Nella pagina di panoramica dell'applicazione 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: Nome <> applicazione non assegnato a un ruolo per l'API <>Web.

Avviso

DO NOT use AADSTS error codes or their message strings as literals in your application's code.DO NOT use AADSTS error codes or their message strings as literals in your application's code. I codici di errore "AADSTS" e le stringhe dei messaggi di errore restituiti 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.

Passaggi successivi

L'articolo successivo di questa serie è Configurazione del codice dell'app.