다음을 통해 공유

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

  • 아티클

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

필수 조건

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

필수 조건

참고 항목

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

Azure 함수 앱 만들기

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

  1. 최소한 애플리케이션 관리자 및 인증 관리자로 Azure Portal에 로그인합니다.

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

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

  4. 함수 앱 만들기 페이지에서 소비를 선택한 다음, 선택합니다.

  5. 함수 앱 만들기(소비) 페이지의 기본 사항 탭에서 다음 표에 지정된 대로 설정을 사용하여 함수 앱을 만듭니다.

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

    개발 환경 및 템플릿을 선택하는 방법을 보여 주는 스크린샷

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

  7. 배포한 후 리소스로 이동을 선택하여 새 함수 앱을 확인합니다.

HTTP 트리거 함수 만들기

Azure 함수 앱이 만들어진 후 앱 내에서 HTTP 트리거 함수를 만듭니다. HTTP 트리거를 사용하면 HTTP 요청으로 함수를 호출할 수 있으며 Microsoft Entra 사용자 지정 인증 확장에서 참조됩니다.

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

함수 편집

코드는 수신 JSON 개체를 읽고 Microsoft Entra ID는 JSON 개체를 API로 보냅니다. 이 예제에서는 상관 관계 ID 값을 읽습니다. 그런 다음 코드는 원본 CorrelationId, Azure 함수의 ApiVersion, Microsoft Entra ID로 반환되는 DateOfBirth 및 CustomRoles를 포함하여 사용자 지정된 클레임 컬렉션을 반환합니다.

  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 함수 앱 만들기 및 빌드

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

애플리케이션 만들기

Azure 함수 앱을 만들려면 다음 단계를 따릅니다.

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

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

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

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

샘플 코드 추가

함수 API는 토큰에 대한 추가 클레임 원본입니다. 이 문서의 목적에 따라 샘플 앱의 값을 하드 코딩합니다. 프로덕션에서는 외부 데이터 저장소에서 사용자에 대한 정보를 가져올 수 있습니다. 기존 속성에 대해서는 WebJobsAuthenticationEventsContext 클래스를 참조하세요.

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을 추출해야 합니다.

  1. 상단 메뉴에서 빌드로 이동한 후 솔루션 빌드를 선택합니다.
  2. 함수를 실행하려면 F5 키를 누르거나 상단 메뉴에서 AuthEventsTrigger를 선택합니다.
  3. 함수 실행 시 팝업되는 터미널에서 함수 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 계정에 올바르게 로그인했는지 확인합니다.

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

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

  3. 특정 대상으로 Azure 함수 앱(Windows)을 선택하고, Azure 함수 앱(Windows)을 선택한 후 다음을 선택합니다.

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

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

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

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

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

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

Azure 함수에 대한 인증 구성

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

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

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

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

  1. 최소한 애플리케이션 관리자 또는 인증 관리자로 Azure Portal에 로그인합니다.
  2. 만든 함수 앱으로 이동하고 설정에서 구성을 선택합니다.
  3. 애플리케이션 설정에서 새 애플리케이션 설정을 선택하고 표의 환경 변수와 관련 값을 추가합니다.
  4. 저장을 선택하여 애플리케이션 설정을 저장합니다.

다음 단계

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