사용자가 로그인하는 웹앱: 코드 구성

아티클
10/30/2023

사용자가 로그인하는 웹앱의 코드를 구성하는 방법을 알아봅니다.

웹앱을 지원하는 Microsoft 라이브러리

웹앱(및 웹 API)을 보호하는 데 사용되는 Microsoft 라이브러리는 다음과 같습니다.

언어 / 프레임워크	프로젝트 설정 GitHub	Package(패키지)	가져오기 시작됨	사용자 로그인	웹 API 액세스	GA(일반 공급) 또는 공개 미리 보기¹
.NET	MSAL.NET	Microsoft.Identity.Client	—			GA
.NET	Microsoft.IdentityModel	Microsoft.IdentityModel	—	²	²	GA
ASP.NET Core	ASP.NET Core	Microsoft.AspNetCore.Authentication	빠른 시작			GA
ASP.NET Core	Microsoft.Identity.Web	Microsoft.Identity.Web	빠른 시작			GA
Java	MSAL4J	msal4j	빠른 시작			GA
Spring	spring-cloud-azure-starter-active-directory	spring-cloud-azure-starter-active-directory	자습서			GA
Node.js	MSAL 노드	msal-node	빠른 시작			GA
Python	MSAL Python	msal				GA
Python	identity	identity	빠른 시작			--

⁽¹⁾온라인 서비스에 대한 유니버설 사용 조건은 공개 미리 보기의 라이브러리에 적용됩니다.

⁽²⁾Microsoft.IdentityModel 라이브러리는 토큰의 유효성 검사만 수행하고 ID 또는 액세스 토큰은 요청할 수 없습니다.

관심 있는 플랫폼에 해당하는 탭을 선택합니다.

이 문서 및 다음 항목의 코드 조각은 ASP.NET Core 웹앱 증분 자습서의 1장에서 추출되었습니다.

전체 구현에 대한 자세한 내용은 해당 자습서를 참조하는 것이 좋습니다.

구성 파일

Microsoft ID 플랫폼을 사용하여 사용자가 로그인하는 웹 애플리케이션은 구성 파일을 통해 구성됩니다. 해당 파일은 다음 값을 지정해야 합니다.

국가 클라우드 등에서 앱을 실행하려는 경우 클라우드 인스턴스. 다양한 옵션에는 다음이 포함됩니다.
- Azure 퍼블릭 클라우드의 경우 https://login.microsoftonline.com/
- https://login.microsoftonline.us/(Azure 미국 정부의 경우)
- Microsoft Entra 독일용 https://login.microsoftonline.de/
- 21Vianet에서 운영하는 Microsoft Entra 중국용 https://login.partner.microsoftonline.cn/common
테넌트 ID의 대상 그룹. 옵션은 앱이 단일 테넌트인지 다중 테넌트인지에 따라 달라집니다.
- 조직의 사용자를 로그인하기 위해 Azure Portal에서 가져오는 테넌트 GUID입니다. 도메인 이름을 사용할 수도 있습니다.
- organizations: 회사 또는 학교 계정의 사용자 로그인
- common: 회사 또는 학교 계정 또는 Microsoft 개인 계정으로 사용자 로그인
- consumers: Microsoft 개인 계정으로만 사용자 로그인
Azure Portal에서 복사한 애플리케이션의 클라이언트 ID.

또한 인스턴스와 테넌트 ID 값을 연결한 권한에 대한 참조를 볼 수도 있습니다.

ASP.NET Core에서 해당 설정은 "Microsoft Entra ID" 섹션의 appsettings.json 파일에 있습니다.

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

ASP.NET Core에서 다른 파일(properties\launchSettings.json)에는 애플리케이션 및 다양한 프로필에 대한 URL(applicationUrl) 및 TLS/SSL 포트(sslPort)가 포함되어 있습니다.

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

Azure Portal에서 애플리케이션의 인증 페이지에 등록하는 리디렉션 URL은 해당 URL과 일치해야 합니다. 위의 두 구성 파일은 https://localhost:44321/signin-oidc입니다. 그 이유는 applicationUrl이 http://localhost:3110인데 sslPort가 지정되었기 때문입니다(44321). CallbackPath는 appsettings.json에 정의된 대로 /signin-oidc입니다.

동일한 방식으로 로그아웃 URL은 https://localhost:44321/signout-oidc로 설정됩니다.

참고 항목

SignedOutCallbackPath는 이벤트를 처리하는 동안 충돌을 방지하기 위해 포털 또는 애플리케이션으로 설정해야 합니다.

ASP.NET에서 애플리케이션은 appsettings.json 파일의 12~15행을 통해 구성됩니다.

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

Azure Portal에서 애플리케이션의 인증 페이지에 등록하는 응답 URI는 해당 URL과 일치해야 합니다. 즉, https://localhost:44326/여야 합니다.

Java에서 구성은 src/main/resources에 위치한 application.properties에 있습니다.

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

Azure Portal에서 애플리케이션의 인증 페이지에 등록하는 응답 URI는 애플리케이션이 정의하는 redirectUri 인스턴스와 일치해야 합니다. 즉, http://localhost:8080/msal4jsample/secure/aad 및 http://localhost:8080/msal4jsample/graph/me여야 합니다.

여기서 구성 매개 변수는 .env.dev에 환경 변수로 상주합니다.

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"

이러한 매개 변수는 authConfig.js 파일에서 구성 개체를 만드는 데 사용되며, 결국 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
};

Azure Portal에서 애플리케이션의 인증 페이지에 등록하는 응답 URI는 애플리케이션이 정의하는 redirectUri 인스턴스와 일치해야 합니다(http://localhost:3000/auth/redirect).

이 문서에서는 편의상 클라이언트 암호를 구성 파일에 저장합니다. 프로덕션 앱에서 키 자격 증명 모음 또는 환경 변수를 사용하는 것이 좋습니다. 더 나은 옵션은 인증서를 사용하는 것입니다.

구성 매개 변수는 .env에 환경 변수로 설정됩니다.

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

해당 환경 변수는 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.

.env 파일에는 비밀이 포함되어 있으므로 소스 제어에 체크인해서는 안 됩니다. 빠른 시작 샘플에는 .env 파일이 체크인되지 않도록 하는 .gitignore 파일이 포함되어 있습니다.

# Environments
.env

초기화 코드

초기화 코드 차이는 플랫폼에 따라 다릅니다. ASP.NET Core 및 ASP.NET의 경우 사용자 로그인은 OpenID Connect 미들웨어에 위임됩니다. ASP.NET 또는 ASP.NET Core 템플릿은 Azure AD v1.0 엔드포인트에 대한 웹 애플리케이션을 생성합니다. Microsoft ID 플랫폼에 맞게 조정하려면 몇 가지 구성이 필요합니다.

ASP.NET Core 웹앱(및 웹 API)의 경우 컨트롤러 또는 컨트롤러 작업에 Authorize 특성이 있으므로 애플리케이션이 보호됩니다. 이 특성은 사용자가 인증되었는지 확인합니다. .NET 6 릴리스 이전에는 코드 초기화가 Startup.cs 파일에 있었습니다. .NET 6이 포함된 새 ASP.NET Core 프로젝트에는 더 이상 Startup.cs 파일이 포함되지 않습니다. 대신 Program.cs 파일이 포함됩니다. 이 자습서의 나머지 부분은 .NET 5 이하와 관련이 있습니다.

참고 항목

Microsoft.Identity.Web을 활용하는 Microsoft ID 플랫폼용 새 ASP.NET Core 템플릿을 사용하여 직접 시작하려는 경우에는 .NET 5.0용 프로젝트 템플릿이 포함된 미리 보기 NuGet 패키지를 다운로드할 수 있습니다. 설치가 완료되면 ASP.NET Core 웹 애플리케이션(MVC 또는 Blazor)을 직접 인스턴스화할 수 있습니다. 자세한 내용은 Microsoft.Identity.Web 웹앱 프로젝트 템플릿을 참조하세요. 이는 다음 단계를 모두 수행하므로 가장 간단한 방식입니다.

Visual Studio 내에서 현재의 기본 ASP.NET Core 웹 프로젝트를 사용하거나 dotnet new mvc --auth SingleOrg 또는 dotnet new webapp --auth SingleOrg를 사용하여 프로젝트를 시작하려는 경우 다음과 같은 코드가 표시됩니다.

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

이 코드는 Azure Active Directory v1.0 애플리케이션을 만드는 데 사용되는 레거시 Microsoft.AspNetCore.Authentication.AzureAD.UI NuGet 패키지를 사용합니다. 이 문서에서는 해당 코드를 바꾸는 Microsoft ID 플랫폼 v2.0 애플리케이션을 만드는 방법을 설명합니다.

프로젝트에 Microsoft.Identity.Web 및 Microsoft.Identity.Web.UI NuGet 패키지를 추가합니다. Microsoft.AspNetCore.Authentication.AzureAD.UI NuGet 패키지가 있는 경우 제거합니다.

AddMicrosoftIdentityWebApp 및 AddMicrosoftIdentityUI 메서드를 사용하도록 ConfigureServices의 코드를 업데이트합니다.

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

Startup.cs의 Configure 메서드에서 app.UseAuthentication(); 및 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
}

이 코드의 경우 다음과 같습니다.

AddMicrosoftIdentityWebApp 확장 메서드는 Microsoft.Identity.Web에 정의되어 있습니다.
- 옵션을 구성하여 구성 파일을 읽습니다(이 경우 "Microsoft Entra ID" 섹션에서).
- Microsoft ID 플랫폼에 권한이 부여되도록 OpenID Connect 옵션을 구성합니다.
- 토큰 발급자의 유효성을 검사합니다.
- 이름에 해당하는 클레임이 ID 토큰의 preferred_username 클레임에서 매핑되었는지 확인합니다.
구성 개체 외에도 AddMicrosoftIdentityWebApp을 호출할 때 구성 섹션의 이름을 지정할 수 있습니다. 기본적으로 AzureAd입니다.
AddMicrosoftIdentityWebApp에는 고급 시나리오에 대한 다른 매개 변수가 있습니다. 예를 들어 OpenID Connect 미들웨어 이벤트를 추적하면 인증이 작동하지 않을 때 웹 애플리케이션의 문제 해결을 지원할 수 있습니다. 선택적 매개 변수 subscribeToOpenIdConnectMiddlewareDiagnosticsEvents를 true로 설정하면 ASP.NET Core 미들웨어 집합이 HTTP 응답으로부터 HttpContext.User의 사용자 ID로 진행할 때 정보를 처리하는 방법을 보여줍니다.
AddMicrosoftIdentityUI 확장 메서드는 Microsoft.Identity.Web.UI에 정의되어 있습니다. 로그인 및 로그아웃을 처리하는 기본 컨트롤러를 제공합니다.

Microsoft.Identity.Web을 사용하여 웹앱을 만드는 방법에 대한 자세한 내용은 microsoft-identity-web의 웹앱을 참조하세요.

ASP.NET 웹앱 및 웹 API의 인증과 관련된 코드는 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);
 }

Java 샘플에서는 Spring 프레임워크를 사용합니다. 각 HTTP 응답을 가로채는 필터를 구현하기 때문에 애플리케이션이 보호됩니다. Java 웹앱의 빠른 시작에서 이 필터는 src/main/java/com/microsoft/azure/msalwebsample/AuthFilter.java의 AuthFilter입니다.

이 필터는 OAuth 2.0 인증 코드 흐름을 처리하고 사용자가 인증되었는지 확인합니다(isAuthenticated() 메서드). 사용자가 인증되지 않은 경우 Microsoft Entra 권한 부여 엔드포인트의 URL을 계산하고 브라우저를 해당 URI로 리디렉션합니다.

인증 코드를 포함하는 응답이 도착하면 MSAL Java를 사용하여 토큰을 획득합니다. 마지막으로 리디렉션 URI에서 토큰 엔드포인트로부터 토큰을 수신하면 사용자가 로그인됩니다.

자세한 내용은 AuthFilter.java의 doFilter() 메서드를 참조하세요.

참고 항목

doFilter()의 코드는 약간 다른 순서로 작성되지만 흐름은 설명된 것과 동일합니다.

해당 메서드가 트리거하는 인증 코드 흐름에 대한 자세한 내용은 Microsoft ID 플랫폼 및 OAuth 2.0 인증 코드 흐름을 참조하세요.

Node 샘플은 Express 프레임워크를 사용합니다. MSAL은 인증 경로 처리기에서 초기화됩니다.

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

Python 샘플은 Flask 프레임워크로 빌드되었지만 Django와 같은 다른 프레임워크도 사용할 수 있습니다. Flask 앱은 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)

그런 다음 코드는 ID 패키지를 사용하여 auth 개체를 구성합니다.

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

다음 단계

다음 문서에서는 로그인 및 로그아웃을 트리거하는 방법을 알아봅니다.

이 시나리오의 다음 문서인 로그인 및 로그아웃으로 이동합니다.

사용자가 로그인하는 웹앱: 코드 구성

웹앱을 지원하는 Microsoft 라이브러리

구성 파일

초기화 코드

다음 단계

추가 리소스