Share via

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

  • 아티클

이 문서에서는 토큰 발급 시작 이벤트에 대한 사용자 지정 클레임 공급자를 구성하는 방법을 설명합니다. 기존 Azure Functions REST API를 사용하여 사용자 지정 인증 확장을 등록하고 REST API에서 구문 분석할 것으로 예상되는 특성을 추가합니다. 사용자 지정 인증 확장을 테스트하려면 샘플 OpenID 커넥트 애플리케이션을 등록하여 토큰을 가져오고 클레임을 확인합니다.

필수 조건

  • Azure Functions를 만들 수 있는 기능이 있는 Azure 구독입니다. 기존 Azure 계정이 없는 경우 평가판에 등록하거나 계정을 만들 때 Visual Studio 구독 혜택을 사용합니다.
  • 토큰 발급 시작 이벤트에 대해 구성된 HTTP 트리거 함수가 있는 Azure Function 앱입니다. 토큰이 없는 경우 토큰 발급 시작 이벤트 HTTP 트리거 함수를 만드는 단계를 수행합니다.
  • 사용자 지정 인증 확장 개요에서 다루는 개념에 대한 기본적인 이해입니다.
  • Microsoft Entra ID 테넌트입니다. 이 방법 가이드에는 고객 또는 인력 테넌트를 사용할 수 있습니다.
    • 외부 테넌트에 대해 등록 및 로그인 사용자 흐름을 사용합니다.

1단계: 사용자 지정 인증 확장 등록

이제 Microsoft Entra ID에서 Azure 함수를 호출하는 데 사용할 사용자 지정 인증 확장을 구성합니다. 사용자 지정 인증 확장에는 REST API 엔드포인트에 대한 정보, REST API에서 구문 분석하는 클레임, REST API에 인증하는 방법이 포함됩니다. 다음 단계에 따라 Azure Function 앱에 사용자 지정 인증 확장을 등록합니다.

참고 항목

최대 100 개의 사용자 지정 확장 정책을 가질 수 있습니다.

사용자 지정 인증 확장 등록

  1. Azure Portal에 애플리케이션 관리istrator 및 Authentication 관리istrator로 로그인합니다.
  2. Microsoft Entra ID를 검색하여 선택하고 엔터프라이즈 애플리케이션을 선택합니다.
  3. 사용자 지정 인증 확장을 선택한 다음 사용자 지정 확장 만들기를 선택합니다.
  4. 기본 사항에서 TokenIssuanceStart 이벤트 유형을 선택하고 다음을 선택합니다.
  5. 엔드포인트 구성에서 다음 속성을 입력합니다.
    • 이름 - 사용자 지정 인증 확장의 이름입니다. 예를 들어 토큰 발급 이벤트입니다.
    • 대상 URL - Azure 함수 URL의 {Function_Url}입니다. Azure Function 앱의 개요 페이지로 이동한 다음, 만든 함수를 선택합니다. 함수 개요 페이지에서 함수 URL 가져오기를 선택하고 복사 아이콘을 사용하여 URL을 복사합니다.
    • 설명 - 사용자 지정 인증 확장에 대한 설명입니다.
  6. 다음을 선택합니다.
  7. API 인증에서 새 앱 등록 만들기 옵션을 선택하여 함수 앱을 나타내는 앱 등록을 만듭니다.
  8. 앱에 이름(예: Azure Functions 인증 이벤트 API)을 지정합니다.
  9. 다음을 선택합니다.
  10. 클레임에서 사용자 지정 인증 확장이 REST API에서 구문 분석될 것으로 예상되는 특성을 입력하고 토큰에 병합됩니다. 다음 클레임을 추가합니다.
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
  11. 다음을 선택한 다음, 사용자 지정 인증 확장 및 연결된 애플리케이션 등록을 등록하는 만들기를 선택합니다.
  12. Azure Function 앱에서 환경 변수를 설정하는 데 필요한 API 인증 아래의 앱 ID를 확인합니다.

