클라이언트 인증에 대한 Microsoft Entra ID 설정

  • 아티클

Warning

현재 Microsoft Entra 클라이언트 인증과 관리 ID 토큰 서비스는 Linux에서 상호 호환되지 않습니다.

Azure에서 실행되는 클러스터의 경우 관리 엔드포인트에 대한 액세스를 보호하려면 Microsoft Entra ID를 사용하는 것이 좋습니다. 이 문서에서는 Service Fabric 클러스터에 대해 클라이언트를 인증하기 위해 Microsoft Entra ID를 설정하는 방법을 설명합니다.

Linux에서는 클러스터를 만들기 전에 다음 단계를 완료해야 합니다. Windows에는 기존 클러스터에 대해 Microsoft Entra 인증을 구성하는 옵션도 있습니다.

이 문서에서 "애플리케이션"이라는 용어는 Service Fabric 애플리케이션이 아닌 Microsoft Entra 애플리케이션을 의미합니다. 필요한 경우 구분이 이루어집니다. Microsoft Entra ID를 사용하면 조직(테넌트라고도 함)이 애플리케이션에 대한 사용자 액세스를 관리할 수 있습니다.

Service Fabric 클러스터는 웹 기반 Service Fabric Explorer 및 Visual Studio를 포함하여 관리 기능에 대한 몇 가지 진입점을 제공합니다. 결과적으로 클러스터에 대한 액세스를 제어하기 위해 두 개의 Microsoft Entra 애플리케이션(웹 애플리케이션 하나와 네이티브 애플리케이션 하나)을 만들게 됩니다. 애플리케이션을 만든 후 읽기 전용 및 관리자 역할에 사용자를 할당합니다.

참고 항목

현재 Service Fabric은 스토리지에 대한 Microsoft Entra 인증을 지원하지 않습니다.

참고 항목

Linux Microsoft Entra ID 지원 클러스터의 애플리케이션과 노드를 Azure Portal에서 볼 수 없다는 것은 알려진 문제입니다.

참고 항목

이제 Microsoft Entra ID에서는 애플리케이션(앱 등록) 게시자 도메인을 확인하거나 기본 구성표를 사용해야 합니다. 자세한 내용은 애플리케이션의 게시자 도메인 구성 및 단일 테넌트 애플리케이션의 AppId URI는 기본 체계 또는 확인된 도메인을 사용해야 함을 참조하세요.

참고 항목

Service Fabric 11.0부터 Service Fabric Explorer에는 웹 리디렉션 URI 대신 단일 페이지 애플리케이션 리디렉션 URI가 필요합니다.

필수 조건

이 문서에서는 이미 테넌트를 만들었다고 가정합니다. 아직 읽어보지 않으셨다면 먼저 Microsoft Entra 테넌트를 구하는 방법을 참조하세요. Service Fabric 클러스터로 Microsoft Entra ID를 구성하는 것과 관련된 일부 단계를 간소화하기 위해 Windows PowerShell 스크립트 집합을 만들었습니다. 일부 작업에는 Microsoft Entra ID에 대한 관리 수준 액세스가 필요합니다. 스크립트에 401 또는 403 'Authorization_RequestDenied' 오류가 발생하면 관리자가 스크립트를 실행해야 합니다.

  1. Azure 관리 권한을 사용하여 인증합니다.
  2. 컴퓨터에 리포지토리를 복제합니다.
  3. 설치된 스크립트에 대한 모든 필수 조건이 있는지 확인합니다.

Microsoft Entra 애플리케이션 만들기 및 사용자에게 역할 할당

스크립트를 사용하여 두 개의 Microsoft Entra 애플리케이션을 만들어 클러스터에 대한 액세스를 제어합니다. 하나는 웹 애플리케이션이고 다른 하나는 네이티브 애플리케이션입니다. 클러스터를 나타내는 애플리케이션을 만든 후 Service Fabric에서 지원하는 역할(읽기 전용 및 관리자)에 대한 사용자를 만듭니다.

SetupApplications.ps1

SetupApplications.ps1을 실행하고 테넌트 ID, 클러스터 이름, 웹 애플리케이션 URI 및 웹 애플리케이션 회신 URL을 매개 변수로 제공합니다. -remove를 사용하여 앱 등록을 제거합니다. -logFile <log file path>를 사용하면 대화 기록 로그가 생성됩니다. 자세한 내용은 스크립트 도움말(help .\setupApplications.ps1 -full)을 참조하세요. 이 스크립트는 Service Fabric 클러스터를 나타내는 웹 및 네이티브 애플리케이션을 만듭니다. 두 개의 새로운 앱 등록 항목의 형식은 다음과 같습니다.

  • ClusterName_Cluster
  • 클러스터 이름_클라이언트

