Condividi tramite

API Web

  • Articolo

Avviso

Questo contenuto riguarda l'endpoint di Azure AD v1.0 meno recente. Per i nuovi progetti, usare Microsoft Identity Platform.

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à applicazione: questo scenario usa la concessione di credenziali client OAuth 2.0 per l'autenticazione come applicazione e l'accesso all'API Web. Quando si usa un'identità applicazione, l'API Web può solo rilevare la chiamata dell'applicazione Web, perché non riceve informazioni relative all'utente. Se l'applicazione riceve informazioni relative all'utente, queste vengono inviate tramite il protocollo applicativo e non sono firmate da Azure AD. L'API Web confida che l'applicazione Web abbia autenticato l'utente. Per questo motivo il modello è definito sottosistema attendibile.
  • Identità utente delegato: questo scenario può essere gestito in due modi, ovvero con OpenID Connect e con la concessione di codice di autorizzazione OAuth 2.0 con un client riservato. L'applicazione Web ottiene un token di accesso per l'utente, dimostrando all'API Web che l'utente è stato autenticato nell'applicazione Web e che l'applicazione Web è riuscita a ottenere un'identità utente delegato 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.

Nel flusso che segue sono illustrati i tipi di identità applicazione e identità utente delegato. La differenza fondamentale consiste nel fatto che l'identità utente delegato deve acquisire un codice di autorizzazione prima che l'utente possa ottenere l'accesso all'API Web.

Diagramma

Diagramma Da applicazione Web ad API Web

Flusso del protocollo

Identità applicazione con concessione delle credenziali client OAuth 2.0

  1. Un utente esegue 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 per l'autenticazione nell'API Web e il recupero della risorsa desiderata. Invia una richiesta all'endpoint del token di Azure AD, fornendo le credenziali, l'ID applicazione e l'URI ID applicazione dell'API Web.
  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 riesce, restituisce la risorsa desiderata.

Identità utente delegato con OpenID Connect

  1. Un utente esegue l'accesso all'applicazione Web usando Azure AD (consultare la sezione precedente Da Web browser ad applicazione Web). Se l'utente dell'applicazione Web non ha ancora concesso il consenso perché l'applicazione Web chiami l'API Web per suo conto, dovrà acconsentire. L'applicazione visualizzerà le autorizzazioni richieste e, se si tratta di autorizzazione a livello amministratore, un utente normale della directory non potrà concedere il consenso. Questo processo di consenso è valido solo per le applicazioni multi-tenant, non per le applicazioni con un singolo tenant, perché l'applicazione avrà già le autorizzazioni necessarie. Quando l'utente ha eseguito l'accesso, l'applicazione Web ha ricevuto un token ID con le informazioni relative all'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 l'API Web vengono convalidati da Azure AD. Se la convalida riesce, Azure AD restituisce tue 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 riesce, restituisce la risorsa desiderata.

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

  1. Un utente ha già eseguito l'accesso all'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 l'autenticazione completata. L'utente accede ad Azure AD.
  3. Se l'utente dell'applicazione Web non ha ancora concesso il consenso perché l'applicazione Web chiami l'API Web per suo conto, dovrà acconsentire. L'applicazione visualizzerà le autorizzazioni richieste e, se si tratta di autorizzazione a livello amministratore, un utente normale della directory non potrà concedere il consenso. Il consenso si applica sia all'applicazione a tenant singolo che multi-tenant. In un'applicazione a tenant singolo l'amministratore può eseguire il consenso dell'amministratore per acconsentire per conto degli utenti. Questa operazione può essere eseguita usando il Grant Permissions pulsante nel portale di Azure.
  4. Quando l'utente concede il consenso, l'applicazione Web riceve il codice di autorizzazione necessario per 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 l'API Web vengono convalidati da Azure AD. Se la convalida riesce, Azure AD restituisce tue 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 riesce, restituisce la risorsa desiderata.

Esempi di codice

Vedere gli esempi di codice per gli scenari Da applicazione Web ad API Web. Consultare spesso questa pagina perché vengono aggiunti regolarmente nuovi esempi: Da applicazione Web ad API Web.

Registrazione delle app

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

  • Tenant singolo: in entrambi i casi (identità applicazione e identità utente delegato), 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 viene usato un tipo di identità utente delegato, l'applicazione Web deve selezionare le autorizzazioni desiderate dal menu a discesa Autorizzazioni ad altre applicazioni nel portale di Azure. Questo passaggio non è necessario se viene usato il tipo di identità applicazione.
  • Multi-tenant: per prima cosa, l'applicazione Web viene configurata per indicare le autorizzazioni necessarie per il funzionamento. Questo elenco di autorizzazioni richieste viene visualizzato in una finestra di dialogo quando un utente o amministratore nella directory di destinazione concede il consenso all'applicazione, rendendola disponibile per la propria organizzazione. Alcune applicazioni richiedono solo autorizzazioni a livello utente, che possono essere concesse da qualsiasi utente dell'organizzazione. Altre applicazioni richiedono autorizzazioni a livello amministratore, che non possono essere concesse dagli utenti dell'organizzazione. Solo un amministratore di directory può concedere il consenso alle applicazioni che richiedono questo livello di autorizzazione. Quando l'utente o l'amministratore acconsente, l'applicazione Web e l'API Web vengono registrate nella directory.

Scadenza del token

Quando l'applicazione Web usa il proprio codice di autorizzazione per ottenere un token di accesso JWT, riceve anche un token di aggiornamento JWT. Quando il token di accesso scade, è possibile usare il token di aggiornamento per autenticare di nuovo l'utente senza richiedere di ripetere l'accesso. Questo token di aggiornamento viene quindi usato per autenticare l'utente, con conseguente emissione di un nuovo token di accesso e un nuovo token di aggiornamento.

Passaggi successivi