사용자 지정 인증 확장이 만들어지면 API에 권한을 부여해야 합니다. 사용자 지정 인증 확장은 client_credentials 및 Receive custom authentication extension HTTP requests 권한을 사용하여 Azure 함수 앱을 인증합니다.

  1. 새 사용자 지정 인증 확장의 개요 페이지를 엽니다. ID 공급자를 추가할 때 필요하므로 API 인증에서 앱 ID를 기록해 둡니다.

  2. API 인증에서 권한 부여를 선택합니다.

  3. 새 창이 열리고 로그인되면 사용자 지정 인증 확장 HTTP 요청을 받을 수 있는 권한을 요청합니다. 이렇게 하면 사용자 지정 인증 확장이 API에 인증할 수 있습니다. 수락을 선택합니다.

    관리자 동의를 부여하는 방법을 보여 주는 스크린샷

2단계: 보강된 토큰을 받도록 OpenID 커넥트 앱 구성

토큰을 가져와서 사용자 지정 인증 확장을 테스트하려면 https://jwt.ms 앱을 사용하면 됩니다. 토큰의 디코딩된 콘텐츠를 표시하는 Microsoft 자체 웹 애플리케이션입니다(토큰의 콘텐츠는 브라우저를 떠나지 않음).

2.1 테스트 웹 애플리케이션 등록

다음 단계에 따라 jwt.ms 웹 애플리케이션을 등록합니다.

  1. Azure Portal의 홈페이지에서 Microsoft Entra ID를 선택합니다.

  2. 앱 등록>새 등록을 선택합니다.

  3. 애플리케이션의 이름을 입력합니다. 예를 들어 내 테스트 애플리케이션입니다.

  4. 지원되는 계정 유형에서 이 조직 디렉터리의 계정만을 선택합니다.

  5. 리디렉션 URI의 플랫폼 선택 드롭다운에서 웹을 선택한 다음, URL 텍스트 상자에 https://jwt.ms를 입력합니다.

  6. 등록을 선택하여 앱 등록을 완료합니다.

    지원되는 계정 유형을 선택하고 URI를 리디렉션하는 방법을 보여 주는 스크린샷

  7. 앱 등록 개요 페이지에서 애플리케이션(클라이언트) ID를 복사합니다. 이후 단계에서 앱 ID를 {App_to_enrich_ID}라고 합니다. Microsoft Graph에서는 appId 속성으로 참조됩니다.

    애플리케이션 ID를 복사하는 방법을 보여 주는 스크린샷

2.2 암시적 흐름 사용

jwt.ms 테스트 애플리케이션은 암시적 흐름을 사용합니다. 내 테스트 애플리케이션 등록 시 암시적 흐름을 사용하도록 설정합니다.

  1. 관리에서 인증을 선택합니다.
  2. 암시적 허용 및 하이브리드 흐름 아래에서 ID 토큰(암시적 및 하이브리드 흐름에 사용됨) 확인란을 선택합니다.
  3. 저장을 선택합니다.

2.3 클레임 매핑 정책에 대해 앱 사용

클레임 매핑 정책은 사용자 지정 인증 확장에서 반환된 특성이 토큰에 매핑되는 특성을 선택하는 데 사용됩니다. 토큰을 보강할 수 있도록 하려면 애플리케이션 등록을 명시적으로 사용하도록 설정하여 매핑된 클레임을 수락해야 합니다.

  1. 내 테스트 애플리케이션 등록의 관리에서 매니페스트를 선택합니다.
  2. 매니페스트에서 acceptMappedClaims 특성을 찾아 값을 true로 설정합니다.
  3. accessTokenAcceptedVersion를 2로 설정합니다.
  4. 저장을 선택하여 변경 내용을 저장합니다.

다음 JSON 코드 조각은 이러한 속성을 구성하는 방법을 보여 줍니다.

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

Warning

악의적인 행위자가 앱에 대한 클레임 매핑 정책을 만들 수 있는 다중 테넌트 앱의 경우 acceptMappedClaims 속성을 true로 설정하지 마세요. 대신 사용자 지정 서명 키를 구성합니다.

다음 단계로 계속 진행하여 앱에 사용자 지정 클레임 공급자를 할당합니다.

3단계: 앱에 사용자 지정 클레임 공급자 할당

