Application web qui connecte les utilisateurs : Configuration de code

Article
08/06/2024

Cet article explique comment configurer le code de votre application web pour connecter les utilisateurs.

Bibliothèques Microsoft prenant en charge les applications web

Les bibliothèques Microsoft suivantes sont utilisées pour protéger une application web (et une API web) :

Langage/framework	Projet sur GitHub	Package	Bien démarrer démarré	Connexion des utilisateurs	Accès aux API web	Disponibilité générale ou Préversion publique¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Démarrage rapide			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Démarrage rapide			GA
Java	MSAL4J	msal4j	Démarrage rapide			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Didacticiel			GA
Node.js	MSAL Node	msal-node	Démarrage rapide			GA
Python	MSAL Python	msal				GA
Python	identity	identity	Démarrage rapide			--

⁽¹⁾ Les termes du contrat de licence universelle pour les services en ligne s’appliquent aux bibliothèques en préversion publique.

⁽²⁾ La bibliothèque Microsoft.IdentityModelvalide uniquement les jetons. Elle ne peut pas demander de jetons d’ID ni de jetons d’accès.

Sélectionnez l’onglet correspondant à la plateforme qui vous intéresse :

Les extraits de code indiqués dans cet article et les suivants proviennent du tutoriel incrémentiel sur l’application web ASP.NET Core, chapitre 1.

Vous pouvez vous y référer pour obtenir tous les détails d’implémentation.

Fichiers de configuration

Les applications web qui connectent les utilisateurs à l’aide de la plateforme d’identités Microsoft sont généralement configurées via des fichiers config. Ces fichiers doivent spécifier les valeurs suivantes :

L’instance de cloud, si vous souhaitez par exemple que votre application s’exécute dans les clouds nationaux. Les différentes options sont les suivantes :
- https://login.microsoftonline.com/ pour cloud public Azure
- https://login.microsoftonline.us/ pour Azure – Gouvernement des États-Unis
- https://login.microsoftonline.de/ pour Microsoft Entra Allemagne
- https://login.partner.microsoftonline.cn/common pour Microsoft Entra Chine géré par 21Vianet
Le public dans l’ID de locataire. Les options varient selon que votre application est monolocataire ou multi-locataires.
- Le GUID de locataire obtenu à partir du portail Azure. pour connecter des utilisateurs dans votre organisation Vous pouvez également utiliser un nom de domaine.
- organizations pour connecter des utilisateurs dans n’importe quel compte professionnel ou scolaire
- common pour connecter des utilisateurs avec un compte professionnel ou scolaire ou un compte personnel Microsoft
- consumers pour connecter des utilisateurs avec un compte personnel Microsoft uniquement
L’ID client pour votre application, tel qu’il a été copié à partir du portail Azure.

Vous pouvez également voir des références à l’autorité, une concaténation des valeurs d’instance et d’ID de locataire.

Dans ASP.NET Core, ces paramètres se trouvent dans le fichier appsettings.json, dans la section « Microsoft Entra ID ».

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id here]",
    "CallbackPath": "/signin-oidc",
    "SignedOutCallbackPath": "/signout-oidc"
  }
}

Dans ASP.NET Core, il existe un autre fichier (properties\launchSettings.json) qui contient l’URL (applicationUrl) et le port TLS/SSL (sslPort) de votre application, ainsi que divers profils.

{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:3110/",
      "sslPort": 44321
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "webApp": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "http://localhost:3110/"
    }
  }
}

Dans le portail Azure, les URI de redirection à inscrire sur la page Authentification de votre application doivent correspondre à ces URL. Pour les deux fichiers de configuration précédents, il s’agirait de https://localhost:44321/signin-oidc. Cela est dû au fait que applicationUrl est http://localhost:3110, mais sslPort est spécifié (44321). CallbackPath est /signin-oidc, comme défini dans appsettings.json.

De la même façon, l’URI de déconnexion devrait être défini sur https://localhost:44321/signout-oidc.

Notes

SignedOutCallbackPath doit être défini sur le portail ou l’application pour éviter tout conflit lors de la gestion de l’événement.

Dans ASP.NET, l’application est configurée par le biais du fichier appsettings.json, lignes 12 à 15.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "TenantId": "[Enter the tenantId here]",
    "ClientId": "[Enter the Client Id here]",
  }
}