참고 항목

국가별 클라우드(예: Azure Government, 21Vianet에서 운영하는 Microsoft Azure)의 경우 -Location 매개 변수도 지정해야 합니다.

매개 변수

  • tenantId:Get-AzureSubscription PowerShell 명령을 실행하여 TenantId를 찾을 수 있습니다. 이 명령을 실행하면 모든 구독에 대한 TenantId가 표시됩니다.

  • clusterName:ClusterName은 스크립트에 의해 만들어진 Microsoft Entra 애플리케이션의 접두사로 사용됩니다. 실제 클러스터 이름과 정확히 일치할 필요는 없습니다. 이는 Microsoft Entra 아티팩트를 사용 중인 Service Fabric 클러스터에 더 쉽게 매핑할 수 있도록 하기 위한 것입니다.

  • SpaApplicationReplyUrl:SpaApplicationReplyUrl은 사용자가 로그인을 마친 후 Microsoft Entra ID가 사용자에게 반환하는 기본 엔드포인트입니다. 이 엔드포인트를 클러스터의 Service Fabric Explorer 엔드포인트로 설정합니다. 기존 클러스터를 나타내기 위해 Microsoft Entra 애플리케이션을 만드는 경우 이 URL이 기존 클러스터의 엔드포인트와 일치하는지 확인합니다. 새 클러스터에 대한 애플리케이션을 만드는 경우 클러스터에 대한 엔드포인트를 계획하고 기존 클러스터의 엔드포인트를 사용하지 않도록 합니다. 기본적으로 Service Fabric Explorer 엔드포인트는 다음과 같습니다. https://<cluster_domain>:19080/Explorer/index.html

  • webApplicationUri:WebApplicationUri는 '확인된 도메인'의 URI이거나 api://{{tenant Id}}/{{cluster name}}의 API 체계 형식을 사용하는 URI입니다. 자세한 내용은 단일 테넌트 애플리케이션의 AppId Uri에서는 기본 구성표 또는 확인된 도메인을 사용해야 함을 참조하세요.

    예제 API 체계: API://0e3d2646-78b3-4711-b8be-74a381d9890c/mysftestcluster

SetupApplications.ps1 예제

# if using cloud shell
# cd clouddrive 
# git clone https://github.com/Azure-Samples/service-fabric-aad-helpers
# cd service-fabric-aad-helpers
# code .

$tenantId = '0e3d2646-78b3-4711-b8be-74a381d9890c'
$clusterName = 'mysftestcluster'
$spaApplicationReplyUrl = 'https://mysftestcluster.eastus.cloudapp.azure.com:19080/Explorer/index.html' # <--- client browser redirect url
#$webApplicationUri = 'https://mysftestcluster.contoso.com' # <--- must be verified domain due to AAD changes
$webApplicationUri = "API://$tenantId/$clusterName" # <--- doesn't have to be verified domain