토큰이 사용자 지정 인증 확장에서 들어오는 클레임과 함께 발급되려면 애플리케이션에 사용자 지정 클레임 공급자를 할당해야 합니다. 이는 토큰 대상 그룹을 기반으로 하므로 ID 토큰으로 클레임을 받으려면 클라이언트 애플리케이션에 공급자를 할당해야 하고, 액세스 토큰으로 클레임을 받으려면 리소스 애플리케이션에 공급자를 할당해야 합니다. 사용자 지정 클레임 공급자는 토큰 발급 시작 이벤트 수신기로 구성된 사용자 지정 인증 확장을 사용합니다. 사용자 지정 클레임 공급자에서 클레임의 전체 또는 하위 집합이 토큰에 매핑되는지 여부를 선택할 수 있습니다.

참고 항목

애플리케이션과 사용자 지정 확장 간에 250개의 고유 할당만 만들 수 있습니다. 여러 앱에 동일한 사용자 지정 확장 호출을 적용하려면 authenticationEventListeners Microsoft Graph API를 사용하여 여러 애플리케이션에 대한 수신기를 만드는 것이 좋습니다. Azure Portal에서는 지원되지 않습니다.

다음 단계에 따라 내 테스트 애플리케이션을 사용자 지정 인증 확장에 연결합니다.

사용자 지정 인증 확장을 사용자 지정 클레임 공급자 원본으로 할당하려면

  1. Azure Portal의 홈페이지에서 Microsoft Entra ID를 선택합니다.

  2. 엔터프라이즈 애플리케이션을 선택한다음 관리에서 모든 애플리케이션을 선택합니다. 목록에서 내 테스트 애플리케이션을 찾아 선택합니다.

  3. 내 테스트 애플리케이션의 개요 페이지에서 관리로 이동하고 Single Sign-On을 선택합니다.

  4. 특성 및 클레임 아래에서 편집을 선택합니다.

    앱 클레임을 구성하는 방법을 보여 주는 스크린샷

  5. 고급 설정 메뉴를 확장합니다.

  6. 사용자 지정 클레임 공급자 옆에 있는 구성을 선택합니다.

  7. 사용자 지정 클레임 공급자 드롭다운 상자를 확장하고 이전에 만든 토큰 발급 이벤트를 선택합니다.

  8. 저장을 선택합니다.

다음으로, 토큰에 클레임으로 발급되어야 하는 사용자 지정 클레임 공급자의 특성을 할당합니다.

  1. 새 클레임 추가를 선택하여 새 클레임을 추가합니다. 발급하려는 클레임에 대해 이름(예: dateOfBirth)을 지정합니다.

  2. 원본에서 특성을 선택하고 원본 특성 드롭다운 상자에서 customClaimsProvider.dateOfBirth를 선택합니다.

    앱에 클레임 매핑을 추가하는 방법을 보여 주는 스크린샷

  3. 저장을 선택합니다.

  4. 이 프로세스를 반복하여 customClaimsProvider.customRoles, customClaimsProvider.apiVersion 및 customClaimsProvider.correlationId 특성 및 해당 이름을 추가합니다. 클레임의 이름과 특성의 이름과 일치하도록 하는 것이 좋습니다.

4단계: Azure 함수 보호

Microsoft Entra 사용자 지정 인증 확장은 서버 간 흐름을 사용하여 HTTP Authorization 헤더에서 Azure Function으로 보내는 액세스 토큰을 가져옵니다. 특히 프로덕션 환경에서 Azure에 함수를 게시할 때 권한 부여 헤더에서 보낸 토큰의 유효성을 검사해야 합니다.

Azure Function을 보호하려면 다음 단계에 따라 들어오는 토큰의 유효성을 검사하기 위해 Azure Functions 인증 이벤트 API 애플리케이션 등록과 Microsoft Entra 인증을 통합합니다. 테넌트 유형에 따라 다음 탭 중 하나를 선택합니다.

참고 항목

Azure 함수 앱이 사용자 지정 인증 확장이 등록된 테넌트가 아닌 다른 Azure 테넌트에서 호스트되는 경우 ID 열기 커넥트 탭을 선택합니다.

4.1 Microsoft Entra ID 공급자 사용

다음 단계를 사용하여 Microsoft Entra를 Azure Function 앱에 ID 공급자로 추가합니다.

  1. Azure Portal에서 이전에 게시한 함수 앱을 찾아 선택합니다.

  2. 설정에서 인증을 선택합니다.

  3. ID 공급자 추가를 선택합니다.

  4. Microsoft를 ID 공급자로 선택합니다.

  5. 테넌트 유형으로 Workforce를 선택합니다.

  6. 앱 등록에서 앱 등록 유형에 대해 이 디렉터리에서 기존 앱 등록을 선택하고, 사용자 지정 클레임 공급자를 등록할 때 이전에 만든 Azure Functions 인증 이벤트 API 앱 등록을 선택합니다.

  7. 다음 발급자 URL을 https://login.microsoftonline.com/{tenantId}/v2.0입력합니다. 여기서 {tenantId} 는 직원 테넌트 테넌트 ID입니다.

  8. 인증되지 않은 요청에서 ID 공급자로 HTTP 401 권한 없음을 선택합니다.

  9. 토큰 저장소 옵션을 선택 취소합니다.

  10. 추가를 선택하여 Azure Function에 인증을 추가합니다.

    직원 테넌트에 있는 동안 함수 앱에 인증을 추가하는 방법을 보여 주는 스크린샷

4.2 OpenID 커넥트 ID 공급자 사용

Microsoft ID 공급자를 구성한 경우 이 단계를 건너뜁니다. 그러지 않으면 Azure Function이 사용자 지정 인증 확장이 등록된 테넌트와 다른 테넌트에서 호스트되는 경우 다음 단계에 따라 함수를 보호합니다.

클라이언트 암호 만들기

  1. Azure Portal의 홈페이지에서 Microsoft Entra ID>앱 등록 선택합니다.
  2. 이전에 만든 Azure Functions 인증 이벤트 API 앱 등록을 선택합니다.
  3. 인증서 및 비밀>클라이언트 암호>새 클라이언트 암호를 선택합니다.
  4. 비밀에 대한 만료를 선택하거나 사용자 지정 수명을 지정하고 설명을 추가하고 추가를 선택합니다.
  5. 클라이언트 애플리케이션 코드에서 사용할 비밀 값을 기록합니다. 이 비밀 값은 이 페이지에서 나가면 다시 표시되지 않습니다.

Azure Function 앱에 OpenID 커넥트 ID 공급자를 추가합니다.

  1. 이전에 게시한 함수 앱을 찾아 선택합니다.

  2. 설정에서 인증을 선택합니다.

  3. ID 공급자 추가를 선택합니다.

  4. ID 공급자로 OpenID Connect를 선택합니다.

  5. Contoso Microsoft Entra ID와 같은 이름을 제공합니다.

  6. 메타데이터 항목에서 문서 URL에 다음 URL을 입력합니다. {tenantId}를 Microsoft Entra 테넌트 ID로 바꿉니다.

    https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration

  7. 앱 등록에서 이전에 만든 Azure Functions 인증 이벤트 API 앱 등록의 애플리케이션 ID(클라이언트 ID)를 입력합니다.

  8. Azure Function으로 돌아가서 앱 등록에서 클라이언트 비밀을 입력합니다.

  9. 토큰 저장소 옵션을 선택 취소합니다.

  10. 추가를 선택하여 OpenID Connect ID 공급자를 추가합니다.

5단계: 애플리케이션 테스트

사용자 지정 클레임 공급자를 테스트하려면 다음 단계를 수행합니다.

  1. 새 프라이빗 브라우저를 열고 다음 URL을 통해 로그인합니다.

    https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

  2. {tenantId}를 테넌트 ID, 테넌트 이름 또는 확인된 도메인 이름 중 하나로 바꿉니다. 예들 들어 contoso.onmicrosoft.com입니다.

  3. 내 테스트 애플리케이션 클라이언트 ID로 바꿉니다{App_to_enrich_ID}.

  4. 로그인하면 https://jwt.ms에 디코딩된 토큰이 표시됩니다. Azure Function의 클레임이 디코딩된 토큰(예: dateOfBirth)에 표시되는지 확인합니다.

참고 항목