Dans le portail Azure, les URI de réponse que vous inscrivez sur la page Authentification de votre application doivent correspondre à ces URL. Autrement dit, ils doivent être https://localhost:44326/.

Dans Java, la configuration se trouve dans le fichier application.properties sous src/main/resources.

aad.clientId=Enter_the_Application_Id_here
aad.authority=https://login.microsoftonline.com/Enter_the_Tenant_Info_Here/
aad.secretKey=Enter_the_Client_Secret_Here
aad.redirectUriSignin=http://localhost:8080/msal4jsample/secure/aad
aad.redirectUriGraph=http://localhost:8080/msal4jsample/graph/me

Dans le portail Azure, les URI de réponse que vous inscrivez sur la page Authentification de votre application doivent correspondre aux instances de redirectUri que l’application définit. Autrement dit, ils doivent être http://localhost:8080/msal4jsample/secure/aad et http://localhost:8080/msal4jsample/graph/me.

Ici, les paramètres de configuration résident dans .env.dev en tant que variables d’environnement :

CLOUD_INSTANCE="Enter_the_Cloud_Instance_Id_Here" # cloud instance string should end with a trailing slash
TENANT_ID="Enter_the_Tenant_Info_Here"
CLIENT_ID="Enter_the_Application_Id_Here"
CLIENT_SECRET="Enter_the_Client_Secret_Here"

REDIRECT_URI="http://localhost:3000/auth/redirect"
POST_LOGOUT_REDIRECT_URI="http://localhost:3000"

GRAPH_API_ENDPOINT="Enter_the_Graph_Endpoint_Here" # graph api endpoint string should end with a trailing slash

EXPRESS_SESSION_SECRET="Enter_the_Express_Session_Secret_Here"

Ces paramètres sont utilisés pour créer un objet de configuration dans le fichier authConfig.js, qui sera finalement utilisé pour initialiser le nœud MSAL :

/*
 * Copyright (c) Microsoft Corporation. All rights reserved.
 * Licensed under the MIT License.
 */

require('dotenv').config({ path: '.env.dev' });

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID, // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
        authority: process.env.CLOUD_INSTANCE + process.env.TENANT_ID, // Full directory URL, in the form of https://login.microsoftonline.com/<tenant>
        clientSecret: process.env.CLIENT_SECRET // Client secret generated from the app registration in Azure portal
    },
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: 3,
        }
    }
}

const REDIRECT_URI = process.env.REDIRECT_URI;
const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI;
const GRAPH_ME_ENDPOINT = process.env.GRAPH_API_ENDPOINT + "v1.0/me";

module.exports = {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI,
    GRAPH_ME_ENDPOINT
};

