Aplikasi web yang memasukkan pengguna: Konfigurasi kode

Artikel
08/01/2024

Artikel ini menjelaskan cara mengonfigurasi kode untuk aplikasi web yang memasukkan pengguna.

Pustaka Microsoft yang mendukung aplikasi web

Pustaka Microsoft berikut digunakan untuk melindungi aplikasi web (dan API web):

Bahasa pemrogram/kerangka kerja	Proyek di GitHub	Paket	Persiapan memulai	Memasukkan pengguna	Mengakses API web	Tersedia secara umum (GA) atau Pratinjau umum¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
Inti ASP.NET	Inti ASP.NET	Microsoft.AspNetCore.Authentication	Mulai Cepat			GA
Inti ASP.NET	Microsoft.Identity.Web	Microsoft.Identity.Web	Mulai Cepat			GA
Java	MSAL4J	msal4j	Mulai Cepat			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	Tutorial			GA
Node.js	MSAL Node	msal-node	Mulai Cepat			GA
Python	MSAL Python	msal				GA
Python	identitas	identitas	Mulai Cepat			--

⁽¹⁾ Ketentuan Lisensi Universal untuk Layanan Online berlaku untuk pustaka dalam Pratinjau publik.

⁽²⁾ Pustaka Microsoft.IdentityModel hanya memvalidasi token - pustaka tidak dapat meminta ID atau token akses.

Pilih tab yang sesuai dengan platform yang Anda minati:

Cuplikan kode dalam artikel ini dan berikut ini diekstrak dari tutorial inkremental aplikasi web Core ASP.NET, bab 1.

Anda mungkin ingin merujuk ke tutorial ini untuk detail penerapan lengkap.

File konfigurasi

Aplikasi web yang memasukkan pengguna menggunakan platform identitas Microsoft dikonfigurasi melalui file konfigurasi. File-file tersebut harus menentukan nilai berikut:

Instans cloud jika Anda ingin aplikasi Anda berjalan di cloud nasional, misalnya. Opsi yang berbeda meliputi;
- https://login.microsoftonline.com/ untuk cloud publik Azure
- https://login.microsoftonline.us/ untuk pemerintah As Azure
- https://login.microsoftonline.de/ untuk Microsoft Entra Jerman
- https://login.partner.microsoftonline.cn/common untuk Microsoft Entra Tiongkok yang dioperasikan oleh 21Vianet
Audiens di ID penyewa. Opsi bervariasi tergantung pada apakah aplikasi Anda adalah penyewa tunggal atau multipenyewa.
- GUID penyewa diperoleh dari portal Azure untuk memasukkan pengguna di organisasi Anda. Anda juga dapat menggunakan nama domain.
- organizations untuk memasukkan pengguna di akun kantor atau sekolah apa pun
- common untuk memasukkan pengguna dengan akun kantor atau sekolah atau akun pribadi Microsoft
- consumers untuk memasukkan pengguna dengan akun pribadi Microsoft saja
ID klien untuk aplikasi Anda, seperti yang disalin dari portal Azure

Anda mungkin juga melihat referensi ke otoritas, perangkaian nilai INSTANS dan ID penyewa.

Di ASP.NET Core, pengaturan ini terletak di file appsettings.json , di bagian "ID Microsoft Entra".

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

Di ASP.NET Core, file lain (properties\launchSettings.json) berisi URL (applicationUrl) dan port TLS/SSL (sslPort) untuk aplikasi dan berbagai profil Anda.

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

Di portal Microsoft Azure, URI pengalihan yang Anda daftarkan di halaman Autentikasi untuk aplikasi Anda harus cocok dengan URL ini. Untuk dua file konfigurasi sebelumnya akan menjadi https://localhost:44321/signin-oidc. Alasannya adalah applicationUrl http://localhost:3110, tetapi sslPort ditentukan (44321). CallbackPath adalah /signin-oidc, seperti yang ditentukan dalam appsettings.json.

Dengan cara yang sama, URI keluar akan ditetapkan ke https://localhost:44321/signout-oidc.

Catatan

SignedOutCallbackPath harus diatur ke portal atau aplikasi untuk menghindari konflik saat menangani peristiwa.

