Web-app waarmee gebruikers worden aangemeld: codeconfiguratie

Artikel
10/24/2023

Meer informatie over het configureren van de code voor uw web-app waarmee gebruikers worden aangemeld.

Microsoft-bibliotheken die web-apps ondersteunen

De volgende Microsoft-bibliotheken worden gebruikt om een web-app (en een web-API) te beveiligen:

Taal/framework	Project over GitHub	Pakket	Aan de slag	Gebruikers aanmelden	Toegang krijgen tot web-API's	Algemeen beschikbaar (GA) of Openbare preview¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	Snelstartgids			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	Snelstartgids			GA
Java	MSAL4J	msal4j	Snelstartgids			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Zelfstudie			GA
Node.js	MSAL-knooppunt	msal-node	Snelstartgids			GA
Python	MSAL Python	msal				GA
Python	identity	identity	Snelstartgids			--

⁽¹⁾Universele licentievoorwaarden voor onlineservices zijn van toepassing op bibliotheken in openbare preview.

⁽²⁾ De bibliotheek Microsoft.IdentityModel valideert alleen tokens. Er kunnen geen id- of toegangstokens worden aangevraagd.

Selecteer het tabblad dat overeenkomt met het platform waarin u geïnteresseerd bent:

Codefragmenten in dit artikel en het volgende worden geëxtraheerd uit de incrementele zelfstudie ASP.NET Core-web-app, hoofdstuk 1.

U kunt deze zelfstudie raadplegen voor de volledige details over implementatie.

Configuratiebestanden

Webtoepassingen die gebruikers aanmelden met behulp van het Microsoft-identiteitsplatform worden geconfigureerd via configuratiebestanden. Deze bestanden moeten de volgende waarden opgeven:

Het cloudexemplaren als u wilt dat uw app bijvoorbeeld wordt uitgevoerd in nationale clouds. De verschillende opties zijn:
- https://login.microsoftonline.com/ voor openbare Azure-cloud
- https://login.microsoftonline.us/ voor Azure US Government
- https://login.microsoftonline.de/ voor Microsoft Entra Duitsland
- https://login.partner.microsoftonline.cn/common voor Microsoft Entra China beheerd door 21Vianet
De doelgroep in de tenant-id. De opties variëren, afhankelijk van of uw app één tenant of multitenant is.
- De tenant-GUID die is verkregen via Azure Portal om gebruikers in uw organisatie aan te melden. U kunt ook een domeinnaam gebruiken.
- organizations om gebruikers aan te melden in een werk- of schoolaccount
- common om gebruikers aan te melden met een werk- of schoolaccount of persoonlijk Microsoft-account
- consumers om gebruikers alleen aan te melden met een persoonlijk Microsoft-account
De client-id voor uw toepassing, zoals gekopieerd uit Azure Portal

Mogelijk ziet u ook verwijzingen naar de instantie, een samenvoeging van de instantie - en tenant-id-waarden .

In ASP.NET Core bevinden deze instellingen zich in het appsettings.json bestand, in de sectie '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"
  }
}

In ASP.NET Core bevat een ander bestand (properties\launchSettings.json) de URL (applicationUrl) en de TLS/SSL-poort (sslPort) voor uw toepassing en verschillende profielen.

{
  "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/"
    }
  }
}

In Azure Portal moeten de omleidings-URI's die u registreert op de verificatiepagina voor uw toepassing overeenkomen met deze URL's. Voor de twee voorgaande configuratiebestanden zouden ze https://localhost:44321/signin-oidc zijn. De reden hiervoor is, applicationUrlhttp://localhost:3110maar sslPort is opgegeven (44321). CallbackPath is /signin-oidc, zoals gedefinieerd in appsettings.json.

Op dezelfde manier wordt de afmeldings-URI ingesteld op https://localhost:44321/signout-oidc.

Notitie

SignedOutCallbackPath moet zijn ingesteld op de portal of de toepassing om conflicten te voorkomen tijdens het afhandelen van de gebeurtenis.

In ASP.NET wordt de toepassing geconfigureerd via het appsettings.json-bestand , regel 12 tot en met 15.

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

In Azure Portal moeten de antwoord-URI's die u registreert op de verificatiepagina voor uw toepassing overeenkomen met deze URL's. Dat wil zeggen: ze moeten https://localhost:44326/ zijn.

