Gérer les versions d’API et d’exécution de l’authentification App Service

Cet article explique comment personnaliser les versions d’API et d’exécution de l’authentification et de l’autorisation intégrées dans App Service.

Il existe deux versions de l’API de gestion pour l’authentification App Service. La version V2 est requise pour l’expérience d’authentification dans le portail Azure. Une application qui utilise déjà l’API V1 peut effectuer une mise à niveau vers la version V2 après quelques modifications. Plus précisément, la configuration confidentielle doit être déplacée vers les paramètres d'application à emplacement fixe. Vous pouvez déplacer automatiquement la configuration des secrets à partir de la section Authentification de votre application sur le portail.

Mettre à jour la version de configuration

Avertissement

La migration vers V2 désactive la gestion de la fonctionnalité d’authentification/d’autorisation App Service pour votre application via certains clients, tels que son expérience existante dans le portail Azure, Azure CLI et Azure PowerShell. Cette migration ne peut pas être inversée.

L’API V2 ne prend pas en charge la création ou la modification d’un compte Microsoft en tant que fournisseur distinct comme V1. Il utilise plutôt la plateforme d’identités Microsoft convergée pour connecter des utilisateurs avec microsoft Entra et des comptes Microsoft personnels. Lorsque vous basculez vers l’API V2, la configuration de Microsoft Entra V1 est utilisée pour configurer le fournisseur de plateforme d’identités Microsoft. Le fournisseur de compte Microsoft V1 est transféré dans le processus de migration et continue à fonctionner normalement, mais vous devez passer au modèle de plateforme d’identités Microsoft plus récent. Pour plus d’informations, consultez Basculer une configuration vers un fournisseur Microsoft Entra.

Le processus de migration automatisé déplace les secrets du fournisseur dans les paramètres d’application, puis convertit le reste de la configuration dans le nouveau format. Pour utiliser la migration automatique :

  1. Accédez à votre application dans le portail et sélectionnezAuthentification> dans le volet gauche.
  2. Si l’application est configurée avec le modèle V1, vous voyez un bouton Mettre à niveau .
  3. Sélectionnez le bouton Mettre à niveau. Veuillez examiner la description dans l'invite de confirmation. Si vous êtes prêt à effectuer la migration, sélectionnezMettre à niveau dans l’invite.

Gestion manuelle de la migration

Les étapes suivantes vous permettent de migrer manuellement une application vers l’API V2 si vous ne souhaitez pas utiliser la version automatique décrite précédemment.

Déplacer des secrets vers les paramètres d’application