Dalam ASP.NET, aplikasi dikonfigurasi melalui file appsettings.json , baris 12 hingga 15.

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

Di portal Microsoft Azure, URI balasan yang Anda daftarkan di halaman Autentikasi untuk aplikasi Anda harus cocok dengan URL ini. Artinya, URI tersebut harus https://localhost:44326/.

Di Java, konfigurasi terletak di file application.properties yang terletak di bawah 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

Di portal Microsoft Azure, URI balasan yang Anda daftarkan di halaman Autentikasi untuk aplikasi Anda harus cocok dengan instans redirectUri yang ditentukan aplikasi. Artinya, URI tersebut harus http://localhost:8080/msal4jsample/secure/aad dan http://localhost:8080/msal4jsample/graph/me.

Di sini, parameter konfigurasi berada di .env.dev sebagai variabel lingkungan:

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"

Parameter ini digunakan untuk membuat objek konfigurasi di file authConfig.js, yang nantinya akan digunakan untuk menginisialisasi Node 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
};

Di portal Microsoft Azure, URI balasan yang Anda daftarkan di halaman Autentikasi untuk aplikasi Anda harus cocok dengan instans redirectUri yang ditentukan aplikasi (http://localhost:3000/auth/redirect).

Untuk kesederhanaan dalam artikel ini, rahasia klien disimpan dalam file konfigurasi. Di aplikasi produksi, pertimbangkan untuk menggunakan brankas kunci atau variabel lingkungan. Opsi yang lebih baik adalah menggunakan sertifikat.

Parameter konfigurasi diatur dalam .env sebagai variabel lingkungan:

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

Variabel lingkungan tersebut dirujuk dalam 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.

File .env tidak boleh diperiksa ke kontrol sumber, karena berisi rahasia. Sampel mulai cepat menyertakan file .gitignore yang mencegah file .env dicek masuk.

# Environments
.env

Kode inisialisasi

Perbedaan kode inisialisasi bergantung pada platform. Untuk ASP.NET Core dan ASP.NET, pengguna yang masuk didelegasikan ke middleware OpenID Connect. Templat ASP.NET atau ASP.NET Core menghasilkan aplikasi web untuk titik akhir Azure AD v1.0. Beberapa konfigurasi diperlukan untuk menyesuaikannya dengan platform identitas Microsoft.

Selain aplikasi web ASP.NET Core (dan API web), aplikasi dilindungi karena Anda memiliki atribut Authorize pada pengontrol atau tindakan pengontrol. Atribut ini memeriksa bahwa pengguna sudah diautentikasi. Sebelum rilis .NET 6, inisialisasi kode berada dalam file Startup.cs . Proyek ASP.NET Core baru dengan .NET 6 tidak lagi berisi file Startup.cs. Ia digantikan oleh file Program.cs. Bagian selanjutnya dari tutorial ini berkaitan dengan .NET 5 atau yang lebih rendah.

Catatan

Jika Anda ingin mulai langsung dengan templat ASP.NET Core baru untuk platform identitas Microsoft, yang memanfaatkan Microsoft.Identity.Web, Anda dapat mengunduh paket NuGet pratinjau yang berisi templat proyek untuk .NET 5.0. Selanjutnya, setelah diinstal, Anda dapat langsung membuat contoh aplikasi web ASP.NET Core (MVC atau Blazor). Lihat Template proyek aplikasi web Microsoft.Identity.Web untuk detailnya. Ini adalah pendekatan paling sederhana karena akan melakukan semua langkah berikut untuk Anda.

Jika Anda lebih suka memulai proyek dengan proyek web ASP.NET Core default saat ini dalam Visual Studio atau dengan menggunakan dotnet new mvc --auth SingleOrg atau dotnet new webapp --auth SingleOrg, Anda akan melihat kode seperti berikut:

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

Kode ini menggunakan paket NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI warisan yang digunakan untuk membuat aplikasi Azure Active Directory v1.0. Artikel ini menjelaskan cara membuat aplikasi platform identitas Microsoft v2.0 yang menggantikan kode tersebut.

Tambahkan paket NuGet Microsoft.Identity.Web dan Microsoft.Identity.Web.UI ke proyek Anda. Microsoft.AspNetCore.Authentication.AzureAD.UI Hapus paket NuGet jika ada.

Perbarui kode di ConfigureServices agar menggunakan metode AddMicrosoftIdentityWebApp dan 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();

Dalam metode Configure pada Startup.cs, aktifkan autentikasi dengan panggilan ke app.UseAuthentication(); dan 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
}

