API per il Web

Avvertimento

Questo contenuto riguarda l'endpoint di Azure AD v1.0 precedente. Usare l' Microsoft Identity Platform per i nuovi progetti.

Le app per le API Web sono applicazioni Web che devono ottenere risorse da un'API Web. In questo scenario, esistono due tipi di identità che l'applicazione Web può usare per autenticare e chiamare l'API Web:

• Identità dell'applicazione : questo scenario usa le credenziali client OAuth 2.0 per l'autenticazione come applicazione e l'accesso all'API Web. Quando si usa un'identità dell'applicazione, l'API Web può rilevare solo che l'applicazione Web la chiama, perché l'API Web non riceve informazioni sull'utente. Se l'applicazione riceve informazioni sull'utente, verrà inviata tramite il protocollo dell'applicazione e non è firmata da Azure AD. L'API Web considera attendibile l'autenticazione dell'utente da parte dell'applicazione Web. Per questo motivo, questo modello è denominato sottosistema attendibile.
• Identità utente delegata : questo scenario può essere eseguito in due modi: OpenID Connect e concessione del codice di autorizzazione OAuth 2.0 con un client riservato. L'applicazione Web ottiene un token di accesso per l'utente, che dimostra all'API Web che l'utente ha autenticato correttamente nell'applicazione Web e che l'applicazione Web è stata in grado di ottenere un'identità utente delegata per chiamare l'API Web. Questo token di accesso viene inviato nella richiesta all'API Web, che autorizza l'utente e restituisce la risorsa desiderata.

Sia l'identità dell'applicazione che i tipi di identità utente delegati sono descritti nel flusso seguente. La differenza principale tra di esse è che l'identità utente delegata deve prima acquisire un codice di autorizzazione prima che l'utente possa accedere e ottenere l'accesso all'API Web.

Diagramma

Flusso del protocollo

Identità dell'applicazione con concessione di credenziali client OAuth 2.0

1. Un utente ha eseguito l'accesso ad Azure AD nell'applicazione Web (vedere la sezione App Web per altre informazioni).
2. L'applicazione Web deve acquisire un token di accesso in modo che possa eseguire l'autenticazione all'API Web e recuperare la risorsa desiderata. Effettua una richiesta all'endpoint del token di Azure AD, fornendo la credenziale, l'ID applicazione e l'URI dell'ID dell'applicazione del Web API.
3. Azure AD autentica l'applicazione e restituisce un token di accesso JWT usato per chiamare l'API Web.
4. Tramite HTTPS, l'applicazione Web usa il token di accesso JWT restituito per aggiungere la stringa JWT con una designazione "Bearer" nell'intestazione authorization della richiesta all'API Web. L'API Web convalida quindi il token JWT e, se la convalida ha esito positivo, restituisce la risorsa desiderata.

Identità utente delegata con OpenID Connect

1. Un utente ha eseguito l'accesso a un'applicazione Web usando Azure AD (vedere la sezione Web Browser to Web Application precedente). Se l'utente dell'applicazione Web non ha ancora acconsentito a consentire all'applicazione Web di chiamare l'API Web per suo conto, l'utente dovrà fornire il consenso. L'applicazione visualizzerà le autorizzazioni necessarie e, se una di queste sono autorizzazioni a livello di amministratore, un utente normale nella directory non sarà in grado di fornire il consenso. Questo processo di consenso si applica solo alle applicazioni multi-tenant, non alle applicazioni a tenant singolo, perché l'applicazione avrà già le autorizzazioni necessarie. Quando l'utente ha eseguito l'accesso, l'applicazione Web ha ricevuto un token ID con informazioni sull'utente, nonché un codice di autorizzazione.
2. Usando il codice di autorizzazione rilasciato da Azure AD, l'applicazione Web invia una richiesta all'endpoint del token di Azure AD che include il codice di autorizzazione, i dettagli sull'applicazione client (ID applicazione e URI di reindirizzamento) e la risorsa desiderata (URI ID applicazione per l'API Web).
3. Il codice di autorizzazione e le informazioni sull'applicazione Web e sull'API Web vengono convalidati da Azure AD. Al termine della convalida, Azure AD restituisce due token: un token di accesso JWT e un token di aggiornamento JWT.
4. Tramite HTTPS, l'applicazione Web usa il token di accesso JWT restituito per aggiungere la stringa JWT con una designazione "Bearer" nell'intestazione authorization della richiesta all'API Web. L'API Web convalida quindi il token JWT e, se la convalida ha esito positivo, restituisce la risorsa desiderata.

