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

  • Articolo

Questo articolo illustra 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 "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. Questa operazione può essere eseguita automaticamente dalla sezione "Autenticazione" del portale per l'app.

Aggiornare la versione della configurazione

Avviso

La migrazione alla versione 2 disabiliterà la gestione della funzionalità 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. Ciò non può essere invertito.

L'API V2 non supporta la creazione o la modifica dell'account Microsoft come provider distinto come è stato fatto nella versione 1. Usa invece Microsoft Identity Platform convergente per consentire agli utenti di accedere con account Microsoft Entra e Microsoft personali. 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 verrà portato avanti nel processo di migrazione e continuerà a funzionare come di consueto, ma è consigliabile passare al modello Microsoft Identity Platform più recente. Per altre informazioni, vedere Supporto per le registrazioni del provider di account Microsoft.

Il processo di migrazione automatizzato 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 l'opzione di menu Autenticazione.
  2. Se l'app è configurata usando il modello V1, verrà visualizzato un pulsante Aggiorna.
  3. Esaminare la descrizione nella richiesta di conferma. Se si è pronti per eseguire la migrazione, selezionare Aggiorna nel prompt.

Gestione manuale della migrazione

La procedura seguente consentirà di eseguire manualmente la migrazione dell'applicazione all'API V2 se non si vuole usare la versione automatica indicata in precedenza.

Spostamento dei segreti nelle impostazioni dell'applicazione

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

    az webapp auth show -g <group_name> -n <site_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
    • Microsoft Account: 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 dell'insieme di credenziali delle chiavi creato con tale valore.

    Per creare l'impostazione, è possibile usare il portale di Azure o eseguire una variante delle opzioni seguenti per ogni provider:

    # For Web Apps, Google example    
az webapp config appsettings set -g <group_name> -n <site_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 <site_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, ovvero non verranno spostate tra ambienti durante un'operazione di scambio di slot. Ciò è dovuto al fatto che la configurazione di autenticazione stessa è associata all'ambiente.

  3. Creare un nuovo file JSON denominato authsettings.json. Accettare l'output ricevuto in precedenza e rimuovere ogni valore del segreto da esso. Scrivere l'output rimanente nel file, assicurandosi che non sia incluso alcun segreto. In alcuni casi, la configurazione potrebbe contenere matrici contenenti stringhe vuote. Assicurarsi che microsoftAccountOAuthScopes non ne abbia, in caso affermativo, passare a 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
    • Microsoft Account: microsoftAccountClientSecretSettingName

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

    {
    "id": "/subscriptions/00d563f8-5b89-4c6a-bcec-c1b9f6d607e0/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/0b2ef922-672a-4707-9643-9a5726eec524/",
        "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/<site_name>/config/authsettings?api-version=2020-06-01" --body @./authsettings.json

  6. Verificare che l'app funzioni ancora come previsto dopo questo gesto.

  7. Eliminare il file usato nei passaggi precedenti.

È stata eseguita la migrazione dell'app per archiviare i segreti del provider di identità come impostazioni dell'applicazione.

Supporto per le registrazioni del provider di account Microsoft

Se la configurazione esistente contiene un provider di account Microsoft e non contiene un provider Microsoft Entra, è possibile passare la configurazione al provider Microsoft Entra e quindi eseguire la migrazione. A questo scopo, è necessario:

  1. Passare a Registrazioni app nel portale di Azure e trovare la registrazione associata al provider di account Microsoft. Potrebbe trovarsi sotto l'intestazione "Applicazioni dall'account personale".
  2. Passare alla pagina "Autenticazione" per la registrazione. In "URI di reindirizzamento" verrà visualizzata una voce che termina con /.auth/login/microsoftaccount/callback. Copiare l'URI.
  3. Aggiungere un nuovo URI corrispondente a quello appena copiato, ad eccezione del fatto che termina in /.auth/login/aad/callback. In questo modo la registrazione verrà usata dalla configurazione autenticazione/autorizzazione del servizio app.
  4. Passare alla configurazione autenticazione/autorizzazione del servizio app per l'app.
  5. Raccogliere la configurazione per il provider di account Microsoft.
  6. Configurare il provider Microsoft Entra usando la modalità di gestione "Avanzata", fornendo 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 e sostituire l'<endpoint di autenticazione> con l'endpoint di autenticazione per l'ambiente cloud ( ad esempio "https://login.microsoftonline.com" per l'ID Microsoft Entra globale), sostituendo anche <id tenant > con l'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, la configurazione è stata copiata correttamente, 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 collegamenti di accesso e così via. Verificare che tutte le parti dell'app funzionino come previsto.
  9. Dopo aver verificato che le operazioni funzionino 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, ciò forza una nuova richiesta di consenso per gli utenti dell'account Microsoft e le attestazioni di identità degli utenti potrebbero essere diverse nella struttura, dato che in particolare sub modificherebbe i valori perché viene usato un nuovo ID app. Questo approccio non è consigliato a meno che non venga compreso accuratamente. È invece necessario attendere il supporto per le due registrazioni nella superficie dell'API V2.

Passaggio alla V2

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

In alternativa, è possibile effettuare una richiesta PUT per la risorsa config/authsettingsv2 nella 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 verrà 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. Questo articolo 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 impostando un'impostazione runtimeVersion per l'app. L'app viene sempre eseguita sulla versione più recente, a meno che non si scelga di aggiungerla in modo esplicito a una versione specifica. Sono disponibili alcune versioni supportate alla volta. Se si aggiunge a una versione non valida che non è più supportata, l'app userà invece 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 di 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 della versione predefinita nell'app.

Dall'interfaccia della riga di comando di Azure

Usando l'interfaccia della riga di comando di Azure, visualizzare la versione del middleware corrente 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 anche <my_resource_group> con il nome del gruppo di risorse per l'app.

Nell'output dell'interfaccia della riga di comando verrà visualizzato il campo runtimeVersion. Sarà simile all'output di esempio seguente, che è stato troncato per maggiore chiarezza:

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

È anche possibile premere l'endpoint /.auth/version in un'app per visualizzare la versione del middleware corrente in cui è in esecuzione l'app. Sarà simile all'output di esempio seguente:

{
"version": "1.3.2"
}

Aggiornare la versione di runtime corrente

Usando l'interfaccia della riga di comando di Azure, è possibile aggiornare l'impostazione runtimeVersion nell'app con 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 anche <my_resource_group> con il nome del gruppo di risorse per l'app. Sostituire anche <version> con una versione valida del runtime 1.x o ~1 per la versione più recente. Vedere le note sulla versione relative alle diverse versioni di runtime per determinare la versione a cui aggiungere.

È possibile eseguire questo comando da Azure Cloud Shell scegliendo Prova nell'esempio di codice precedente. È anche possibile usare l'interfaccia della riga di comando di Azure in locale per eseguire questo comando dopo l'esecuzione del comando az login per eseguire l'accesso.

Passaggi successivi

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