Gestire l'API e le versioni di runtime dell'autenticazione del servizio app

Questo articolo descrive come personalizzare l'API e le versioni di runtime dell'autenticazione e dell'autorizzazione predefinite nel servizio app.

Esistono due versioni dell'API di gestione per l'autenticazione del servizio app. La versione V2 è necessaria per l'esperienza di autenticazione nel portale di Azure. Un'app che usa già l'API V1 può eseguire l'aggiornamento alla versione V2 dopo aver apportato alcune modifiche. In particolare, la configurazione dei segreti deve essere spostata nelle impostazioni dell'applicazione slot-sticky. È possibile spostare automaticamente la configurazione dei segreti dalla sezione Autenticazione dell'app nel portale.

Aggiornare la versione della configurazione

Avviso

La migrazione alla versione 2 disabilita la gestione della funzionalità di autenticazione/autorizzazione del servizio app per l'applicazione tramite alcuni client, ad esempio l'esperienza esistente nel portale di Azure, nell'interfaccia della riga di comando di Azure e in Azure PowerShell. Questa migrazione non può essere annullata.

L'API V2 non supporta la creazione o la modifica di un account Microsoft come provider distinto come V1. Usa invece la piattaforma di identità Microsoft Identity Platform convergente per consentire agli utenti di accedere con account Microsoft Entra e personali Microsoft. Quando si passa all'API V2, la configurazione di Microsoft Entra V1 viene usata per configurare il provider di Microsoft Identity Platform. Il provider di account Microsoft V1 viene portato avanti nel processo di migrazione e continua a funzionare come di consueto, ma è consigliabile passare al modello Microsoft Identity Platform più recente. Per altre informazioni, vedere Passare una configurazione a un provider Microsoft Entra.

Il processo di migrazione automatizzata sposta i segreti del provider nelle impostazioni dell'applicazione e quindi converte il resto della configurazione nel nuovo formato. Per usare la migrazione automatica:

  1. Passare all'app nel portale e selezionare Impostazioni>Autenticazione nel riquadro sinistro.
  2. Se l'app è configurata con il modello V1, viene visualizzato un pulsante Aggiorna .
  3. Selezionare il pulsante Aggiorna. Esaminare la descrizione nel prompt di conferma. Se si è pronti per eseguire la migrazione, selezionare Aggiorna nel prompt.

Gestione manuale della migrazione

La procedura seguente consente di eseguire manualmente la migrazione di un'applicazione all'API V2 se non si vuole usare la versione automatica descritta in precedenza.

Spostare i segreti nelle impostazioni dell'applicazione

Per spostare i segreti del provider di identità nelle impostazioni dell'applicazione, completare questi passaggi.

  1. Ottenere la configurazione esistente usando l'API V1:

    az webapp auth show -g <group_name> -n <app_name>

    Nel payload JSON risultante prendere nota del valore del segreto usato per ogni provider configurato:

    • Microsoft Entra: clientSecret
    • Google: googleClientSecret
    • Facebook: facebookAppSecret
    • X: twitterConsumerSecret
    • Account Microsoft: microsoftAccountClientSecret

    Importante

    I valori dei segreti sono credenziali di sicurezza importanti e devono essere gestiti con attenzione. Non condividere questi valori o renderli persistenti in un computer locale.

  2. Creare le impostazioni dell'applicazione slot-sticky per ogni valore del segreto. È possibile scegliere il nome di ogni impostazione dell'applicazione. Il valore deve corrispondere a quello ottenuto nel passaggio precedente o fare riferimento a un segreto di Azure Key Vault creato con tale valore.

    Per creare l'impostazione, è possibile usare il portale di Azure o eseguire una variante del comando seguente per ogni provider:

    # For web apps, Google example    
az webapp config appsettings set -g <group_name> -n <app_name> --slot-settings GOOGLE_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

