Aplikasi web yang memasukkan pengguna: Konfigurasi kode

Artikel
07/22/2022
10 menit untuk membaca

Pelajari cara mengonfigurasi kode untuk aplikasi web Anda 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
Node.js	MSAL Node	msal-node	Mulai Cepat			GA
Python	MSAL Python	msal	Mulai Cepat			GA

¹Ketentuan penggunaan tambahan untuk Pratinjau Microsoft Azure berlaku untuk pustaka dalam Pratinjau umum.

² Pustaka Microsoft.IdentityModel hanya memvalidasi token - pustaka ini tidak dapat meminta ID atau mengakses token.

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. Ini adalah nilai yang harus Anda tentukan dalam konfigurasi:

Instans cloud (Instance) jika Anda ingin aplikasi Anda berjalan di cloud nasional, misalnya
Audiens di ID penyewa (TenantId)
ID klien (ClientId) untuk aplikasi Anda, seperti yang disalin dari portal Microsoft Azure

Anda mungkin juga melihat referensi ke Authority. Nilai Authority adalah penggabungan nilai Instance dan TenantId.

Di ASP.NET Core, pengaturan ini terletak di file appsettings.json, di bagian "AzureAd".

{
  "AzureAd": {
    // Azure cloud instance among:
    // - "https://login.microsoftonline.com/" for Azure public cloud
    // - "https://login.microsoftonline.us/" for Azure US government
    // - "https://login.microsoftonline.de/" for Azure AD Germany
    // - "https://login.partner.microsoftonline.cn/common" for Azure AD China operated by 21Vianet
    "Instance": "https://login.microsoftonline.com/",

    // Azure AD audience among:
    // - "TenantId" as a GUID obtained from the Azure portal to sign in users in your organization
    // - "organizations" to sign in users in any work or school account
    // - "common" to sign in users with any work or school account or Microsoft personal account
    // - "consumers" to sign in users with a Microsoft personal account only
    "TenantId": "[Enter the tenantId here]",

    // Client ID (application ID) obtained from the Azure portal
    "ClientId": "[Enter the Client Id]",
    "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 bahwa applicationUrl adalah 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.

Di ASP.NET, aplikasi dikonfigurasi melalui file Web.config, baris 12 hingga 15.

<?xml version="1.0" encoding="utf-8"?>
<!--
  For more information on how to configure your ASP.NET application, visit
  https://go.microsoft.com/fwlink/?LinkId=301880
  -->
<configuration>
  <appSettings>
    <add key="webpages:Version" value="3.0.0.0" />
    <add key="webpages:Enabled" value="false" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />
    <add key="ida:ClientId" value="[Enter your client ID, as obtained from the app registration portal]" />
    <add key="ida:ClientSecret" value="[Enter your client secret, as obtained from the app registration portal]" />
    <add key="ida:AADInstance" value="https://login.microsoftonline.com/{0}{1}" />
    <add key="ida:RedirectUri" value="https://localhost:44326/" />
    <add key="vs:EnableBrowserLink" value="false" />
  </appSettings>

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

/**
 * 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: "Info",
        }
    }
}

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).

Catatan

Mulai cepat ini mengusulkan untuk menyimpan rahasia klien dalam file konfigurasi untuk kesederhanaan. Di aplikasi produksi, Anda ingin menggunakan cara lain untuk menyimpan rahasia, seperti key vault atau variabel lingkungan.

Berikut adalah file konfigurasi Python di app_config.py:

CLIENT_SECRET = "Enter_the_Client_Secret_Here"
AUTHORITY = "https://login.microsoftonline.com/common"
CLIENT_ID = "Enter_the_Application_Id_here"
ENDPOINT = 'https://graph.microsoft.com/v1.0/users'
SCOPE = ["User.ReadBasic.All"]
SESSION_TYPE = "filesystem"  # So the token cache will be stored in a server-side session

Catatan

CLIENT_SECRET = os.getenv("CLIENT_SECRET")
if not CLIENT_SECRET:
    raise ValueError("Need to define CLIENT_SECRET environment variable")

Kode inisialisasi

Kode inisialisasi berbeda tergantung platform. Untuk ASP.NET Core dan ASP.NET, pengguna yang masuk didelegasikan ke middleware OpenID Connect. Template ASP.NET atau ASP.NET Core menghasilkan aplikasi web untuk titik akhir Microsoft Azure Active Directory (Azure AD) v1.0. Beberapa konfigurasi diperlukan untuk menyesuaikannya dengan platform identitas Microsoft. Dalam kasus Java, ini ditangani oleh Spring dengan kerja sama aplikasi.

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, kode yang menginisialisasi aplikasi ada di 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.

Untuk menambahkan autentikasi dengan platform identitas Microsoft (dulu Microsoft Azure Active Directory v2.0), Anda harus menambahkan kode berikut. Komentar dalam kode harus jelas.

Catatan

Jika Anda ingin memulai langsung dengan templat ASP.NET Core baru untuk platform identitas Microsoft, yang memanfaatkan Microsoft.Identity.Web, Anda dapat mengunduh pratinjau paket NuGet yang berisi templat proyek untuk .NET Core 3.1 dan .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 di bawah ini 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 warisan paket NuGet Microsoft.AspNetCore.Authentication.AzureAD.UI yang digunakan untuk membuat aplikasi Azure AD v1.0. Artikel ini menjelaskan cara membuat aplikasi platform identitas Microsoft (Microsoft Azure Active Directory v2.0) yang menggantikan kode tersebut.

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

Perbarui kode di ConfigureServices agar menggunakan metode AddMicrosoftIdentityWebAppAuthentication 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.AddMicrosoftIdentityWebAppAuthentication(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 di atas:

Metode ekstensi AddMicrosoftIdentityWebAppAuthentication didefinisikan dalam Microsoft.Identity.Web. Ini:
- Menambahkan layanan autentikasi.
- Mengonfigurasi opsi untuk membaca file konfigurasi (di sini dari bagian "AzureAD")
- 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 AddMicrosoftIdentityWebAppAuthentication. Secara default, ini adalah AzureAd.
AddMicrosoftIdentityWebAppAuthentication 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());

  app.UseOpenIdConnectAuthentication(
    new OpenIdConnectAuthenticationOptions
    {
     // Authority` represents the identity platform endpoint - https://login.microsoftonline.com/common/v2.0.
     // `Scope` describes the initial permissions that your app will need.
     //  See https://azure.microsoft.com/documentation/articles/active-directory-v2-scopes/.
     ClientId = clientId,
     Authority = String.Format(CultureInfo.InvariantCulture, aadInstance, "common", "/v2.0"),
     RedirectUri = redirectUri,
     Scope = "openid profile",
     PostLogoutRedirectUri = redirectUri,
    });
 }

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 mengomputasi URL titik akhir otorisasi Microsoft Azure Active Directory, 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.

Node membuat sampel kerangka kerja Ekspres. MSAL diinisialisasi dalam penangan rute auth:

var express = require('express');
var msal = require('@azure/msal-node');

var {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI
} = require('../authConfig');

const router = express.Router();
const msalInstance = new msal.ConfidentialClientApplication(msalConfig);

Sampel Python menggunakan Flask. Inisialisasi Flask dan MSAL Python dilakukan di app.py#L1-L28.

import uuid
import requests
from flask import Flask, render_template, session, request, redirect, url_for
from flask_session import Session  # https://pythonhosted.org/Flask-Session
import msal
import app_config

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

Langkah berikutnya

Di artikel berikutnya, Anda akan mempelajari cara memicu masuk dan keluar.

Beralih ke artikel berikutnya dalam skenario ini, Masuk dan keluar.