Pour déplacer les secrets du fournisseur d’identité vers les paramètres d’application, procédez comme suit.

  1. Récupérez votre configuration actuelle à l’aide de l’API v1 :

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

    Dans la charge utile JSON résultante, prenez note de la valeur de secret utilisée pour chaque fournisseur que vous avez configuré :

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

    Important

    Les valeurs secrètes sont des informations d’identification de sécurité importantes et doivent être manipulées avec précaution. Ne partagez pas ces valeurs ni ne les conservez sur un ordinateur local.

  2. Créez des paramètres d’application à emplacement fixe pour chaque valeur de secret. Vous pouvez choisir le nom de chaque paramètre d’application. Sa valeur doit correspondre à ce que vous avez obtenu à l’étape précédente ou référencer un secret Azure Key Vault que vous avez créé avec cette valeur.

    Pour créer le paramètre, vous pouvez utiliser le portail Azure ou exécuter une variante de la commande suivante pour chaque fournisseur :

    # 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>

    Note

    Les paramètres de l’application de cette configuration doivent être marqués comme adhérents au slot, ce qui signifie qu’ils ne se déplaceront pas entre les environnements lors d’une opération de bascule de slot. Cette configuration est requise, car votre configuration d’authentification est liée à l’environnement.

  3. Créez un nouveau fichier JSON appelé authsettings.json. Prenez la sortie que vous avez reçue précédemment et supprimez chaque valeur secrète de celle-ci. Ajoutez la sortie restante au fichier, en vous assurant qu’aucun secret n’est inclus. Dans certains cas, la configuration peut avoir des tableaux qui contiennent des chaînes vides. Assurez-vous que microsoftAccountOAuthScopes ne fonctionne pas. Si c’est le cas, remplacez la valeur nullpar .

  4. Ajoutez une propriété à authsettings.json qui pointe vers le nom du paramètre d’application que vous avez créé précédemment pour chaque fournisseur :

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

    Un fichier de paramètres après cette opération peut ressembler à ce qui suit, dans ce cas uniquement configuré pour l’ID Microsoft Entra :

    {
    "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. Envoyez ce fichier en tant que nouvelle configuration d’authentification/autorisation pour votre application :

    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. Vérifiez que votre application fonctionne toujours comme prévu après avoir envoyé le fichier.

  7. Supprimez le fichier utilisé dans les étapes précédentes.

Vous avez maintenant migré l’application pour stocker les secrets du fournisseur d’identité comme paramètres d’application.

Basculer une configuration vers un fournisseur Microsoft Entra

Si votre configuration existante contient un fournisseur de compte Microsoft et qu’elle ne contient pas de fournisseur Microsoft Entra, vous pouvez modifier la configuration au fournisseur Microsoft Entra, puis effectuer la migration :

  1. Accédez aux inscriptions d’applications dans le portail Azure et recherchez l’inscription associée à votre fournisseur de compte Microsoft. Il peut se trouver sous le titre Applications détenues .
  2. Accédez à la page Authentification (Aperçu) pour l'inscription. Sous URI de redirection, vous devriez voir une entrée se terminant par /.auth/login/microsoftaccount/callback. Copiez cet URI.
  3. Ajoutez un nouvel URI qui correspond à celui que vous venez de copier, mais terminez-le par /.auth/login/aad/callback. Cet URI permet à l’inscription d’être utilisée par la configuration d’authentification/d’autorisation App Service.
  4. Accédez à votre application dans le portail. Sélectionnez Paramètres>Authentification.
  5. Collectez la configuration du fournisseur de compte Microsoft.
  6. Configurez le fournisseur Microsoft Entra à l’aide du mode de gestion avancé , en fournissant l’ID client et les valeurs de secret client que vous avez collectées à l’étape précédente. Pour l’URL de l’émetteur, utilisez <authentication-endpoint>/<tenant-id>/v2.0. Remplacez <authentication-endpoint> par le point de terminaison d’authentification de votre environnement cloud (par exemple, «https://login.microsoftonline.com" ; pour l’ID Microsoft Entra global). Remplacez <tenant-id> par votre ID d’annuaire (locataire).
  7. Après avoir enregistré la configuration, testez le flux de connexion en naviguant dans votre navigateur vers le /.auth/login/aad point de terminaison de votre site et en complétant le processus de connexion.
  8. À ce stade, vous avez correctement copié la configuration, mais la configuration du fournisseur de compte Microsoft existante reste. Avant de le supprimer, assurez-vous que toutes les parties de votre application font référence au fournisseur Microsoft Entra via des liens de connexion, et ainsi de suite. Vérifiez que toutes les parties de votre application fonctionnent comme prévu.
  9. Après avoir validé que tout fonctionne avec le fournisseur Microsoft Entra, vous pouvez supprimer la configuration du fournisseur de compte Microsoft.

Avertissement

Il est possible de converger les deux inscriptions en modifiant les types de comptes pris en charge pour l’inscription de l’application Microsoft Entra. Toutefois, cette configuration forcerait une nouvelle invite de consentement pour les utilisateurs de compte Microsoft, et les revendications d’identité de ces utilisateurs pourraient avoir une structure différente, sub notamment par la modification des valeurs, étant donné qu'un nouvel ID d’application est utilisé. Nous vous déconseillons cette approche, sauf si vous la comprenez soigneusement. Vous devriez plutôt attendre la prise en charge des deux enregistrements dans la surface de l'API V2.

Basculer vers V2

Une fois les étapes précédentes effectuées, accédez à l’application dans le portail Azure. Sélectionnez la section Authentification (aperçu).

Vous pouvez également effectuer une demande PUT sur la ressource config/authsettingsv2 située sous la ressource du site. Le schéma de la charge utile est identique à celui capturé dans la configuration basée sur les fichiers.

Épingler votre application à une version spécifique du runtime d’authentification

Lorsque vous activez l’authentification/autorisation, l’intergiciel (middleware) de la plateforme est injecté dans votre pipeline de requêtes HTTP, comme décrit dans la vue d’ensemble des fonctionnalités. Cet intergiciel (middleware) de plateforme est régulièrement mis à jour avec de nouvelles fonctionnalités et des améliorations dans le cadre des mises à jour de routine de la plateforme. Par défaut, votre application web ou de fonction s’exécute sur la dernière version de ce middleware de plateforme. Ces mises à jour automatiques sont toujours rétrocompatibles. Toutefois, dans les rares cas où cette mise à jour automatique introduit un problème de runtime pour votre application web ou de fonction, vous pouvez revenir temporairement à la version précédente de l’intergiciel (middleware). Cette section explique comment épingler temporairement une application à une version spécifique du middleware d’authentification.

Mises à jour de versions automatiques et manuelles

Vous pouvez épingler votre application à une version spécifique du middleware de plateforme en configurant un runtimeVersion paramètre pour l’application. Votre application s’exécute toujours sur la dernière version, sauf si vous choisissez de l’épingler explicitement à une version spécifique. Il existe quelques versions prises en charge à la fois. Si vous épinglez à une version non valide qui n’est plus prise en charge, votre application utilise plutôt la dernière version. Pour toujours exécuter la dernière version, définissez le runtimeVersion sur ~1.

Afficher et mettre à jour la version actuelle du runtime

Vous pouvez modifier la version du runtime utilisée par votre application. La nouvelle version du runtime doit prendre effet après le redémarrage de l’application.

Afficher la version actuelle du runtime

Vous pouvez afficher la version actuelle du middleware d’authentification de la plateforme à l’aide d’Azure CLI ou via l’un des points de terminaison HTTP intégrés de votre application.

Depuis l'Azure CLI

À l’aide d’Azure CLI, affichez la version actuelle du middleware avec la commande az webapp auth show .

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

Dans ce code, remplacez <my_app_name> par le nom de votre application. Remplacez <my_resource_group> par le nom du groupe de ressources de votre application.

Le champ runtimeVersion est affiché dans la sortie de l’interface CLI. Il ressemble à l’exemple de sortie suivant, qui est tronqué pour plus de clarté :

{
  "additionalLoginParams": null,
  "allowedAudiences": null,
    ...
  "runtimeVersion": "1.3.2",
    ...
}
À partir du point de terminaison de version

Vous pouvez également atteindre le point de terminaison /.auth/version sur une application pour afficher la version actuelle du middleware sur laquelle l’application s’exécute. La sortie ressemble à l'exemple suivant :

{
"version": "1.3.2"
}

Mettre à jour la version actuelle du runtime

Avec Azure CLI, vous pouvez mettre à jour le runtimeVersion paramètre dans une application à l’aide de la commande az webapp auth update :

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

Remplacez <my_app_name> par le nom de votre application. Remplacez <my_resource_group> par le nom du groupe de ressources de votre application. Remplacez <version> par une version valide de l'environnement d'exécution 1.x ou utilisez ~1 pour la version la plus récente. Pour déterminer la version à choisir pour Azure Functions, consultez la vue d’ensemble des versions de l'environnement d'exécution Azure Functions.

Vous pouvez exécuter cette commande à partir d’Azure Cloud Shell en sélectionnant Open Cloud Shell dans l’exemple de code précédent. Vous pouvez également utiliser Azure CLI localement pour exécuter cette commande après avoir exécuté az login pour vous connecter.

Étape suivante

Tutoriel : Authentifier et autoriser des utilisateurs de bout en bout

  • Last updated on