Configurar a identidade gerida do Power Platform para plug-ins do Dataverse ou pacotes de plug-ins

Quando usa identidade gerida do Power Platform, os plug-ins ou pacotes de plug-ins do Dataverse podem ligar-se a recursos do Azure sem gerir credenciais. Este artigo descreve a configuração recomendada (versão 2), que constrói a credencial de identidade federada (FIC) a partir de um hash do Nome Distinto (DN) completo do certificado.

Porquê a versão 2

A versão 2 produz um identificador de sujeito de comprimento fixo, apenas ASCII, pelo que funciona com qualquer nome de certificado. A versão 1 falha em certos nomes de certificados (CNs):

• Caracteres não ASCII no CN (por exemplo, letras com acento) → AADSTS70050: The Federated Managed Identity path is not properly formatted.
• Vírgulas no CN (por exemplo, CN=Contoso, Inc.) → AADSTS700213: No matching federated identity record found.

Pré-requisitos

• Uma subscrição do Azure com acesso ao aprovisionamento da identidade gerida atribuída pelo utilizador (UAMI) ou registo de aplicação.
• Ferramentas para plug-ins ou pacotes de plug-in:
  • Ambiente de Desenvolvimento Integrado (IDE), como o Visual Studio, para construir plug-ins
  • Ferramenta de registo de plug-ins
  • SignTool.exe (Ferramenta de Assinatura) para assinar a assemblagem do plug-in
  • Power Platform CLI
• Um certificado válido para assinar a assemblagem do plug-in.

Configurar identidade gerenciada

1. Crie um novo registo de aplicação ou uma identidade gerida atribuída pelo utilizador.
2. Constrói, assina e regista o plug-in.
3. Configura a credencial de identidade federada.
4. Crie o registo de identidade gerida no Dataverse.
5. Conceda acesso ao recurso Azure.
6. Valida a integração.

Passo 1: Criar um registo de aplicação ou uma identidade gerida atribuída pelo utilizador

Crie uma identidade gerida atribuída pelo utilizador ou uma aplicação no Microsoft Entra ID:

• Para uma identidade de aplicação associada ao plug-in (para poderes aplicar políticas do Azure), usa o registo da aplicação.
• Para um principal de serviço, aprovisione uma identidade gerida atribuída pelo utilizador.

Passo 2: Construir, assinar e registar o plug-in

1. Cria um plug-in no Visual Studio. Use o ID do inquilino do passo 1 e um âmbito como https://{OrgName}.crm*.dynamics.com/.default. Use IManagedIdentityService para solicitar um token:

   string AcquireToken(IEnumerable<string> scopes);
   

2. Assine digitalmente o plug-in com o seu certificado.

   Pacote de plug-in (NuGet):

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

   Instalação do plug-in (SignTool):

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

3. Registe o plug-in usando a ferramenta de registo do plug-in.

Passo 3: Configurar a credencial de identidade federada

No portal do Azure, abra a sua aplicação ou identidade gerida atribuída a utilizador (UAMI), vá a Certificados e segredos>Credenciais federadas>Adicionar credencial e selecione Outro emissor. Em seguida, digite:

• Emitente — https://login.microsoftonline.com/{tenantID}/v2.0

• Tipo — Identificador explícito de assunto

• Identificador de assunto — use o formato para o seu tipo de certificado:

  • Certificado de emissor confiável (produção):

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

  • Certificado autoassinado (apenas para desenvolvimento):

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

  Referência do segmento

  Segmento	Description
  eid1	Versão do formato de identidade
  c/pub	Código para nuvem pública, GCC e primeira estação de disponibilização no GCC
  t/{encodedTenantId}	ID do inquilino. Consulte Obter o ID de tenant codificado
  a/qzXoWDkuqUa3l6zM5mM0Rw/	Apenas para uso interno. Não modifiquem
  n/plugin	Componente de extensão
  e/{environmentId}	ID do Ambiente
  i/{issuerHash} s/{subjectHash}	Hash SHA-256 em Base64URL do DN completo do emissor/do sujeito. Consulte Calcular os hashes do emitente e do titular
  h/{hash}	SHA-256 do certificado (apenas auto-assinado)

Calcular os hashes do emissor e do assunto

Calcule o hash SHA-256 das cadeias DN completas do emissor e do sujeito, tal como aparecem no certificado, e codifique cada uma em Base64 segura para URL. Obtenha as cadeias DN com:

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

Calcule os valores de hash (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"

Ou em 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 saída é uma cadeia de 43 caracteres contendo apenas A-Z, a-z, 0-9, -, e _.

Passo 4: Criar o registo de identidade gerida no Dataverse

Envie um pedido HTTP POST usando um cliente REST. Para a versão 2, defina version para 2.

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

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

Depois, vincule o conjunto do plug-in (ou pacote) ao registo:

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

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

Para um pacote plug-in, use pluginpackages(<<PluginPackageId>>) em vez disso.

Passo 5: Conceder acesso ao recurso Azure

Conceda à aplicação ou à identidade gerida atribuída pelo utilizador acesso ao recurso Azure de que necessita, como o Azure Key Vault.

Passo 6: Validar a integração

Ativa o plug-in e confirma que adquiriu um token e chega ao recurso Azure sem credenciais separadas.

Atualização para a versão 2

Se tiveres um plug-in na versão 0 ou 1, podes movê-lo para a versão 2 sem reconstruir ou registar novamente o plug-in.

Opção 1: CLI da Power Platform

1. Instale a CLI do Power Platform versão 2.8.1 ou posterior. Consulte Instalar Microsoft Power Platform CLI.
2. Crie um perfil de autenticação: pac auth create
3. Consulta a versão atual: pac managed-identity show-fic --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --version 2
4. Atualização: pac managed-identity upgrade-version --environment <orgUrl> --component-type PluginAssembly --component-id <pluginAssemblyId> --target-version 2 --confirm
5. Ative o plug-in para efetuar a validação.

Opção 2: Manual

1. Calcule os hashes do emissor e do assunto da versão 2. Veja Calcular os hashes do emissor e do assunto.

2. Adicione um novo FIC com o formato de identificador de assunto da versão 2 (Passo 3).

3. Atualize o registo de identidade gerida para a versão 2:

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

   { "version": 2 }
   

4. Acione o plug-in e verifique se a aquisição do token foi bem-sucedida.

5. Remova a versão antiga 1 do FIC.

Reference

Obtenha o ID do inquilino codificado

O ID do tenant codificado é o GUID do tenant convertido em bytes e codificado como Base64URL (não Base64 padrão):

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

Gerar um certificado autoassinado

Para desenvolvimento ou testes apenas:

$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

Calcule o certificado autoassinado {hash} (SHA-256 do .cer; exporte-o primeiro a partir de um .pfx, se necessário):

CertUtil -hashfile <CertificateFilePath> SHA256

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

Ambientes de nuvem especializados do Azure

Defina explicitamente o prefixo Audiência, URL do Emissor e Sujeito ao implementar fora da cloud pública, GCC e a primeira estação de lançamento no GCC.

Perguntas mais frequentes (FAQ)

Como resolvo AADSTS700213: Nenhum registo de identidade federado correspondente encontrado?

O identificador de assunto calculado em tempo de execução não corresponde a nenhum FIC da aplicação. Verifique se:

1. Configuraste e guardaste o FIC.
2. O emissor e o assunto correspondem ao formato do Passo 3. Você também pode encontrar o formato esperado na pilha de erros.
3. O registo version é 2 e o FIC utiliza o formato de hash da versão 2.
4. O hash é calculado a partir da string DN do tempo de execução (X509Certificate2.Issuer / X509Certificate2.Subject).
5. O emissor é https://login.microsoftonline.com/{tenantId}/v2.0 e o público é api://AzureADTokenExchange (distintor de maiúsculas e minúsculas).

Como resolvo AADSTS70050: O caminho da Identidade Gerida Federada não está devidamente formatado?

O identificador de sujeito contém caracteres que o fornecedor de identidade não aceita — na maioria das vezes caracteres não ASCII no certificado CN da versão 1. A versão 2 produz um identificador do assunto composto apenas por caracteres ASCII e resolve este erro.

Como resolvo o erro "Não é possível alcançar ou conectar-se à Power Platform"?

Para garantir que os pontos finais do Power Platform estão acessíveis e incluídos na lista de permissões, consulte URLs e intervalos de endereços IP do Power Platform.