$configObj = .\SetupApplications.ps1 -TenantId $tenantId `
  -ClusterName $clusterName `
  -SpaApplicationReplyUrl $spaApplicationReplyUrl `
  -AddResourceAccess `
  -WebApplicationUri $webApplicationUri `
  -Verbose

스크립트는 후속 명령에 대한 $configObj 변수와 Azure Resource Manager 템플릿에 필요한 JSON을 출력합니다. JSON 출력을 복사하여 기존 클러스터를 만들거나 수정할 때 사용합니다. Microsoft Entra ID 지원 클러스터를 만듭니다.

SetupApplications.ps1 예제 출력

Name                           Value
----                           -----
WebAppId                       f263fd84-ec9e-44c0-a419-673b1b9fd345
TenantId                       0e3d2646-78b3-4711-b8be-74a381d9890c
ServicePrincipalId             3d10f55b-1876-4a62-87db-189bfc54a9f2
NativeClientAppId              b22cc0e2-7c4e-480c-89f5-25f768ecb439

-----ARM template-----
"azureActiveDirectory": {
  "tenantId":"0e3d2646-78b3-4711-b8be-74a381d9890c",
  "clusterApplication":"f263fd84-ec9e-44c0-a419-673b1b9fd345",
  "clientApplication":"b22cc0e2-7c4e-480c-89f5-25f768ecb439"
},

azureActiveDirectory 매개 변수 개체 JSON

"azureActiveDirectory": {
  "tenantId":"<guid>",
  "clusterApplication":"<guid>",
  "clientApplication":"<guid>"
},

SetupUser.ps1

SetupUser.ps1은 위의 $configObj 출력 변수를 사용하여 사용자 계정을 새로 만든 앱 등록에 추가하는 데 사용됩니다. 앱 등록을 사용하여 구성할 사용자 계정의 사용자 이름을 지정하고, 관리 권한에 대해 'isAdmin'을 지정합니다. 새 사용자 계정인 경우 새 사용자에 대한 임시 암호도 제공합니다. 처음 로그온할 때 암호를 변경해야 합니다. '-remove'를 사용하면 앱 등록뿐만 아니라 사용자 계정도 제거됩니다.

SetupUser.ps1 사용자(읽기) 예제

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestUser' `
  -Password 'P@ssword!123' `
  -Verbose

SetupUser.ps1 관리자(읽기/쓰기) 예제

.\SetupUser.ps1 -ConfigObj $configobj `
  -UserName 'TestAdmin' `
  -Password 'P@ssword!123' `
  -IsAdmin `
  -Verbose

SetupClusterResource.ps1

SetupClusterResource.ps1은 필요에 따라 기존 클러스터 리소스 ARM 템플릿을 내보내고, 'azureActiveDirectory' 구성을 추가/수정하고, 템플릿을 다시 배포하는 데 사용할 수 있습니다. '-Whatif'를 사용하여 템플릿을 내보내고 수정할 뿐 구성 변경 내용을 다시 배포하지 않습니다. 이 스크립트에는 Azure 'Az' 모듈과 클러스터에 대한 리소스 그룹의 이름이 필요합니다.

SetupClusterResource.ps1 -whatIf 예제

# requires azure module 'az'
# install-module az
$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName `
  -WhatIf

템플릿이 확인되고 처리할 준비가 되면 '-WhatIf' 없이 스크립트를 다시 실행하거나 'New-AzResourceGroupDeployment' powershell commandlet을 사용하여 템플릿을 배포합니다.

SetupClusterResource.ps1 예제

