Condividi tramite

Configurare la gestione credenziali: accesso delegato dell'utente alle API back-end

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Questo articolo illustra i passaggi generali per configurare e usare una connessione gestita che concede agli utenti o gruppi di Microsoft Entra autorizzazioni delegate a un'API OAuth 2.0 back-end. Seguire questi passaggi per gli scenari in cui un'app client (o bot) deve accedere alle risorse online protette dal back-end per conto di un utente autenticato (ad esempio, controllare i messaggi di posta elettronica o effettuare un ordine).

Panoramica dello scenario

Nota

Questo scenario si applica solo ai provider di credenziali configurati con il tipo di concessione codice di autorizzazione.

In questo scenario si configura una connessione gestita che consente a un'app client (o bot) di accedere a un'API back-end per conto di un utente o gruppo Microsoft Entra. Ad esempio, si potrebbe avere un'app Web statica che accede a un'API GitHub back-end e che si vuole far accedere ai dati specifici dell'utente connesso. Il diagramma seguente illustra lo scenario.

Diagramma che mostra il flusso di processo per le autorizzazioni delegate dall'utente.

  • L'utente deve autorizzare l'app ad accedere alle risorse protette per suo conto e, per autorizzare l'app, l'utente deve autenticare la propria identità
  • Per eseguire operazioni per conto di un utente, l'app chiama il servizio back-end esterno, ad esempio Microsoft Graph o GitHub
  • Ogni servizio esterno ha un modo per proteggere tali chiamate, ad esempio con un token utente che identifica l'utente in modo univoco
  • Per garantire la sicurezza della chiamata al servizio esterno, l'app deve chiedere all'utente di eseguire l'accesso, in modo da poter acquisire il token dell'utente
  • Nell'ambito della configurazione, un provider di credenziali viene registrato usando la gestione credenziali nell'istanza di Gestione API. Contiene informazioni sul provider di identità da usare, nonché un segreto e un ID client OAuth validi, gli ambiti di OAuth da abilitare e altri metadati della connessione richiesti dal provider di identità.
  • Viene inoltre creata e usata una connessione per consentire l'accesso dell'utente e ottenere il token utente in modo che possa essere gestito

Prerequisiti

  • Accesso a un tenant di Microsoft Entra in cui si dispone delle autorizzazioni per creare una registrazione dell'app e concedere il consenso amministratore per le autorizzazioni dell'app. Ulteriori informazioni

    Se si vuole creare un tenant per sviluppatore personalizzato, è possibile iscriversi al Programma per sviluppatori di Microsoft 365.

  • Uno o più utenti o gruppi nel tenant a cui delegare le autorizzazioni.

  • Un'istanza di Gestione API in esecuzione. Se necessario, creare un'istanza di Gestione API di Azure.

  • API OAuth 2.0 back-end a cui si vuole accedere per conto dell'utente o del gruppo.

Passaggio 1: Effettuare il provisioning dell'entità servizio Piano dati di Gestione API di Azure

È necessario effettuare il provisioning dell'entità servizio Piano dati di Gestione API di Azure per concedere agli utenti o ai gruppi le autorizzazioni delegate necessarie. Usare la procedura seguente per effettuare il provisioning dell'entità servizio usando Azure PowerShell.

  1. Accedere ad Azure PowerShell.

  2. Se il modulo AzureAD non è già installato, installarlo con il comando seguente:

    Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force

  3. Connettersi al tenant con il comando seguente:

    Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"

  4. Se richiesto, accedere con le credenziali dell'account amministratore del tenant.

  5. Effettuare il provisioning dell'entità servizio Piano dati di Gestione API di Azure con il comando seguente:

    New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"

Passaggio 2: Creare una registrazione dell'app Microsoft Entra

Creare un'applicazione Microsoft Entra ID per la delega utente e concedere le autorizzazioni appropriate per leggere la connessione in Gestione API.

  1. Accedere al portale di Azure con un account con autorizzazioni sufficienti nel tenant.
  2. In Servizi di Azurecercare Microsoft Entra ID.
  3. Nel menu a sinistra, selezionare Registrazioni app e quindi selezionare + Nuova registrazione.
  4. Nella pagina Registra un'applicazione inserire le impostazioni di registrazione dell'applicazione:
    1. Nella sezione Nome inserire un nome significativo che verrà visualizzato agli utenti dell'app, ad esempio UserPermissions.
    2. In Tipi di account supportati selezionare un'opzione adatta allo scenario, ad esempio Account solo in questa directory organizzativa (tenant singolo).
    3. Impostare l'URI di reindirizzamento su Web, quindi immettere https://www.postman-echo.com/get.
  5. Nel menu a sinistra selezionare Autorizzazioni API e quindi selezionare + Aggiungi un'autorizzazione.
    1. Selezionare la scheda API usate dall'organizzazione, digitare Piano dati di Gestione API di Azure e selezionarlo.
    2. In Autorizzazioni, selezionare Authorizations.Read, quindi selezionare Aggiungi autorizzazioni.
  6. Nel menu a sinistra, selezionare Panoramica. Nella pagina Panoramica, trovare il valore ID applicazione (client) e registrarlo per utilizzarlo in un passaggio successivo.
  7. Nel menu a sinistra selezionare Certificati e segreti e quindi selezionare + Nuovo segreto client.
    1. Compilare il campo Descrizione.
    2. Selezionare un'opzione per Scadenza.
    3. Selezionare Aggiungi.
    4. Copiare il Valore del segreto client prima di uscire dalla pagina. Saranno necessarie in un passaggio successivo.