# For Azure Functions, X example
az functionapp config appsettings set -g <group_name> -n <app_name> --slot-settings TWITTER_PROVIDER_AUTHENTICATION_SECRET=<value_from_previous_step>

    Nota

    Le impostazioni dell'applicazione per questa configurazione devono essere contrassegnate come slot-sticky, il che significa che non si spostano tra ambienti durante un'operazione di scambio di slot. Questa configurazione è necessaria perché la configurazione di autenticazione è associata all'ambiente.

  3. Creare un nuovo file JSON denominato authsettings.json. Prendere l'output ricevuto in precedenza e rimuovere ogni valore segreto da esso. Aggiungere l'output rimanente al file, assicurandosi che non siano inclusi segreti. In alcuni casi, la configurazione potrebbe contenere matrici che contengono stringhe vuote. Assicurarsi che microsoftAccountOAuthScopes non lo faccia. In caso affermativo, modificare il valore in null.

  4. Aggiungere una proprietà a authsettings.json che punti al nome dell'impostazione dell'applicazione creato in precedenza per ogni provider:

    • Microsoft Entra: clientSecretSettingName
    • Google: googleClientSecretSettingName
    • Facebook: facebookAppSecretSettingName
    • X: twitterConsumerSecretSettingName
    • Account Microsoft: microsoftAccountClientSecretSettingName

    Un file di impostazioni dopo questa operazione potrebbe essere simile al seguente, in questo caso configurato solo per Microsoft Entra ID:

    {
    "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myresourcegroup/providers/Microsoft.Web/sites/mywebapp/config/authsettings",
    "name": "authsettings",
    "type": "Microsoft.Web/sites/config",
    "location": "Central US",
    "properties": {
        "enabled": true,
        "runtimeVersion": "~1",
        "unauthenticatedClientAction": "AllowAnonymous",
        "tokenStoreEnabled": true,
        "allowedExternalRedirectUrls": null,
        "defaultProvider": "AzureActiveDirectory",
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "clientSecret": "",
        "clientSecretSettingName": "MICROSOFT_IDENTITY_AUTHENTICATION_SECRET",
        "clientSecretCertificateThumbprint": null,
        "issuer": "https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/",
        "allowedAudiences": [
            "https://mywebapp.azurewebsites.net"
        ],
        "additionalLoginParams": null,
        "isAadAutoProvisioned": true,
        "aadClaimsAuthorization": null,
        "googleClientId": null,
        "googleClientSecret": null,
        "googleClientSecretSettingName": null,
        "googleOAuthScopes": null,
        "facebookAppId": null,
        "facebookAppSecret": null,
        "facebookAppSecretSettingName": null,
        "facebookOAuthScopes": null,
        "gitHubClientId": null,
        "gitHubClientSecret": null,
        "gitHubClientSecretSettingName": null,
        "gitHubOAuthScopes": null,
        "twitterConsumerKey": null,
        "twitterConsumerSecret": null,
        "twitterConsumerSecretSettingName": null,
        "microsoftAccountClientId": null,
        "microsoftAccountClientSecret": null,
        "microsoftAccountClientSecretSettingName": null,
        "microsoftAccountOAuthScopes": null,
        "isAuthFromFile": "false"
    }   
}

  5. Inviare questo file come nuova configurazione di autenticazione/autorizzazione per l'app:

    az rest --method PUT --url "/subscriptions/<subscription_id>/resourceGroups/<group_name>/providers/Microsoft.Web/sites/<app_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Verificare che l'app funzioni ancora come previsto dopo l'invio del file.

  7. Eliminare il file usato nei passaggi precedenti.

Ora hai migrato l'app per conservare i segreti del fornitore di identità come impostazioni dell'applicazione.

Passare a una configurazione di un provider Microsoft Entra

Se la configurazione esistente contiene un provider di account Microsoft e non contiene un provider Microsoft Entra, è possibile modificare la configurazione con il provider Microsoft Entra e quindi eseguire la migrazione:

  1. Passare a Registrazioni delle app nel portale di Azure e trovare la registrazione associata al fornitore dell'account Microsoft. Potrebbe trovarsi sotto l'intestazione Applicazioni di proprietà .
  2. Passare alla pagina Autenticazione (anteprima) per la registrazione. In URI di reindirizzamento dovrebbe essere visualizzata una voce che termina con /.auth/login/microsoftaccount/callback. Copiare l'URI.
  3. Aggiungere un nuovo URI corrispondente a quello appena copiato, ma terminarlo con /.auth/login/aad/callback. Questo URI consente alla registrazione di essere utilizzata dalla configurazione di autenticazione/autorizzazione dell'App Service.
  4. Vai all'app nel portale. Selezionare Impostazioni>Autenticazione.
  5. Raccogliere la configurazione per il provider di account Microsoft.
  6. Configurare il provider Microsoft Entra usando la modalità di gestione avanzata , specificando l'ID client e i valori dei segreti client raccolti nel passaggio precedente. Per l'URL dell'autorità di certificazione, usare <authentication-endpoint>/<tenant-id>/v2.0. Sostituire <authentication-endpoint> con l'endpoint di autenticazione per l'ambiente cloud (ad esempio, "https://login.microsoftonline.com"" per l'ID Microsoft Entra globale). Sostituire <tenant-id> con il proprio ID Directory (tenant).
  7. Dopo aver salvato la configurazione, testare il flusso di accesso passando nel browser all'endpoint /.auth/login/aad nel sito e completando il flusso di accesso.
  8. A questo punto, hai copiato con successo la configurazione, ma rimane la configurazione del provider di account Microsoft esistente. Prima di rimuoverlo, assicurarsi che tutte le parti dell'app facciano riferimento al provider Microsoft Entra tramite i collegamenti di accesso e così via. Verificare che tutte le parti dell'app funzionino come previsto.
  9. Dopo aver verificato che tutto funzioni con il provider Microsoft Entra, è possibile rimuovere la configurazione del provider di account Microsoft.

Avviso

È possibile convergere le due registrazioni modificando i tipi di account supportati per la registrazione dell'app Microsoft Entra. Tuttavia, questa configurazione forza una nuova richiesta di consenso per gli utenti dell'account Microsoft e le attestazioni di identità degli utenti potrebbero essere diverse nella struttura, sub con cambiamenti significativi nei valori, perché viene usato un nuovo ID app. Questo approccio non è consigliato a meno che non lo si capisca a fondo. È invece necessario attendere il supporto per le due registrazioni nella superficie dell'API V2.

Passare alla versione 2

Dopo aver completato i passaggi precedenti, passare all'app nel portale di Azure. Selezionare la sezione Autenticazione (anteprima).

In alternativa, è possibile effettuare una richiesta PUT sulla risorsa config/authsettingsv2 all'interno della risorsa del sito. Lo schema per il payload è uguale a quello acquisito nella configurazione basata su file.

Aggiungere l'app a una versione specifica del runtime di autenticazione

Quando si abilita l'autenticazione/autorizzazione, il middleware della piattaforma viene inserito nella pipeline di richieste HTTP, come descritto nella panoramica delle funzionalità. Questo middleware della piattaforma viene aggiornato periodicamente con nuove funzionalità e miglioramenti nell'ambito degli aggiornamenti della piattaforma di routine. Per impostazione predefinita, l'app Web o per le funzioni viene eseguita nella versione più recente di questo middleware della piattaforma. Questi aggiornamenti automatici sono sempre compatibili con le versioni precedenti. Tuttavia, nel raro caso in cui questo aggiornamento automatico introduce un problema di runtime per l'app Web o per le funzioni, è possibile eseguire temporaneamente il rollback alla versione del middleware precedente. Questa sezione illustra come aggiungere temporaneamente un'app a una versione specifica del middleware di autenticazione.

Aggiornamenti di versione automatici e manuali

È possibile aggiungere l'app a una versione specifica del middleware della piattaforma configurando un'impostazione runtimeVersion per l'app. L'app viene sempre eseguita nella versione più recente, a meno che non si scelga di aggiungerla in modo esplicito a una versione specifica. Sono supportate alcune versioni alla volta. Se fissi una versione non valida che non è più supportata, l'app utilizza la versione più recente. Per eseguire sempre la versione più recente, impostare runtimeVersion su ~1.

Visualizzare e aggiornare la versione corrente del runtime

È possibile modificare la versione del runtime usata dall'app. La nuova versione del runtime dovrebbe essere applicata dopo il riavvio dell'app.

Visualizzare la versione corrente del runtime

È possibile visualizzare la versione corrente del middleware di autenticazione della piattaforma usando l'interfaccia della riga di comando di Azure o tramite uno degli endpoint HTTP predefiniti della versione nell'app.

Dall'interfaccia della riga di comando di Azure

Usando l'interfaccia della riga di comando di Azure, visualizzare la versione attuale del software intermedio con il comando az webapp auth show.

az webapp auth show --name <my_app_name> \
--resource-group <my_resource_group>

In questo codice sostituire <my_app_name> con il nome dell'app. Sostituire <my_resource_group> con il nome del gruppo di risorse per l'app.

Vedrai il campo runtimeVersion nell'output CLI. È simile all'output di esempio seguente, che viene troncato per maggiore chiarezza:

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
Dall'endpoint della versione

È anche possibile raggiungere l'endpoint /.auth/version in un'app per visualizzare la versione del middleware corrente in cui è in esecuzione l'app. L'output sarà simile al seguente:

{
"version": "1.3.2"
}

Aggiornare la versione di runtime corrente

Con l'interfaccia della riga di comando di Azure è possibile aggiornare l'impostazione runtimeVersion in un'app usando il comando az webapp auth update :

az webapp auth update --name <my_app_name> \
--resource-group <my_resource_group> \
--runtime-version <version>

Sostituire <my_app_name> con il nome dell'app. Sostituire <my_resource_group> con il nome del gruppo di risorse per l'app. Sostituire <version> con una versione valida di 1.x runtime o usare ~1 per la versione più recente. Per determinare la versione da utilizzare per Funzioni di Azure, vedere Panoramica delle versioni di runtime di Funzioni di Azure.

È possibile eseguire questo comando da Azure Cloud Shell selezionando Open Cloud Shell nell'esempio di codice precedente. È anche possibile usare l'interfaccia della riga di comando di Azure in locale per eseguire questo comando dopo aver eseguito az login per accedere.

Passo successivo

Esercitazione: Autenticare e autorizzare gli utenti end-to-end

  • Last updated on