Identità utente delegata con concessione del codice di autorizzazione OAuth 2.0

1. Un utente ha già eseguito l'accesso a un'applicazione Web, il cui meccanismo di autenticazione è indipendente da Azure AD.
2. L'applicazione Web richiede un codice di autorizzazione per acquisire un token di accesso, quindi invia una richiesta tramite il browser all'endpoint di autorizzazione di Azure AD, fornendo l'ID applicazione e l'URI di reindirizzamento per l'applicazione Web dopo aver completato l'autenticazione. L'utente accede ad Azure AD.
3. Se l'utente dell'applicazione Web non ha ancora acconsentito a consentire all'applicazione Web di chiamare l'API Web per suo conto, l'utente dovrà fornire il consenso. L'applicazione visualizzerà le autorizzazioni necessarie e, se una di queste sono autorizzazioni a livello di amministratore, un utente normale nella directory non sarà in grado di fornire il consenso. Questo consenso si applica sia alle applicazioni mono-tenant che a quelle multi-tenant. Nel caso di tenant singolo, un amministratore può fornire il consenso amministrativo per conto degli utenti. A tale scopo, usare il Grant Permissions pulsante nel portale di Azure.
4. Dopo il consenso dell'utente, l'applicazione Web riceve il codice di autorizzazione che deve acquisire un token di accesso.
5. Usando il codice di autorizzazione rilasciato da Azure AD, l'applicazione Web invia una richiesta all'endpoint del token di Azure AD che include il codice di autorizzazione, i dettagli sull'applicazione client (ID applicazione e URI di reindirizzamento) e la risorsa desiderata (URI ID applicazione per l'API Web).
6. Il codice di autorizzazione e le informazioni sull'applicazione Web e sull'API Web vengono convalidati da Azure AD. Al termine della convalida, Azure AD restituisce due token: un token di accesso JWT e un token di aggiornamento JWT.
7. Tramite HTTPS, l'applicazione Web usa il token di accesso JWT restituito per aggiungere la stringa JWT con una designazione "Bearer" nell'intestazione authorization della richiesta all'API Web. L'API Web convalida quindi il token JWT e, se la convalida ha esito positivo, restituisce la risorsa desiderata.

Esempi di codice

Vedere gli esempi di codice per scenari di applicazione Web a API Web. Consultare spesso -- vengono aggiunti nuovi campioni frequentemente. Da applicazione Web all'API Web.

Registrazione dell'app

Per registrare un'applicazione con l'endpoint di Azure AD v1.0, vedere Registrare un'app.

• Tenant singolo: sia per l'identità dell'applicazione che per i casi di identità utente delegata, l'applicazione Web e l'API Web devono essere registrate nella stessa directory in Azure AD. L'API Web può essere configurata per esporre un set di autorizzazioni, che vengono usate per limitare l'accesso dell'applicazione Web alle relative risorse. Se si usa un tipo di identità utente delegato, l'applicazione Web deve selezionare le autorizzazioni desiderate dal menu a discesa Autorizzazioni per altre applicazioni nel portale di Azure. Questo passaggio non è obbligatorio se viene usato il tipo di identità dell'applicazione.
• Multi-tenant: per prima cosa, l'applicazione Web è configurata per indicare le autorizzazioni necessarie per essere funzionanti. Questo elenco di autorizzazioni necessarie viene visualizzato in una finestra di dialogo quando un utente o un amministratore nella directory di destinazione concede il consenso all'applicazione, che lo rende disponibile per l'organizzazione. Alcune applicazioni richiedono solo autorizzazioni a livello di utente, a cui qualsiasi utente dell'organizzazione può fornire il consenso. Altre applicazioni richiedono autorizzazioni a livello di amministratore, a cui un utente dell'organizzazione non può fornire il consenso. Solo un amministratore di directory può fornire il consenso alle applicazioni che richiedono questo livello di autorizzazioni. Quando l'utente o l'amministratore acconsente, l'applicazione Web e l'API Web vengono entrambi registrati nella directory.

Scadenza del token

Quando l'applicazione Web usa il codice di autorizzazione per ottenere un token di accesso JWT, riceve anche un token di aggiornamento JWT. Quando il token di accesso scade, il token di aggiornamento può essere usato per autenticare di nuovo l'utente senza richiedere di nuovo l'accesso. Questo token di aggiornamento viene quindi usato per autenticare l'utente, che comporta un nuovo token di accesso e un token di aggiornamento.

Passaggi successivi

• Altre informazioni su altri tipi e scenari di applicazione
• Informazioni sulle nozioni di base sull'autenticazione di Azure AD