In Java bevindt de configuratie zich in het bestand application.properties onder 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

In Azure Portal moeten de antwoord-URI's die u registreert op de verificatiepagina voor uw toepassing overeenkomen met de redirectUri-exemplaren die door de toepassing worden gedefinieerd. Dat wil zeggen: ze moeten http://localhost:8080/msal4jsample/secure/aad en http://localhost:8080/msal4jsample/graph/me zijn.

Hier bevinden de configuratieparameters zich in .env.dev als omgevingsvariabelen:

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"

Deze parameters worden gebruikt om een configuratieobject te maken in het bestand authConfig.js, dat uiteindelijk wordt gebruikt om MSAL Node te initialiseren:

/*
 * 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
};

In Azure Portal moeten de antwoord-URI's die u registreert op de verificatiepagina voor uw toepassing overeenkomen met de redirectUri-exemplaren die door de toepassing worden gedefinieerd (http://localhost:3000/auth/redirect).

Ter vereenvoudiging in dit artikel wordt het clientgeheim opgeslagen in het configuratiebestand. Overweeg in de productie-app een sleutelkluis of een omgevingsvariabele te gebruiken. Een nog betere optie is om een certificaat te gebruiken.

De configuratieparameters worden in .env ingesteld als omgevingsvariabelen:

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

Naar deze omgevingsvariabelen wordt verwezen in 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.

Het .env-bestand mag nooit worden ingecheckt bij broncodebeheer, omdat het geheimen bevat. Het quickstart-voorbeeld bevat een .gitignore-bestand dat voorkomt dat het .env-bestand wordt ingecheckt.

# Environments
.env

Initialisatiecode

De verschillen in initialisatiecode zijn afhankelijk van het platform. Voor ASP.NET Core en ASP.NET wordt het aanmelden van gebruikers gedelegeerd aan de OpenID Connect-middleware. De ASP.NET of ASP.NET Core-sjabloon genereert webtoepassingen voor het Azure AD v1.0-eindpunt. Sommige configuraties moeten worden aangepast aan het Microsoft-identiteitsplatform.

In ASP.NET Core-web-apps (en -web-API's) wordt de toepassing beveiligd omdat uw controllers of controlleracties over een Authorize-kenmerk beschikken. Met dit kenmerk wordt gecontroleerd of de gebruiker is geverifieerd. Vóór de release van .NET 6 stond de code-initialisatie in het Startup.cs-bestand . Nieuwe ASP.NET Core-projecten met .NET 6 bevatten niet meer het bestand Startup.cs. Het is vervangen door het bestand Program.cs. De rest van deze zelfstudie heeft betrekking op .NET 5 of lager.

Notitie

Als u direct wilt beginnen met de nieuwe ASP.NET Core-sjablonen voor het Microsoft Identity Platform, die gebruikmaken van Microsoft.Identity.Web, kunt u een voorbeeld van een NuGet-pakket downloaden met projectsjablonen voor .NET 5.0. Vervolgens kunt u na installatie rechtstreeks ASP.NET Core-webtoepassingen (MVC of Blazor) instantiëren. Zie projectsjablonen voor Microsoft.Identity.Web-web-apps voor meer informatie. Dit is de eenvoudigste aanpak, omdat alle volgende stappen voor u worden uitgevoerd.

Als u uw project liever wilt starten met het huidige standaard ASP.NET Core-webproject in Visual Studio of met behulp van dotnet new mvc --auth SingleOrg of dotnet new webapp --auth SingleOrg, ziet u code zoals hierna volgt:

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

Deze code maakt gebruik van het verouderde NuGet-pakket Microsoft.AspNetCore.Authentication.AzureAD.UI dat wordt gebruikt om een Azure Active Directory v1.0-toepassing te maken. In dit artikel wordt uitgelegd hoe u een Microsoft Identity Platform v2.0-toepassing maakt die die code vervangt.

Voeg de NuGet-pakketten Microsoft.Identity.Web en Microsoft.Identity.Web.UI toe aan uw project. Verwijder het Microsoft.AspNetCore.Authentication.AzureAD.UI NuGet-pakket als het aanwezig is.

Werk de code bij in ConfigureServices zodat deze van de methode AddMicrosoftIdentityWebApp en AddMicrosoftIdentityUI gebruikmaakt.

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();

Schakel in de methode Configure in Startup.cs verificatie in met een aanroep naar app.UseAuthentication(); en 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
}

In die code:

De AddMicrosoftIdentityWebApp extensiemethode wordt gedefinieerd in Microsoft.Identity.Web, die;
- Configureert opties voor het lezen van het configuratiebestand (hier in de sectie 'Microsoft Entra ID')
- worden de OpenID Connect-opties geconfigureerd, zodat de instantie het Microsoft-identiteitsplatform is;
- wordt de verlener van het token gevalideerd;
- wordt gecontroleerd of de claims die overeenkomen met de naam, worden toegewezen vanuit de preferred_username-claim in het id-token.
Naast het configuratieobject kunt u de naam van de configuratiesectie opgeven bij het aanroepen van AddMicrosoftIdentityWebApp. Dit is standaard AzureAd.
AddMicrosoftIdentityWebApp heeft andere parameters voor geavanceerde scenario's. Wanneer u bijvoorbeeld gebeurtenissen met OpenID Connect-middleware traceert, kunt u problemen met uw webtoepassing oplossen als verificatie niet werkt. Als u de optionele parameter subscribeToOpenIdConnectMiddlewareDiagnosticsEvents op true instelt, ziet u hoe informatie wordt verwerkt door de set ASP.NET Core-middleware terwijl deze voortgaat van het HTTP-antwoord naar de identiteit van de gebruiker in HttpContext.User.
De uitbreidingsmethode AddMicrosoftIdentityUI wordt gedefinieerd in Microsoft.Identity.Web.UI. Hiermee wordt een standaardcontroller geboden voor het afhandelen van aanmelding en afmelden.

Zie Web Apps in Microsoft.Identity.Web voor meer informatie over hoe u web-apps kunt maken met Microsoft.Identity.Web.

De code met betrekking tot verificatie in een ASP.NET-web-app en web-API's bevindt zich in het bestand 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);
 }

Het voorbeeld met Java maakt gebruik van het Spring-framework. De toepassing is beveiligd omdat u een filter implementeert, waarmee elk HTTP-antwoord wordt onderschept. In de quickstart voor Java-web-apps bevindt dit filter zich AuthFilter in src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

Het filter verwerkt de OAuth 2.0-autorisatiecodestroom en controleert of de gebruiker is geverifieerd (methode isAuthenticated()). Als de gebruiker niet is geverifieerd, wordt de URL van de Microsoft Entra-autorisatie-eindpunten berekend en wordt de browser omgeleid naar deze URI.

Wanneer het antwoord met de autorisatiecode binnenkomt, wordt het token verkregen met behulp van MSAL Java. Wanneer het token uiteindelijk wordt ontvangen vanuit het tokeneindpunt (op de omleidings-URI), wordt de gebruiker aangemeld.

Zie de methode doFilter() in AuthFilter.java voor meer informatie.

Notitie

De code van de doFilter() is in een iets andere volgorde geschreven, maar het is de stroom die wordt beschreven.

Zie het Microsoft-identiteitsplatform en de OAuth 2.0-autorisatiecodestroom voor meer informatie over de autorisatiecodestroom die door deze methode wordt geactiveerd.

Het knooppuntvoorbeeld maakt gebruik van het Express-framework. MSAL wordt geïnitialiseerd in de auth-routehandler:

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: '/'

Het Python-voorbeeld is gebouwd met het Flask-framework, hoewel ook andere frameworks zoals Django kunnen worden gebruikt. De Flask-app wordt geïnitialiseerd met de app-configuratie bovenaan 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)

Vervolgens maakt de code een auth object met behulp van het identiteitspakket.

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

Volgende stappen

In het volgende artikel leert u hoe u aanmeldingen en afmeldingen activeert.

Ga verder met het volgende artikel in dit scenario, Aanmelden en afmelden.

Web-app waarmee gebruikers worden aangemeld: codeconfiguratie

Microsoft-bibliotheken die web-apps ondersteunen

Configuratiebestanden

Initialisatiecode

Volgende stappen

Aanvullende resources