Passaggio 3: Configurare un provider di credenziali in Gestione API

  1. Accedere al portale e passare all'istanza di Gestione API.
  2. Nel menu a sinistra selezionare Gestione credenziali e quindi + Crea.
    Screenshot della creazione di credenziali API nel portale.
  3. Nella pagina Crea provider di credenziali immettere le impostazioni per il provider di credenziali per l'API. Per questo scenario, in Tipo di concessione, è necessario selezionare Codice di autorizzazione. Per altre informazioni, vedere Configurare i provider di credenziali nella gestione credenziali.
  4. Seleziona Crea.
  5. Quando richiesto, esaminare l'URL di reindirizzamento OAuth visualizzato e selezionare Sì per confermare che corrisponda all'URL immesso nella registrazione dell'app.

Passaggio 4: Configurare una connessione

Dopo aver creato un provider di credenziali, è possibile aggiungere una connessione al provider. Nella scheda Connessione, completare i passaggi per la connessione:

  1. Immettere un Nome di connessione e quindi selezionare Salva.
  2. In Passaggio 2: Accedere alla connessione, selezionare il collegamento per accedere al provider di credenziali. Completare i passaggi necessari per autorizzare l'accesso e tornare a Gestione API.
  3. Nel Passaggio 3: Determinare chi avrà accesso a questa connessione (criterio di accesso), selezionare +Aggiungi. A seconda dello scenario di delega, selezionare Utenti o Gruppo.
  4. Nella finestra Seleziona elemento, effettuare selezioni nell'ordine seguente:
    1. Cercare prima di tutto uno o più utenti (o gruppi) da aggiungere e selezionare la casella di selezione.
    2. Quindi, nell'elenco visualizzato, cercare la registrazione dell'app creata in una sezione precedente.
    3. Fare clic su Seleziona.
  5. Selezionare Completo.

La nuova connessione viene visualizzata nell'elenco delle connessioni e mostra lo stato Connesso. Se si vuole creare un'altra connessione per il provider di credenziali, completare i passaggi precedenti.

Suggerimento

Usare il portale per aggiungere, aggiornare o eliminare connessioni a un provider di credenziali in qualsiasi momento. Per altre informazioni, vedere Configurare più connessioni.

Passaggio 5: Acquisire un token di accesso Microsoft Entra ID

Per abilitare l'accesso delegato dell'utente all'API back-end, è necessario fornire un token di accesso per l'utente o il gruppo delegato in fase di runtime nei criteri get-authorization-context. In genere questa operazione viene eseguita a livello di codice nell'app client usando Microsoft Authentication Library (MSAL). Questa sezione illustra i passaggi manuali per creare un token di accesso per il test.

  1. Incollare l'URL seguente nel browser, sostituendo i valori per <tenant-id> e <client-id> con i valori della registrazione dell'app Microsoft Entra:

    https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`

  2. Quando richiesto, eseguire l'accesso. Nel corpo della risposta, copiare il valore del codice fornito (ad esempio: "0.AXYAh2yl…").

  3. Inviare la richiesta POST seguente all'endpoint del token, sostituendo <tenant-id> con l'ID tenant e includendo l'intestazione indicata e i parametri del corpo dalla registrazione dell'app e il codice copiato nel passaggio precedente.

    POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1

    Intestazione

    Content-Type: application/x-www-form-urlencoded

    Testo

    grant_type: "authorization_code"
client_id: <client-id>
client_secret: <client-secret>
redirect_uri: <redirect-url> 
code: <code>   ## The code you copied in the previous step

  4. Nel corpo della risposta, copiare il valore del access_token fornito (ad esempio: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...). Questo valore verrà passato nella configurazione dei criteri nel passaggio successivo.

Passaggio 6: Configurare il criterio get-authorization-context per l'API back-end

Configurare il criterio get-authorization-context per l'API back-end a cui si vuole accedere per conto dell'utente o del gruppo. A scopo di test, è possibile configurare il criterio usando il token di accesso di Microsoft Entra ID per l'utente ottenuto nella sezione precedente.

  1. Accedere al portale e passare all'istanza di Gestione API.

  2. Nel menu a sinistra selezionare API e quindi selezionare l'API back-end OAuth 2.0.

  3. Selezionare Tutte le operazioni. Nella sezione Elaborazione in ingresso selezionare l'icona (editor di codice) (</>).

  4. Configurare il criterio get-authorization-context nella sezione inbound, impostando identity-type su jwt:

    <policies>
    <inbound>
        [...]
        <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
        [...]
    </inbound> 
</policies>

Nella definizione del criterio precedente, sostituire:

  • <credential-provider-id> e <connection-id> con i nomi rispettivamente del provider di credenziali e della connessione configurati in un passaggio precedente.

  • <access-token> con il token di accesso Microsoft Entra ID generato nel passaggio precedente.

Passaggio 7: Testare l'API

  1. Nella scheda Test selezionare un'operazione configurata.

  2. Selezionare Invia.

    Una risposta con esito positivo restituisce i dati utente dall'API back-end.

Contenuto correlato