Dataverse 플러그 인 또는 플러그 인 패키지에 대한 Power Platform 관리 ID 설정

Power Platform 관리 ID를 사용하는 경우 Dataverse 플러그 인 또는 플러그 인 패키지는 자격 증명을 관리하지 않고도 Azure 리소스에 연결할 수 있습니다. 이 문서에서는 인증서의 전체 DN(고유 이름) 해시에서 페더레이션 ID 자격 증명(FIC)을 빌드하는 권장(버전 2) 설정에 대해 설명합니다.

왜 버전 2

버전 2는 고정 길이 ASCII 전용 주체 식별자를 생성하므로 모든 인증서 이름에서 작동합니다. 특정 인증서 이름(CN)에서 버전 1이 실패합니다.

• CN의 ASCII가 아닌 문자(예: 악센트가 있는 문자)는 →AADSTS70050: The Federated Managed Identity path is not properly formatted.
• CN의 쉼표(예: CN=Contoso, Inc.)는 →AADSTS700213: No matching federated identity record found.

Prerequisites

• UAMI(사용자 할당 관리 ID) 또는 애플리케이션 등록을 프로비전할 수 있는 액세스 권한이 있는 Azure 구독입니다.
• 플러그 인 또는 플러그 인 패키지용 도구:
  • 플러그 인을 빌드하기 위해 Visual Studio 같은 IDE(통합 개발 환경)
  • 플러그 인 등록 도구
  • SignTool.exe(서명 도구)를 사용하여 플러그 인 어셈블리에 서명
  • Power Platform CLI
• 플러그 인 어셈블리에 서명할 유효한 인증서입니다.

관리 ID 설정

1. 새 앱 등록 또는 사용자가 할당한 관리 ID를 만듭니다.
2. 플러그 인을 빌드, 로그인 및 등록합니다.
3. 페더레이션 ID 자격 증명을 구성합니다.
4. Dataverse에서 관리 ID 레코드를 만듭니다.
5. Azure 리소스에 대한 액세스 권한을 부여합니다.
6. 통합의 유효성을 검사합니다.

1단계: 앱 등록 또는 사용자 할당 관리 ID 만들기

Microsoft Entra ID에서 사용자 할당 관리형 ID 또는 애플리케이션 중 하나를 만듭니다:

• 플러그 인과 연결된 앱 ID의 경우(Azure 정책을 적용할 수 있도록) 애플리케이션 등록을 사용합니다.
• 서비스 주체의 경우 사용자 할당 관리 ID를 프로비전합니다.

2단계: 플러그 인 빌드, 로그인 및 등록

1. Visual Studio 플러그 인을 만듭니다. 1단계의 테넌트 ID와 다음과 같은 https://{OrgName}.crm*.dynamics.com/.default범위를 사용합니다. IManagedIdentityService를 사용하여 토큰을 요청합니다.

   string AcquireToken(IEnumerable<string> scopes);
   

2. 인증서를 사용하여 플러그 인에 로그인합니다.

   플러그 인 패키지(NuGet):

   nuget sign YourPlugin.nupkg `
     -CertificatePath MyCert.pfx `
     -CertificatePassword "MyPassword" `
     -Timestamper http://timestamp.digicert.com
   

   플러그 인 어셈블리(SignTool):

   signtool sign /f MyCert.pfx /p MyPassword /t http://timestamp.digicert.com /fd SHA256 MyAssembly.dll
   

3. 플러그인 등록 도구를 사용하여 플러그인을 등록합니다.

3단계: 페더레이션 ID 자격 증명 구성

Azure 포털에서 앱 또는 UAMI(사용자 할당 관리 ID)를 열고, 인증서 및 비밀>페더레이션 자격 증명>으로 이동하고, 다른 발급자를 선택합니다. 그런 다음, 다음을 입력합니다.

• 발급자 — https://login.microsoftonline.com/{tenantID}/v2.0

• 형식 - 명시적 주체 식별자

• 주체 식별자 - 인증서 유형에 대한 형식을 사용합니다.

  • 신뢰할 수 있는 발급자 인증서(프로덕션):

    /eid1/c/pub/t/{encodedTenantId}/a/qzXoWDkuqUa3l6zM5mM0Rw/n/plugin/e/{environmentId}/i/{issuerHash}/s/{subjectHash}
    

  • 자체 서명된 인증서(개발 전용):

    /eid1/c/pub/t/{encodedTenantId}/a/qzXoWDkuqUa3l6zM5mM0Rw/n/plugin/e/{environmentId}/h/{hash}
    

  세그먼트 참조

  세그먼트	Description
  eid1	ID 형식 버전
  c/pub	퍼블릭 클라우드, GCC 및 GCC의 첫 번째 릴리스 스테이션용 클라우드 코드
  t/{encodedTenantId}	테넌트 ID. 인코딩된 테넌트 ID 가져오기를 참조하세요.
  a/qzXoWDkuqUa3l6zM5mM0Rw/	내부용으로만 사용됩니다. 수정 안 함
  n/plugin	플러그 인 구성 요소
  e/{environmentId}	환경 ID
  i/{issuerHash} s/{subjectHash}	전체 발급자/서브젝트 DN의 SHA-256 Base64URL 해시입니다. 발급자 및 주체 해시 계산을 참조하세요
  h/{hash}	인증서의 SHA-256(자체 서명된 경우에만)

발급자 및 제목 해시 계산

인증서에 표시되는 전체 발급자 및 주체 DN 문자열의 SHA-256 해시를 가져와 URL로부터 안전한 Base64로 인코딩합니다. 다음을 사용하여 DN 문자열을 가져옵니다.

$cert = Get-PfxCertificate -FilePath "path\to\your.pfx"
Write-Host "Issuer:  $($cert.Issuer)"
Write-Host "Subject: $($cert.Subject)"

해시 계산(PowerShell):

function Get-Sha256Base64Url {
    param([string]$InputString)
    $bytes = [System.Text.Encoding]::UTF8.GetBytes($InputString)
    $sha256 = [System.Security.Cryptography.SHA256]::Create()
    $hash = $sha256.ComputeHash($bytes)
    $base64 = [Convert]::ToBase64String($hash)
    return $base64.Replace('+', '-').Replace('/', '_').TrimEnd('=')
}

$issuerHash = Get-Sha256Base64Url -InputString "<full issuer DN string>"
$subjectHash = Get-Sha256Base64Url -InputString "<full subject DN string>"
Write-Host "Issuer Hash:  $issuerHash"
Write-Host "Subject Hash: $subjectHash"

또는 C#에서:

using System.Security.Cryptography;
using System.Text;

static string ComputeSha256Base64Url(string input)
{
    using var sha256 = SHA256.Create();
    byte[] hashBytes = sha256.ComputeHash(Encoding.UTF8.GetBytes(input));
    return Convert.ToBase64String(hashBytes)
        .Replace('+', '-')
        .Replace('/', '_')
        .TrimEnd('=');
}

출력은 A-Z, a-z, 0-9, - 및 _만 포함하는 43자 문자열입니다.

4단계: Dataverse에서 관리 ID 레코드 만들기

REST 클라이언트를 사용하여 HTTP POST 요청을 보냅니다. 버전 2의 경우 version를 2(으)로 설정합니다.

POST https://<<orgURL>>/api/data/v9.0/managedidentities

{
  "applicationid": "<<appId>>",
  "managedidentityid": "<<anyGuid>>",
  "credentialsource": 2,
  "subjectscope": 1,
  "tenantid": "<<tenantId>>",
  "version": 2
}

그런 다음, 플러그 인 어셈블리(또는 패키지)를 레코드에 바인딩합니다.

PATCH https://<<orgURL>>/api/data/v9.0/pluginassemblies(<<PluginAssemblyId>>)

{
  "managedidentityid@odata.bind": "/managedidentities(<<ManagedIdentityGuid>>)"
}

플러그 인 패키지의 경우 대신 사용합니다 pluginpackages(<<PluginPackageId>>) .

5단계: Azure 리소스에 대한 액세스 권한 부여

애플리케이션 또는 사용자 할당 관리 ID에 필요한 Azure 리소스(예: Azure Key Vault)에 대한 액세스 권한을 부여합니다.

6단계: 통합 유효성 검사

플러그 인을 트리거하고 토큰을 획득하고 별도의 자격 증명 없이 Azure 리소스에 도달하는지 확인합니다.

버전 2로 업그레이드

버전 0 또는 버전 1에 플러그 인이 있는 경우 플러그 인을 다시 빌드하거나 다시 등록하지 않고 버전 2로 이동할 수 있습니다.

옵션 1: Power Platform CLI

1. Power Platform CLI 버전 2.8.1 이상을 설치합니다. MICROSOFT POWER PLATFORM CLI 설치를 참조하세요.
2. 인증 프로필을 만듭니다. pac auth create
3. 현재 버전을 확인합니다. pac managed-identity show-fic --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --version 2
4. 업그레이드: pac managed-identity upgrade-version --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --target-version 2 --confirm
5. 플러그 인을 트리거하여 유효성을 검사합니다.

옵션 2: 수동

1. 버전 2 발급자 및 주체 해시를 계산합니다. 발급자 및 제목 해시 계산을 참조하세요.

2. 버전 2 주체 식별자 형식을 사용하여 새 FIC를 추가합니다(3단계).

3. 관리 ID 레코드를 버전 2로 업데이트합니다.

   PATCH https://<<orgURL>>/api/data/v9.0/managedidentities(<<ManagedIdentityId>>)
   

   { "version": 2 }
   

4. 플러그 인을 트리거하고 토큰 획득이 성공했는지 확인합니다.

5. 이전 버전 1 FIC를 제거합니다.

Reference

인코딩된 테넌트 ID 가져오기

인코딩된 테넌트 ID는 바이트로 변환되고 Base64URL 로 인코딩된 테넌트 GUID입니다(표준 Base64 아님).

$tenantId = "<your-tenant-guid>"
$tenantGuid = [System.Guid]::Parse($tenantId)
$tenantBytes = $tenantGuid.ToByteArray()
$base64 = [System.Convert]::ToBase64String($tenantBytes)
$encodedTenantId = $base64.Replace('+', '-').Replace('/', '_').TrimEnd('=')
$encodedTenantId

자체 서명된 인증서 생성

개발 또는 테스트 전용:

$params = @{
    Type = 'Custom'
    Subject = 'E=admin@contoso.com,CN=Contoso'
    TextExtension = @(
        '2.5.29.37={text}1.3.6.1.5.5.7.3.4',
        '2.5.29.17={text}email=admin@contoso.com' )
    KeyAlgorithm = 'RSA'
    KeyLength = 2048
    SmimeCapabilities = $true
    CertStoreLocation = 'Cert:\CurrentUser\My'
}
New-SelfSignedCertificate @params

자체 서명된 {hash}을 계산합니다(SHA-256은 .cer에 대해 계산하며, 필요한 경우 먼저 .pfx에서 내보내세요):

CertUtil -hashfile <CertificateFilePath> SHA256

$cert = Get-PfxCertificate -FilePath "path\to\your.pfx"
$cert.RawData | Set-Content -Encoding Byte -Path "extracted.cer"

특수한 Azure 클라우드 환경

퍼블릭 클라우드, GCC 및 GCC의 첫 번째 릴리스 스테이션 외부에 배포하는 경우 대상, 발급자 URL 및 주체 접두사를 명시적으로 설정합니다.

FAQ(질문과 대답)

AADSTS700213 확인하려면 어떻게 해야 하나요? 일치하는 페더레이션 ID 레코드를 찾을 수 없나요?

런타임에 계산된 주체 식별자는 앱의 FIC와 일치하지 않습니다. 다음 사항을 확인합니다.

1. FIC를 구성하고 저장했습니다.
2. 발급자와 제목은 3단계의 형식과 일치합니다. 오류 스택에서 예상 형식을 찾을 수도 있습니다.
3. 레코드 version 이며 2 FIC는 버전 2 해시 형식을 사용합니다.
4. 해시는 런타임의 DN 문자열(X509Certificate2.Issuer / X509Certificate2.Subject)에서 계산됩니다.
5. 발급자는 https://login.microsoftonline.com/{tenantId}/v2.0이고 대상은 api://AzureADTokenExchange(대/소문자 구분)입니다.

AADSTS70050: 페더레이션된 관리 ID 경로의 형식이 올바르지 않습니다. 이 문제를 해결하려면 어떻게 해야 하나요?

주체 식별자에는 ID 공급자가 허용하지 않는 문자(버전 1의 인증서 CN에서 ASCII가 아닌 문자)가 포함됩니다. 버전 2는 ASCII 전용 주체 식별자를 생성하고 이 오류를 해결합니다.

"Power Platform에 연결할 수 없음" 오류를 해결하려면 어떻게 해야 하나요?

Power Platform 엔드포인트에 연결할 수 있고 허용 목록에 포함되도록 하려면 Power Platform URL 및 IP 주소 범위를 참조하세요.