$resourceGroupName = 'mysftestcluster'
.\SetupClusterResource.ps1 -configObj $configObj `
  -resourceGroupName $resourceGroupName

참고 항목

새로운 클러스터 리소스 Microsoft Entra 구성 변경 내용으로 클러스터 프로비전 ARM 템플릿 또는 스크립트를 업데이트합니다.

구성 중인 'API 권한'에 대해 '관리자 동의 허용'이 필요할 수 있습니다. Azure 앱 등록 블레이드로 이동하여 클러스터 이름을 필터에 추가합니다. 두 등록 모두에 대해 'API 권한'을 열고, 사용 가능한 경우 '다음에 대한 관리자 동의 허용'을 선택합니다.

Screenshot that shows Grant admin consent selected on the Azure App registrations blade.

Screenshot that shows the Grant admin consent confirmation with Yes highlighted.

Microsoft Entra 구성 확인

SFX(Service Fabric Explorer) URL로 이동합니다. 이는 spaApplicationReplyUrl 매개 변수와 동일해야 합니다. Azure 인증 대화 상자가 표시됩니다. 새로운 Microsoft Entra 구성으로 구성된 계정으로 로그온합니다. 관리자 계정에 읽기/쓰기 액세스 권한이 있고 사용자에게 읽기 액세스 권한이 있는지 확인합니다. 클러스터에 대한 수정(예: 작업 수행)은 관리 작업입니다.

Microsoft Entra ID 설정 문제 해결 도움말

Microsoft Entra ID를 설정하고 사용하는 것은 어려울 수 있으므로 문제를 디버깅하기 위해 수행할 수 있는 작업에 대한 몇 가지 지침은 다음과 같습니다. 'SetupApplications.ps1' 및 'SetupUser.ps1' 스크립트에서 '-logFile' 인수를 사용하여 PowerShell 기록 로깅을 사용하도록 설정하면 출력을 검토할 수 있습니다.

참고 항목

ID 플랫폼 마이그레이션(ADAL에서 MSAL로), Azure AZ를 위한 AzureRM 사용 중단 및 여러 버전의 PowerShell 지원을 사용하면 종속성이 항상 올바르지 않거나 최신 상태가 아닐 수 있으므로 스크립트 실행에서 오류가 발생할 수 있습니다. Azure Cloud Shell에서 PowerShell 명령 및 스크립트를 실행하면 세션 자동 인증 및 관리 ID와 관련된 오류의 가능성이 줄어듭니다.

Button to launch the Azure Cloud Shell.

Request_BadRequest

문제

유효한 참조 업데이트가 아닙니다. Http 상태 코드: 400

VERBOSE: POST with 157-byte payload
VERBOSE: received -byte response of content type application/json
>> TerminatingError(Invoke-WebRequest): "{"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}"
confirm-graphApiRetry returning:True
VERBOSE: invoke-graphApiCall status: 400
exception:
Response status code doesn't indicate success: 400 (Bad Request).

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Request_BadRequest","message":"Not a valid reference update.","innerError":{"date":"2022-09-11T22:17:16","request-id":"61fadb2a-478b-4483-8f23-d17e13732104","client-request-id":"61fadb2a-478b-4483-8f23-d17e13732104"}}}

at invoke-graphApiCall, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 239
at invoke-graphApi, /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1: line 275
at add-roleAssignment, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 193
at add-user, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 244
at enable-AADUser, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 178
at main, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 136
at <ScriptBlock>, /home/<user>/clouddrive/service-fabric-aad-helpers/SetupUser.ps1: line 378
at <ScriptBlock>, /home/<user>/clouddrive/aad-test.ps1: line 43
at <ScriptBlock>, <No file>: line 1
WARNING: invoke-graphApiCall response status: 400
invoke-graphApi count:0 statuscode:400 -uri https://graph.microsoft.com/v1.0/0e3d2646-78b3-4711-b8be-74a381d9890c/servicePrincipals/3d10f55b-1876-4a62-87db-189bfc54a9f2/appRoleAssignedTo -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
confirm-graphApiRetry returning:True

원인

구성 변경 내용이 전파되지 않았습니다. 스크립트는 HTTP 상태 코드 400 및 404를 사용하여 특정 요청을 다시 시도합니다.

솔루션

기본적으로 5분인 '-timeoutMin'이 제공될 때까지 스크립트에서 400 및 404 HTTP 상태 코드의 특정 요청을 다시 시도합니다. 필요에 따라 스크립트를 다시 실행할 수 있습니다.

Service Fabric Explorer에 인증서를 선택하라는 메시지가 표시

문제

Service Fabric Explorer에서 Microsoft Entra ID에 성공적으로 로그인하면 브라우저가 홈페이지로 돌아가지만 인증서를 선택하라는 메시지가 표시됩니다.

SFX certificate dialog

원인

사용자에게 Microsoft Entra ID 클러스터 애플리케이션의 역할이 할당되지 않았습니다. 따라서 Service Fabric 클러스터에서 Microsoft Entra 인증이 실패합니다. Service Fabric Explorer는 인증서 인증으로 대체됩니다.

솔루션

Microsoft Entra ID 설정 지침을 따르고 사용자 역할을 할당합니다. 또한 SetupApplications.ps1에서와 같이 "앱에 액세스하려면 사용자 할당 필요"를 켜는 것이 좋습니다.

“지정된 자격 증명이 올바르지 않다”는 오류가 표시되면서 PowerShell 연결 실패

문제

PowerShell을 사용하여 "AzureActiveDirectory" 보안 모드를 사용하여 클러스터에 연결하면 Microsoft Entra ID에 성공적으로 로그인한 후 "지정된 자격 증명이 잘못되었습니다."라는 오류와 함께 연결이 실패합니다.

솔루션

이 솔루션은 이전과 동일합니다.

로그인할 때 Service Fabric Explorer가 실패를 반환함: "AADSTS50011"

문제

Service Fabric Explorer에서 Microsoft Entra ID에 로그인하려고 하면 페이지에서 오류를 반환합니다. "AADSTS50011: 회신 주소 <url>이 애플리케이션에 대해 구성된 회신 주소(<guid>)와 일치하지 않습니다."

SFX reply address doesn't match

원인

Service Fabric Explorer를 나타내는 클러스터(웹) 애플리케이션은 Microsoft Entra ID에 대해 인증을 시도하고 요청의 일부로 리디렉션 반환 URL을 제공합니다. 하지만 해당 URL은 Microsoft Entra 애플리케이션의 회신 URL 목록에 나와 있지 않습니다.

솔루션

클러스터의 Microsoft Entra 앱 등록 페이지에서 인증을 선택하고 리디렉션 URI 섹션에서 Service Fabric Explorer URL을 목록에 추가합니다. 변경 내용을 저장합니다.

Web application reply URL

PowerShell을 통해 Microsoft Entra 인증을 사용하여 클러스터에 연결하면 로그인할 때 "AADSTS50011" 오류가 발생합니다.

문제

PowerShell을 통해 Microsoft Entra ID를 사용하여 Service Fabric 클러스터에 연결하려고 하면 로그인 페이지에서 오류를 반환합니다. "AADSTS50011: 요청에 지정된 회신 URL이 애플리케이션에 대해 구성된 회신 URL(<guid>)과 일치하지 않습니다."

원인

이전 문제와 마찬가지로 PowerShell은 Microsoft Entra 애플리케이션 회신 URL 목록에 나열되지 않은 리디렉션 URL을 제공하는 Microsoft Entra ID에 대해 인증을 시도합니다.

솔루션

이전 문제에서와 동일한 프로세스를 사용하지만 URL은 명령줄 인증을 위한 특수 리디렉션인 urn:ietf:wg:oauth:2.0:oob로 설정되어야 합니다.

스크립트를 실행하면 권한 부여 오류에서 오류가 발생함

문제

PowerShell 스크립트는 "Authorization_RequestDenied", "작업을 완료하는 데 필요한 권한이 없습니다." 오류로 인해 Microsoft Entra 구성을 완료하는 데 필요한 모든 REST 명령을 수행하지 못할 수 있습니다. 오류 예제는 다음과 같습니다.

Invoke-WebRequest: /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:239
Line |
 239 |  …   $result = Invoke-WebRequest $uri -Method $method -Headers $headers  …
     |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | {"error":{"code":"Authorization_RequestDenied","message":"Insufficient privileges to complete the
     | operation.","innerError":{"date":"2022-08-29T14:46:37","request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0","client-request-id":"c4fd3acc-1558-4950-8028-68bb058f7bf0"}}}
...
invoke-graphApi count:0 statuscode:403 -uri https://graph.microsoft.com/v1.0/72f988bf-86f1-41af-91ab-2d7cd011db47/oauth2PermissionGrants -headers System.Collections.Hashtable -body System.Collections.Hashtable -method post
Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:364
Line |
 364 |      assert-notNull $result "aad app service principal oauth permissio …
     |      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     | aad app service principal oauth permissions User.Read configuration failed

Write-Error: /home/<user>/clouddrive/service-fabric-aad-helpers/SetupApplications.ps1:656
Line |
 656 |  main
     |  ~~~~
     | exception:  exception: assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  Exception:
     | /home/<user>/clouddrive/service-fabric-aad-helpers/Common.ps1:22 Line |   22 |          throw "assertion failure: object:$obj message:$msg"      |         
     | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~      | assertion failure: object: message:aad app service principal oauth permissions User.Read configuration failed  
...

원인

스크립트를 실행하는 사용자 계정에 REST 호출을 수행할 수 있는 권한이 없으면 이 오류가 반환됩니다. 이는 사용자에게 만들거나 수정하는 개체에 대한 관리자/관리/쓰기 권한이 없는 경우에 발생할 수 있습니다.

솔루션

Azure 테넌트 관리자 또는 Microsoft Entra ID와 협력하여 나머지 모든 작업을 완료합니다. 제공된 스크립트는 멱등성이 있으므로 다시 실행하여 프로세스를 완료할 수 있습니다.

PowerShell을 통해 Microsoft Entra 인증을 사용하여 클러스터 연결

Service Fabric 클러스터에 연결하려면 다음 PowerShell 명령 예제를 사용합니다.

Connect-ServiceFabricCluster -ConnectionEndpoint <endpoint> -KeepAliveIntervalInSec 10 -AzureActiveDirectory -ServerCertThumbprint <thumbprint>

자세한 내용은 Connect-ServiceFabricCluster cmdlet를 참조하세요.

여러 클러스터에서 동일한 Microsoft Entra 테넌트를 재사용할 수 있나요?

예. 그렇지만 Service Fabric Explorer의 URL을 클러스터(웹) 애플리케이션에 추가해야 합니다. 그러지 않으면 Service Fabric Explorer가 작동하지 않습니다.

Microsoft Entra ID가 사용하도록 설정되어 있는데도 서버 인증서가 필요한 이유는 무엇인가요?

FabricClient와 FabricGateway는 상호 인증을 수행합니다. Microsoft Entra 인증 중에 Microsoft Entra 통합은 서버에 클라이언트 ID를 제공하고 클라이언트는 서버 인증서를 사용하여 서버의 ID를 확인합니다. Service Fabric 인증서에 대한 자세한 내용은 X.509 인증서 및 Service Fabric을 참조하세요.

다음 단계

Microsoft Entra 애플리케이션을 설정하고 사용자 역할을 설정한 후 클러스터를 구성 및 배포합니다.