Azure Functions에서 토큰 발급 시작 이벤트에 대한 REST API 만들기

이 문서에서는 Azure Portal에서 Azure Functions를 사용하여 토큰 발급 시작 이벤트 로 REST API를 만드는 방법을 설명합니다. 토큰에 대한 추가 클레임을 반환할 수 있는 Azure Function 앱 및 HTTP 트리거 함수를 만듭니다.

필수 조건

• 사용자 지정 인증 확장 개요에서 다루는 개념에 대한 기본적인 이해입니다.
• Azure Functions를 만들 수 있는 기능이 있는 Azure 구독입니다. 기존 Azure 계정이 없는 경우 평가판에 등록하거나 계정을 만들 때 Visual Studio 구독 혜택을 사용합니다.
• Microsoft Entra ID 테넌트입니다. 이 방법 가이드에는 고객 또는 인력 테넌트를 사용할 수 있습니다.

이 문서에서는 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 라이브러리를 사용하여 토큰 발급 시작 이벤트에 대한 REST API를 만들고 인증을 위해 설정하는 방법을 설명합니다. Visual Studio 또는 Visual Studio Code에서 HTTP 트리거 함수를 만들고, 인증하도록 구성하고, Azure Functions를 통해 액세스할 수 있는 Azure Portal에 배포합니다.

필수 조건

• 사용자 지정 인증 확장 개요에서 다루는 개념에 대한 기본적인 이해입니다.
• Azure Functions를 만들 수 있는 기능이 있는 Azure 구독입니다. 기존 Azure 계정이 없는 경우 평가판에 등록하거나 계정을 만들 때 Visual Studio 구독 혜택을 사용합니다.
• Microsoft Entra ID 테넌트입니다. 이 방법 가이드에는 고객 또는 인력 테넌트를 사용할 수 있습니다.
• 다음 IDE 및 구성 중 하나입니다.
  • Visual Studio용 Azure 개발 워크로드가 구성된 Visual Studio .
  • Azure Functions 확장을 사용하도록 설정된 Visual Studio Code.

참고 항목

Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 라이브러리는 현재 미리 보기로 제공됩니다. 이 문서의 단계는 변경될 수 있습니다. 토큰 발급 시작 이벤트를 구현하는 일반 공급 구현의 경우 Azure Portal을 사용하여 구현할 수 있습니다.

Azure Function 앱 만들기

Azure Portal에서 HTTP 트리거 함수를 계속 만들기 전에 Azure Function 앱 및 관련 리소스를 만듭니다.

1. Azure Portal에 애플리케이션 관리istrator 및 Authentication 관리istrator로 로그인합니다.

2. Azure Portal 메뉴 또는 홈 페이지에서 리소스 만들기를 선택합니다.

3. 함수 앱을 검색하여 선택하고 만들기를 선택합니다.

4. 기본 페이지에서 다음 표에 지정된 대로 설정을 사용하여 함수 앱을 만듭니다.

   설정	제안 값	설명
   구독	구독	새 함수 앱을 만들 구독입니다.
   리소스 그룹	myResourceGroup	기존 리소스 그룹을 선택하거나 함수 앱을 만들 새 리소스 그룹의 이름을 선택합니다.
   함수 앱 이름	전역적으로 고유한 이름	새 함수 앱을 식별하는 이름입니다. 유효한 문자는 a-z(대/소문자 구분 안 함), 0-9 및 -입니다.
   코드 또는 컨테이너 이미지 배포	코드	코드 파일 또는 Docker 컨테이너를 게시하는 옵션입니다. 이 자습서에서는 코드를 선택합니다.
   런타임 스택	.NET	선호하는 프로그래밍 언어입니다. 이 자습서에서는 .NET을 선택합니다.
   버전	6(LTS) In-process	.NET 런타임의 버전입니다. In-process는 포털에서 함수를 만들고 수정할 수 있음을 의미하며, 이 가이드에 권장됩니다.
   지역	기본 지역	사용자 또는 함수가 액세스할 수 있는 기타 서비스에 가까운 지역을 선택합니다.
   운영 체제	Windows	운영 체제는 런타임 스택 선택에 따라 미리 선택됩니다.
   플랜 유형	사용량(서버리스)	함수 앱에 리소스가 할당되는 방법을 정의하는 호스팅 계획입니다.

5. 검토 + 만들기를 선택하여 앱 구성 선택 항목을 검토한 다음, 만들기를 선택합니다. 배포에는 몇 분 정도 걸립니다.

6. 배포되면 리소스로 이동을 선택하여 새 함수 앱을 봅니다.

HTTP 트리거 함수 만들기

Azure Function 앱을 만든 후 앱 내에서 HTTP 트리거 함수를 만듭니다. HTTP 트리거를 사용하면 HTTP 요청을 사용하여 함수를 호출할 수 있으며 Microsoft Entra 사용자 지정 인증 확장 프로그램에서 참조합니다.

1. 함수 앱의 개요 페이지 내에서 함수 창을 선택하고 Azure Portal에서 만들기 아래에서 함수 만들기를 선택합니다.
2. 함수 만들기 창에서 개발 환경 속성을 포털에서 개발로 둡니다. 템플릿에서 HTTP 트리거를 선택합니다.
3. 템플릿 세부 정보에서 새 함수 속성에 대해 CustomAuthenticationExtensionsAPI를 입력합니다.
4. 권한 부여 수준에서 함수를 선택합니다.
5. 만들기를 실행합니다.

함수 편집

이 코드는 들어오는 JSON 개체를 읽고 Microsoft Entra ID는 JSON 개체 를 API로 보냅니다. 이 예제에서는 상관 관계 ID 값을 읽습니다. 그런 다음, 코드는 원래CorrelationIdApiVersion, Azure Function DateOfBirth 의 a 및 CustomRoles Microsoft Entra ID로 반환되는 사용자 지정된 클레임의 컬렉션을 반환합니다.

1. 메뉴의 개발자 아래에서 코드 + 테스트를 선택합니다.

2. 전체 코드를 다음 코드 조각으로 바꾼 다음 저장을 선택합니다.

   #r "Newtonsoft.Json"
   using System.Net;
   using Microsoft.AspNetCore.Mvc;
   using Microsoft.Extensions.Primitives;
   using Newtonsoft.Json;
   public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
   {
       log.LogInformation("C# HTTP trigger function processed a request.");
       string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
       dynamic data = JsonConvert.DeserializeObject(requestBody);
   
       // Read the correlation ID from the Microsoft Entra request    
       string correlationId = data?.data.authenticationContext.correlationId;
   
       // Claims to return to Microsoft Entra
       ResponseContent r = new ResponseContent();
       r.data.actions[0].claims.CorrelationId = correlationId;
       r.data.actions[0].claims.ApiVersion = "1.0.0";
       r.data.actions[0].claims.DateOfBirth = "01/01/2000";
       r.data.actions[0].claims.CustomRoles.Add("Writer");
       r.data.actions[0].claims.CustomRoles.Add("Editor");
       return new OkObjectResult(r);
   }
   public class ResponseContent{
       [JsonProperty("data")]
       public Data data { get; set; }
       public ResponseContent()
       {
           data = new Data();
       }
   }
   public class Data{
       [JsonProperty("@odata.type")]
       public string odatatype { get; set; }
       public List<Action> actions { get; set; }
       public Data()
       {
           odatatype = "microsoft.graph.onTokenIssuanceStartResponseData";
           actions = new List<Action>();
           actions.Add(new Action());
       }
   }
   public class Action{
       [JsonProperty("@odata.type")]
       public string odatatype { get; set; }
       public Claims claims { get; set; }
       public Action()
       {
           odatatype = "microsoft.graph.tokenIssuanceStart.provideClaimsForToken";
           claims = new Claims();
       }
   }
   public class Claims{
       [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
       public string CorrelationId { get; set; }
       [JsonProperty(NullValueHandling = NullValueHandling.Ignore)]
       public string DateOfBirth { get; set; }
       public string ApiVersion { get; set; }
       public List<string> CustomRoles { get; set; }
       public Claims()
       {
           CustomRoles = new List<string>();
       }
   }
   

3. 위쪽 메뉴에서 함수 URL 가져오기를 선택하고 URL 값을 복사합니다. 이 함수 URL은 사용자 지정 인증 확장을 설정할 때 사용할 수 있습니다.

Azure Function 앱 만들기 및 빌드

이 단계에서는 IDE를 사용하여 HTTP 트리거 함수 API를 만들고, 필요한 NuGet 패키지를 설치하고, 샘플 코드에 복사합니다. 프로젝트를 빌드하고 함수를 실행하여 로컬 함수 URL을 추출합니다.

애플리케이션 만들기

Azure Function 앱을 만들려면 다음 단계를 수행합니다.

Visual Studio

1. Visual Studio를 열고 새 프로젝트 만들기를 선택합니다.
2. Azure Functions를 검색하여 선택한 다음, 다음을 선택합니다.
3. 프로젝트에 AuthEventsTrigger와 같은 이름을 지정합니다. 솔루션 이름을 프로젝트 이름과 일치하도록 하는 것이 좋습니다.
4. 프로젝트의 위치 를 선택합니다. 다음을 선택합니다.
5. 대상 프레임워크로 .NET 6.0(장기 지원)을 선택합니다.
6. Http 트리거를 함수 형식으로 선택하고 권한 부여 수준이 함수로 설정됩니다. 만들기를 실행합니다.
7. 솔루션 탐색기 Function1.cs 파일의 이름을 AuthEventsTrigger.cs 변경 제안에 동의합니다.

Visual Studio Code

1. Visual Studio Code를 엽니다.

2. 탐색기 창에서 새 폴더 아이콘을 선택하고 프로젝트에 대한 새 폴더(예: AuthEventsTrigger)를 만듭니다.

3. 화면 왼쪽에서 Azure 확장 아이콘을 선택합니다. 아직 로그인하지 않은 경우 Azure 계정에 로그인합니다.

4. 작업 영역 표시줄 아래에서 Azure Functions 아이콘 >새 프로젝트 만들기를 선택합니다.

   

5. 위쪽 막대에서 프로젝트를 만들 위치를 선택합니다.

6. C#을 언어로 선택하고 .NET 6.0 LTS를 .NET 런타임으로 선택합니다.

7. 템플릿으로 HTTP 트리거를 선택합니다.

8. 프로젝트의 이름(예: AuthEventsTrigger)을 제공합니다.

9. AccessRights가 Function으로 설정된 상태에서 Company.Function을 네임스페이스로 수락합니다.

NuGet 패키지 설치 및 프로젝트 빌드

프로젝트를 만든 후에는 필요한 NuGet 패키지를 설치하고 프로젝트를 빌드해야 합니다.

Visual Studio

1. Visual Studio의 위쪽 메뉴에서 프로젝트를 선택한 다음, NuGet 패키지를 관리합니다.
2. 찾아보기 탭을 선택한 다음, 오른쪽 창에서 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents를 검색하여 선택합니다. 설치를 선택합니다.
3. 표시되는 팝업의 변경 내용을 적용하고 적용합니다.

Visual Studio Code

1. Visual Studio Code에서 터미널을 열고 프로젝트 폴더로 이동합니다.

2. 콘솔에 다음 명령을 입력하여 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 패키지를 설치 합니다 .

   dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents
   

샘플 코드 추가

함수 API는 토큰에 대한 추가 클레임 원본입니다. 이 문서의 목적을 위해 샘플 앱에 대한 값을 하드 코딩합니다. 프로덕션 환경에서는 외부 데이터 저장소에서 사용자에 대한 정보를 가져올 수 있습니다.

AuthEventsTrigger.cs 파일에서 파일의 전체 내용을 다음 코드로 바꿉니다.

using System;
using Microsoft.Azure.WebJobs;
using Microsoft.Extensions.Logging;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;
using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;

namespace AuthEventsTrigger
{
    public static class AuthEventsTrigger
    {
        [FunctionName("onTokenIssuanceStart")]
        public static WebJobsAuthenticationEventResponse Run(
            [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log)
        {
            try
            {
                // Checks if the request is successful and did the token validation pass
                if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful)
                {
                    // Fetches information about the user from external data store
                    // Add new claims to the token's response
                    request.Response.Actions.Add(
                        new WebJobsProvideClaimsForToken(
                            new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
                            new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
                            new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
                            new WebJobsAuthenticationEventsTokenClaim(
                                "correlationId", 
                                request.Data.AuthenticationContext.CorrelationId.ToString())));
                }
                else
                {
                    // If the request fails, such as in token validation, output the failed request status, 
                    // such as in token validation or response validation.
                    log.LogInformation(request.StatusMessage);
                }
                return request.Completed();
            }
            catch (Exception ex) 
            { 
                return request.Failed(ex);
            }
        }
    }
}

로컬로 프로젝트 빌드 및 실행

프로젝트가 만들어졌으며 샘플 코드가 추가되었습니다. IDE를 사용하여 로컬 함수 URL을 추출하기 위해 프로젝트를 로컬로 빌드하고 실행해야 합니다.

Visual Studio

1. 상단 메뉴에서 빌드로 이동하고 솔루션 빌드를 선택합니다.
2. F5 키를 누르거나 상단 메뉴에서 AuthEventsTrigger를 선택하여 함수를 실행합니다.
3. 함수를 실행할 때 팝업되는 터미널에서 함수 URL 을 복사합니다. 사용자 지정 인증 확장을 설정할 때 사용할 수 있습니다.

Visual Studio Code

1. 위쪽 메뉴에서 디버깅 시작 실행을>선택하거나 F5 키를 눌러 함수를 실행합니다.
2. 터미널에서 표시되는 함수 URL을 복사합니다. 사용자 지정 인증 확장을 설정할 때 사용할 수 있습니다.

함수를 로컬로 실행(권장)

함수를 Azure에 배포하기 전에 로컬에서 테스트하는 것이 좋습니다. Microsoft Entra ID가 REST API에 보내는 요청을 모방하는 더미 JSON 본문을 사용할 수 있습니다. 원하는 API 테스트 도구를 사용하여 함수를 직접 호출합니다.

1. IDE에서 local.settings.json 열고 코드를 다음 JSON으로 바꿉다. 로컬 테스트를 위해 설정할 "AuthenticationEvents__BypassTokenValidation"true 수 있습니다.

   {
     "IsEncrypted": false,
     "Values": {
       "AzureWebJobsStorage": "",
       "AzureWebJobsSecretStorageType": "files",
       "FUNCTIONS_WORKER_RUNTIME": "dotnet",
       "AuthenticationEvents__BypassTokenValidation" : true
     }
   }
   

2. 선호하는 API 테스트 도구를 사용하여 새 HTTP 요청을 만들고 HTTP 메서드를 POST.로 설정합니다.

3. Microsoft Entra ID가 REST API에 보내는 요청을 모방하는 다음 JSON 본문을 사용합니다.

   {
       "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
       "source": "/tenants/aaaabbbb-0000-cccc-1111-dddd2222eeee/applications/00001111-aaaa-2222-bbbb-3333cccc4444",
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
           "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
           "authenticationEventListenerId": "11112222-bbbb-3333-cccc-4444dddd5555",
           "customAuthenticationExtensionId": "22223333-cccc-4444-dddd-5555eeee6666",
           "authenticationContext": {
               "correlationId": "aaaa0000-bb11-2222-33cc-444444dddddd",
               "client": {
                   "ip": "127.0.0.1",
                   "locale": "en-us",
                   "market": "en-us"
               },
               "protocol": "OAUTH2.0",
               "clientServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "resourceServicePrincipal": {
                   "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
                   "appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
                   "appDisplayName": "My Test application",
                   "displayName": "My Test application"
               },
               "user": {
                   "companyName": "Casey Jensen",
                   "createdDateTime": "2023-08-16T00:00:00Z",
                   "displayName": "Casey Jensen",
                   "givenName": "Casey",
                   "id": "00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
                   "mail": "casey@contoso.com",
                   "onPremisesSamAccountName": "Casey Jensen",
                   "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                   "onPremisesUserPrincipalName": "Casey Jensen",
                   "preferredLanguage": "en-us",
                   "surname": "Jensen",
                   "userPrincipalName": "casey@contoso.com",
                   "userType": "Member"
               }
           }
       }
   }
   
   

4. 보내기를 선택하면 다음과 유사한 JSON 응답을 받게 됩니다.

   {
       "data": {
           "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
           "actions": [
               {
                   "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                   "claims": {
                       "customClaim1": "customClaimValue1",
                       "customClaim2": [
                           "customClaimString1",
                           "customClaimString2" 
                       ]
                   }
               }
   
           ]
       }
   }
   

함수 배포 및 Azure에 게시

함수는 IDE를 사용하여 Azure에 배포해야 합니다. 함수를 게시할 수 있도록 Azure 계정에 올바르게 로그인했는지 확인합니다.

Visual Studio

1. 솔루션 탐색기 프로젝트를 마우스 오른쪽 단추로 클릭하고 게시를 선택합니다.

2. 대상에서 Azure를 선택한 다음, 다음을 선택합니다.

3. 특정 대상에 대해 Azure Function App(Windows)을 선택하고, Azure 함수 앱(Windows)을 선택한 다음, 다음을 선택합니다.

4. 함수 인스턴스에서 구독 이름 드롭다운을 사용하여 새 함수 앱을 만들 구독을 선택합니다.

5. 새 함수 앱을 게시할 위치를 선택하고 새로 만들기를 선택합니다.

6. 함수 앱(Windows) 페이지에서 다음 표에 지정된 대로 함수 앱 설정을 사용한 다음 만들기를 선택합니다.

   설정	제안 값	Description
   이름	전역적으로 고유한 이름	새 함수 앱을 식별하는 이름입니다. 유효한 문자는 a-z(대/소문자 구분 안 함), 0-9 및 -입니다.
   구독	구독	새 함수 앱이 만들어지는 구독입니다.
   리소스 그룹	myResourceGroup	기존 리소스 그룹을 선택하거나 함수 앱을 만들 새 리소스 그룹의 이름을 지정합니다.
   플랜 유형	사용량(서버리스)	함수 앱에 리소스가 할당되는 방법을 정의하는 호스팅 계획입니다.
   위치	기본 지역	사용자 또는 함수가 액세스할 수 있는 기타 서비스에 가까운 지역을 선택합니다.
   Azure Storage	스토리지 계정	Azure 스토리지 계정은 함수 런타임에서 필요합니다. 새로 만들기를 선택하여 범용 스토리지 계정을 구성합니다.
   Application Insights	기본값	Azure Monitor의 기능입니다. 자동으로 선택되고 사용하려는 항목을 선택하거나 새 항목을 구성합니다.

7. 함수 앱이 배포될 때까지 잠시 기다립니다. 창이 닫히면 마침을 선택합니다.

8. 새 게시 창이 열립니다. 맨 위에서 게시를 선택합니다. 함수 앱이 배포되고 Azure Portal에 표시될 때까지 몇 분 정도 기다립니다.

Visual Studio Code

1. Azure 확장 아이콘을 선택합니다. 리소스에서 아이콘을 + 선택하여 리소스를 만듭니다.
2. Azure에서 함수 앱 만들기를 선택합니다. 함수 앱을 설정하려면 다음 설정을 사용합니다.
3. 함수 앱에 AuthEventsTriggerNuGet과 같은 이름을 지정하고 Enter 키를 누릅니다.
4. .NET 6(LTS) In-Process 런타임 스택을 선택합니다.
5. 함수 앱의 위치(예: 미국 동부)를 선택합니다.
6. 함수 앱이 배포되고 Azure Portal에 표시될 때까지 몇 분 정도 기다립니다.

Azure Function에 대한 인증 구성

Azure Function에 대한 인증을 설정하는 세 가지 방법이 있습니다.

• 환경 변수 를 사용하여 Azure Portal에서 인증 설정(권장)
• 를 사용하여 코드에서 인증 설정 WebJobsAuthenticationEventsTriggerAttribute
• Azure 앱 서비스 인증 및 권한 부여

기본적으로 환경 변수를 사용하여 Azure Portal에서 인증을 위해 코드가 설정되었습니다. 아래 탭을 사용하여 환경 변수를 구현하는 기본 방법을 선택하거나 기본 제공 Azure 앱 서비스 인증 및 권한 부여를 참조하세요. 환경 변수를 설정하려면 다음 값을 사용합니다.

속성	값
AuthenticationEvents__AudienceAppId	토큰 발급 이벤트에 대한 사용자 지정 클레임 공급자 구성에서 설정된 사용자 지정 인증 확장 앱 ID
AuthenticationEvents__AuthorityUrl	• 직원 테넌트 https://login.microsoftonline.com/<tenantID> • 외부 테넌트 https://<mydomain>.ciamlogin.com
AuthenticationEvents__AuthorizedPartyAppId	99045fe1-7639-4a75-9d4a-577b6ca3810f 또는 다른 권한 있는 당사자

Azure Portal에서 인증 설정

환경 변수를 사용하여 Azure Portal에서 인증 설정

1. Azure Portal에 애플리케이션 관리istrator 또는 Authentication 관리istrator로 로그인합니다.
2. 만든 함수 앱으로 이동하고 설정 아래에서 구성을 선택합니다.
3. 애플리케이션 설정에서 새 애플리케이션 설정을 선택하고 테이블 및 관련 값에서 환경 변수를 추가합니다.
4. 저장을 선택하여 애플리케이션 설정을 저장합니다.

코드에서 인증 설정

를 사용하여 코드에서 인증 설정 WebJobsAuthenticationEventsTriggerAttribute

1. IDE에서 AuthEventsTrigger.cs 파일을 엽니다.
2. WebJobsAuthenticationEventsTriggerAttribute 아래 코드 조각과 AuthorityUrlAudienceAppId 같이 포함 및 AuthorizedPartyAppId 속성을 수정합니다.

    [FunctionName("onTokenIssuanceStart")]
    public static WebJobsAuthenticationEventResponse Run(
        [WebJobsAuthenticationEventsTriggerAttribute(
            AudienceAppId = "Enter custom authentication extension app ID here",
            AuthorityUrl = "Enter authority URI here", 
            AuthorizedPartyAppId = "Enter the Authorized Party App Id here")]WebJobsTokenIssuanceStartRequest request, ILogger log)

다음 단계

사용자 지정 클레임 공급자 토큰 발급 이벤트 구성