Dans le portail Azure, les URI de réponse que vous inscrivez sur la page Authentification de votre application doivent correspondre aux instances de redirectUri que l’application définit (http://localhost:3000/auth/redirect).

Par souci de simplicité dans cet article, le secret client est stocké dans le fichier de configuration. Dans l’application de production, envisagez d’utiliser un coffre de clés ou une variable d’environnement. Une meilleure option consiste à utiliser un certificat.

Les paramètres de configuration sont définis dans .env en tant que variables d’environnement :

# Note: If you are using Azure App Service, go to your app's Configuration,
# and then set the following values into your app's "Application settings".

CLIENT_ID=<client id>
CLIENT_SECRET=<client secret>

# Expects a full authority URL such as "https://login.microsoftonline.com/TENANT_GUID"
# or "https://login.microsoftonline.com/contoso.onmicrosoft.com".
# Alternatively, leave it undefined if you are building a multi-tenant app in world-wide cloud
#AUTHORITY=<authority url>

Ces variables d’environnement sont référencées dans app_config.py :

import os

# Application (client) ID of app registration
CLIENT_ID = os.getenv("CLIENT_ID")
# Application's generated client secret: never check this into source control!
CLIENT_SECRET = os.getenv("CLIENT_SECRET")

# You can configure your authority via environment variable
# Defaults to a multi-tenant app in world-wide cloud
AUTHORITY = os.getenv("AUTHORITY", "https://login.microsoftonline.com/common")

REDIRECT_PATH = "/getAToken"  # Used for forming an absolute URL to your redirect URI.
# The absolute URL must match the redirect URI you set
# in the app's registration in the Azure portal.

# You can find more Microsoft Graph API endpoints from Graph Explorer
# https://developer.microsoft.com/en-us/graph/graph-explorer
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'  # This resource requires no admin consent

# You can find the proper permission names from this document
# https://docs.microsoft.com/en-us/graph/permissions-reference
SCOPE = ["User.ReadBasic.All"]

# Tells the Flask-session extension to store sessions in the filesystem
SESSION_TYPE = "filesystem"
# Using the file system will not work in most production systems,
# it's better to use a database-backed session store instead.

Le fichier .env ne doit jamais être archivé dans le contrôle de code source, car il contient des secrets. L’exemple de démarrage rapide inclut un fichier .gitignore qui empêche l’enregistrement du fichier .env.

# Environments
.env

Code d’initialisation

Les différences de code d’initialisation dépendent de la plateforme. Pour ASP.NET Core et ASP.NET, la connexion des utilisateurs est déléguée à l’intergiciel (middleware) OpenID Connect. À l’heure actuelle, le modèle ASP.NET ou ASP.NET Core génère des applications web pour le point de terminaison Azure AD v1.0. Un peu de configuration est nécessaire pour les adapter à la plateforme d’identités Microsoft.

Dans les applications web ASP.NET Core (et les API web), l’application est protégée, car vous disposez d’un attribut Authorize sur les contrôleurs ou les actions des contrôleurs. Cet attribut vérifie que l’utilisateur est authentifié. Avant la publication de .NET 6, l’initialisation du code était dans le fichier Startup.cs. Les nouveaux projets ASP.NET Core avec .NET 6 ne contiennent plus de fichier Startup.cs. La prise de sa place est le fichier Program.cs. Le reste de ce didacticiel se rapporte à .NET 5 ou inférieur.

Notes

Si vous souhaitez démarrer directement avec les nouveaux modèles ASP.NET Core pour la plateforme d’identités Microsoft, qui tirent profit de Microsoft.Identity.Web, vous pouvez télécharger un package NuGet en préversion contenant des modèles de projet pour .NET 5.0. Une fois l’installation effectuée, vous pouvez instancier directement les applications web ASP.NET Core (MVC ou Blazor). Pour plus d’informations, consultez Modèles de projet d’application web Microsoft.Identity.Web. Il s’agit de l’approche la plus simple, car elle permet l’exécution de toutes les étapes suivantes à votre place.

Si vous préférez démarrer votre projet avec le projet web ASP.NET Core par défaut présent dans Visual Studio ou à l’aide de dotnet new mvc --auth SingleOrg ou dotnet new webapp --auth SingleOrg, vous verrez du code semblable à celui-ci :

 services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
         .AddAzureAD(options => Configuration.Bind("AzureAd", options));

Ce code utilise le package NuGet hérité Microsoft.AspNetCore.Authentication.AzureAD.UI qui est utilisé pour créer une application Azure Active Directory v1.0. Cet article explique comment créer une application de plateforme d’identités Microsoft v2.0 qui remplace ce code.

Ajoutez les packages NuGet Microsoft.Identity.web et Microsoft.Identity.web.UI à votre projet. Supprimez le package NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI, s’il est présent.

Mettez à jour le code dans ConfigureServices afin qu’il utilise les méthodes AddMicrosoftIdentityWebApp et AddMicrosoftIdentityUI.

public class Startup
{
 ...
 // This method gets called by the runtime. Use this method to add services to the container.
 public void ConfigureServices(IServiceCollection services)
 {
  services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
         .AddMicrosoftIdentityWebApp(Configuration, "AzureAd");

  services.AddRazorPages().AddMvcOptions(options =>
  {
   var policy = new AuthorizationPolicyBuilder()
                 .RequireAuthenticatedUser()
                 .Build();
   options.Filters.Add(new AuthorizeFilter(policy));
  }).AddMicrosoftIdentityUI();

Dans la méthode Configure dans Startup.cs, activez l’authentification avec un appel à app.UseAuthentication(); et app.MapControllers();.

// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
 // more code here
 app.UseAuthentication();
 app.UseAuthorization();

 app.MapRazorPages();
 app.MapControllers();
 // more code here
}

Dans ce code :

La méthode d’extension AddMicrosoftIdentityWebApp est définie dans Microsoft.Identity.Web, qui
- Configure les options pour lire le fichier de configuration (ici à partir de la section « Microsoft Entra ID »)
- Configure les options d’OpenID Connect afin que l’autorité soit la plateforme d’identités Microsoft.
- Valide l’émetteur du jeton.
- Garantit que les revendications correspondant au nom sont mappées à partir de la revendication preferred_username dans le jeton d’ID.
En plus de l’objet de configuration, vous pouvez spécifier le nom de la section de configuration lors de l’appel de AddMicrosoftIdentityWebApp. Par défaut, il s’agit de AzureAd.
AddMicrosoftIdentityWebApp a d’autres paramètres pour des scénarios avancés. Par exemple, le suivi des événements de l’intergiciel OpenId Connect peut vous aider à dépanner votre application web si l’authentification ne fonctionne pas. La définition du paramètre facultatif subscribeToOpenIdConnectMiddlewareDiagnosticsEvents sur true vous montrera comment les informations sont traitées par le jeu d’intergiciels d’ASP.NET Core lors de leur progression de la réponse HTTP à l’identité de l’utilisateur dans HttpContext.User.
La méthode d’extension AddMicrosoftIdentityUI est définie dans Microsoft.Identity.web.UI. Il fournit un contrôleur par défaut pour gérer la connexion et la déconnexion.

Pour plus d’informations sur la façon dont Microsoft.Identity.Web vous permet de créer des applications web, consultez Applications web dans microsoft-identity-web.

Le code lié à l’authentification dans l’application web ASP.NET et les API web se trouve dans le fichier App_Start/Startup.Auth.cs.

 public void ConfigureAuth(IAppBuilder app)
 {
  app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

  OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
  factory.Build();
  app.AddMicrosoftIdentityWebApi(factory);
 }

L’exemple Java utilise le framework Spring. L’application est protégée parce que vous implémentez un filtre, qui intercepte chaque réponse HTTP. Dans le guide de démarrage rapide pour les applications web Java, ce filtre est AuthFilter dans src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

Le filtre traite le flux code d’autorisation OAuth 2.0 et vérifie si l’utilisateur est authentifié (méthode isAuthenticated()). Si l’utilisateur n’est pas authentifié, il calcule l’URL des points de terminaison d’autorisation Microsoft Entra et redirige le navigateur vers cet URI.

Lorsque la réponse arrive, contenant le code d’autorisation, il acquiert le jeton à l’aide de MSAL Java. Lorsqu’il reçoit enfin le jeton du point de terminaison de jeton (sur l’URI de redirection), l’utilisateur est connecté.

Pour plus d’informations, consultez la méthode doFilter() dans AuthFilter.java.

Notes

Le code de doFilter() est écrit dans un ordre légèrement différent, mais le flux est celui décrit.

Pour plus d’informations sur le flux du code d’autorisation déclenché par cette méthode, consultez Plateforme d’identités Microsoft et flux de code d’autorisation OAuth 2.0.

L’exemple Node utilise l’infrastructure Express. MSAL est initialisé dans le gestionnaire de routage d’authentification :

var express = require('express');

const authProvider = require('../auth/AuthProvider');
const { REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

const router = express.Router();

router.get('/signin', authProvider.login({
    scopes: [],
    redirectUri: REDIRECT_URI,
    successRedirect: '/'

L’exemple Python est généré avec l’infrastructure Flask, bien que d’autres infrastructures comme Django puissent également être utilisées. L’application Flask est initialisée avec la configuration de l’application en haut de app.py :

import identity
import identity.web
import requests
from flask import Flask, redirect, render_template, request, session, url_for
from flask_session import Session

import app_config

app = Flask(__name__)
app.config.from_object(app_config)
Session(app)

Ensuite, le code construit un objet auth à l’aide du package d’identité.

auth = identity.web.Auth(
    session=session,
    authority=app.config["AUTHORITY"],
    client_id=app.config["CLIENT_ID"],
    client_credential=app.config["CLIENT_SECRET"],
)

Étape suivante

Se connecter et se déconnecter

Partage via

Application web qui connecte les utilisateurs : Configuration de code

Bibliothèques Microsoft prenant en charge les applications web

Fichiers de configuration

Code d’initialisation

Étape suivante

Commentaires

Ressources supplémentaires