Dalam kode itu:

Metode AddMicrosoftIdentityWebApp ekstensi didefinisikan dalam Microsoft.Identity.Web, yang;
- Mengonfigurasi opsi untuk membaca file konfigurasi (di sini dari bagian "ID Microsoft Entra")
- Mengonfigurasi opsi OpenID Connect agar otoritasnya adalah platform identitas Microsoft.
- Memvalidasi pengeluar sertifikat token.
- Memastikan klaim yang sesuai dengan nama dipetakan dari klaim preferred_username dalam token ID.
Selain objek konfigurasi, Anda dapat menentukan nama bagian konfigurasi saat memanggil AddMicrosoftIdentityWebApp. Secara default, ini adalah AzureAd.
AddMicrosoftIdentityWebApp memiliki parameter lain untuk skenario tingkat lanjut. Misalnya, menelusuri kejadian middleware OpenID Connect dapat membantu Anda memecahkan masalah aplikasi web jika autentikasi tidak berfungsi. Mengatur parameter opsional subscribeToOpenIdConnectMiddlewareDiagnosticsEvents ke true akan memperlihatkan bagaimana informasi diproses oleh kumpulan middleware ASP.NET Core saat berkembang dari respons HTTP ke identitas pengguna di HttpContext.User.
Metode ekstensi AddMicrosoftIdentityUI didefinisikan dalam Microsoft.Identity.Web. Ini menyediakan pengontrol default untuk menangani masuk dan keluar.

Untuk informasi selengkapnya tentang bagaimana Microsoft.Identity.Web memungkinkan Anda membuat aplikasi web, lihat Web Apps di microsoft-identity-web.

Kode yang terkait dengan autentikasi dalam aplikasi web ASP.NET dan API web terletak di file App_Start/Startup.Auth.cs ini.

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

  app.UseCookieAuthentication(new CookieAuthenticationOptions());

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

Sampel Java menggunakan kerangka kerja Spring. Aplikasi dilindungi karena Anda mengimplementasikan filter, yang memotong tiap respons HTTP. Dalam mulai cepat untuk aplikasi web Java, filter ini berada AuthFilter di src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java.

Filter memproses alur kode otorisasi OAuth 2.0 dan memeriksa apakah pengguna diautentikasi (metode isAuthenticated()). Jika pengguna tidak diautentikasi, pengguna menghitung URL titik akhir otorisasi Microsoft Entra, dan mengalihkan browser ke URI ini.

Ketika respons tiba, yang berisi kode otorisasi, respons memperoleh token dengan menggunakan MSAL Java. Ketika akhirnya menerima token dari titik akhir token (pada URI pengalihan), pengguna masuk.

Untuk detailnya, lihat metode doFilter() di AuthFilter.java.

Catatan

Kode dari doFilter() ditulis dalam urutan yang sedikit berbeda, tetapi alirannya adalah yang dijelaskan.

Untuk detail tentang alur kode otorisasi yang dipicu oleh metode ini, lihat Platform identitas Microsoft dan alur kode otorisasi OAuth 2.0.

Sampel Node menggunakan kerangka kerja Ekspres. MSAL diinisialisasi dalam penangan rute auth:

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

Sampel Python dibangun dengan kerangka kerja Flask, meskipun kerangka kerja lain seperti Django juga dapat digunakan. Aplikasi Flask diinisialisasi dengan konfigurasi aplikasi di bagian atas 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)

Kemudian kode membuat auth objek menggunakan paket identitas.

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

Langkah selanjutnya

Masuk dan keluar.

Bagikan melalui

Aplikasi web yang memasukkan pengguna: Konfigurasi kode

Pustaka Microsoft yang mendukung aplikasi web

File konfigurasi

Kode inisialisasi

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: