Configurando o Fabric Link com Service Principal e Azure Key Vault
Configurar o Fabric Link parece simples: selecionar o workspace, informar as credenciais e avançar. Na prática, alguns detalhes podem transformar essa etapa em uma sequência de erros de autenticação.
Durante uma configuração no Dynamics 365 Finance & Operations, recebi mensagens de acesso negado ao Key Vault, falha na recuperação do segredo e credenciais inválidas.
Neste post, organizei o fluxo de configuração e os principais pontos de atenção para quem precisa utilizar um service principal com o client secret armazenado no Azure Key Vault.
1. Entendendo o cenário
O Link to Microsoft Fabric permite vincular um ambiente do Dataverse a um workspace do Fabric. Quando o ambiente está vinculado ao Dynamics 365 Finance & Operations, também é possível selecionar tabelas dessas aplicações no assistente.[learn.microsoft]
Neste tutorial, o foco é a configuração da autenticação:
Ambiente Dataverse vinculado ao D365 F&O
|
Fabric Link
|
Autenticação por Service Principal
|
Tenant ID + Client ID + Secret
|
Azure Key VaultO Azure Key Vault centraliza o armazenamento do segredo do cliente. No Fabric, uma referência identifica o cofre e o segredo a serem consultados para autenticar a conexão.[learn.microsoft]
Nota: a documentação atual recomenda Workspace identity quando essa opção atende ao cenário, pois elimina a necessidade de administrar client secrets. Este post trata da alternativa com service principal e segredo, utilizada quando há esse requisito na solução.[learn.microsoft]
2. Pré-requisitos
Antes de configurar a conexão, valide:
- Ambiente Dataverse vinculado ao F&O, para disponibilizar as tabelas do ERP.
- Permissão de System Administrator no ambiente Power Platform para configurar o link.
- Acesso administrativo ao workspace de destino.
- Capacidade ou licenciamento compatível com o Fabric Link.
- Permissão para administrar conexões no Fabric.
- Aplicação registrada no Microsoft Entra ID.
- Azure Key Vault disponível e acessível pelo caminho de rede utilizado pela conexão.[learn.microsoft][learn.microsoft]
Este tutorial não substitui a validação dos requisitos de versão e build do F&O. Consulte os requisitos atuais da Microsoft, especialmente se o ambiente utilizar o mecanismo de sincronização de baixa latência.[learn.microsoft]
3. Identifique corretamente as credenciais
Na configuração por service principal, os campos principais são:
| Campo | Informação utilizada |
|---|---|
| Tenant ID | Directory (tenant) ID |
| Service principal client ID | Application (client) ID |
| Service principal Key | Valor do client secret da aplicação |
O Client ID identifica a aplicação. O client secret é a credencial que ela usa para comprovar sua identidade.[learn.microsoft][learn.microsoft]
Dois erros comuns nessa etapa:
- Utilizar o Object ID em vez do Application/Client ID.
- Utilizar o Secret ID no lugar do valor do client secret.[learn.microsoft][learn.microsoft]
Os três elementos — tenant, aplicação e segredo — precisam corresponder entre si.
4. Cadastre a aplicação no Dataverse
Não basta registrar a aplicação no Entra ID. Para o Fabric Link, o service principal também precisa ser adicionado como Application User no ambiente do Dataverse e receber o papel apropriado.[learn.microsoft]
No Power Platform admin center:
- Abra o ambiente utilizado pelo Fabric Link.
- Acesse a área de usuários de aplicação.
- Selecione
New app user. - Adicione a aplicação pelo nome ou pelo Application/Client ID.
- Defina a Business Unit.
- Atribua o papel de segurança apropriado.
- Conclua o cadastro.
O procedimento documentado pela Microsoft normalmente utiliza o System Administrator para essa identidade. Como esse papel possui privilégios elevados, sua concessão deve seguir as diretrizes de governança do ambiente.[learn.microsoft]
5. Armazene o segredo no Azure Key Vault
No portal do Azure:
- Abra o Key Vault.
- Acesse
Objects > Secrets. - Clique em
+ Generate/Import. - Selecione a opção
Manual. - Informe o nome do segredo.
- No campo de valor, cole o client secret da aplicação.
- Clique em
Create. [learn.microsoft]
Exemplo ilustrativo:
Key Vault:
kv-fabric-prod
Nome do segredo:
fabric-link-client-secret
Valor:
[valor do client secret da aplicação]Guarde a distinção:
| Informação | Onde será utilizada |
|---|---|
| Nome do Key Vault | Na criação da referência no Fabric |
| Nome do segredo | No campo Secret da conexão |
| Valor do segredo | Armazenado dentro do Key Vault |
O Fabric utiliza o nome do segredo para localizar a credencial no cofre.[learn.microsoft]
6. Configure as permissões do Key Vault
Uma das principais armadilhas está no nome do papel. Key Vault Reader.
Apesar de permitir consultar os metadados dos objetos, esse papel não permite ler o conteúdo dos segredos.[learn.microsoft]
Em um cofre configurado com Azure RBAC:
| Papel | Finalidade |
|---|---|
| Key Vault Reader | Consultar metadados do cofre e dos objetos |
| Key Vault Secrets User | Ler o conteúdo dos segredos |
| Key Vault Secrets Officer | Criar e administrar segredos, sem administrar permissões |
Para recuperar o client secret, a identidade que acessa o cofre precisa de permissão para ler o conteúdo do cofre. Não é necessário conceder administração completa do Key Vault apenas para essa finalidade.[learn.microsoft]
Qual identidade deve receber acesso?
Neste fluxo existem duas identidades com funções diferentes:
- A conta utilizada para autenticar a referência do Key Vault no Fabric.
- O principal serviço utilizado na conexão do Fabric Link.
O Fabric consulta o Key Vault usando a autenticação armazenada na referência. Portanto, conceder acesso apenas ao service principal não substitui a autorização da conta utilizada nessa referência. A documentação exige as permissões Get e List para a identidade do usuário.[learn.microsoft]
No Azure:
Key Vault
> Access control (IAM)
> Add role assignment
> Key Vault Secrets User
> Selecionar a identidade corretaEsses papéis se aplicam ao modelo de RBAC do Azure. Se o cofre utiliza o modelo legado de Vault access policy, as permissões devem ser configuradas nas políticas de acesso. Não altere o modelo de um cofre existente sem avaliar as aplicações dependentes: a mudança para RBAC invalida as permissões das access policies.[learn.microsoft]
Nota sobre a documentação: o guia geral de referências do Fabric também lista o Key Vault Certificate User como pré-requisito para a criação da referência. Isso não deve ser confundido com o papel específico de leitura de segredos; confira os requisitos atuais caso o erro ocorra durante a criação da referência.[learn.microsoft][learn.microsoft]
7. Crie a referência do Key Vault no Fabric
No portal do Fabric:
- Abra a engrenagem de configurações.
- Selecione
Manage connections and gateways. - Abra a aba
Azure Key Vault references. - Clique em
New. Preencha:
Reference alias: nome amigável da referência.Account Name: nome do recurso Key Vault.
- Clique em
Edit credentials. - Autentique com a conta autorizada.
- Clique em
Create. - Verifique se a referência está disponível online.[learn.microsoft]
Exemplo:
| Campo | Valor ilustrativo |
|---|---|
| Reference alias | akv-fabric-prod |
| Account Name | kv-fabric-prod |
O alias pertence ao Fabric; o Account Name identifica o cofre existente no Azure.[learn.microsoft]
8. Utilize o segredo no Fabric Link
No Power Apps, abra o assistente do Fabric Link e configure a conexão:
- Selecione
Authentication kind = Service principal. - Informe o Tenant ID.
- Informe o Application/Client ID.
- Selecione a credencial do tipo Key.
- Clique em
Use Azure Key Vault. - Escolha a referência criada.
- No campo
Secret, informe somente o nome do segredo. - Clique em
Applye valide a conexão. A configuração por service principal faz parte do assistente do Fabric Link, enquanto a referência do Key Vault fornece a credencial pelo nome do segredo.[learn.microsoft][learn.microsoft]
Exemplo:
Azure Key Vault reference:
akv-fabric-prod
Secret:
fabric-link-client-secretNo campo Secret, não informe:
- O valor do client secret.
- A URL completa do segredo.
- O identificador da versão.
- O Secret ID da aplicação.
A configuração documentada utiliza a referência existente e o nome do segredo.[learn.microsoft]
9. Erros encontrados e roteiro de diagnóstico
Durante a configuração, apareceram três mensagens importantes. Elas ajudam a organizar a investigação, mas não devem ser interpretadas isoladamente como prova de uma causa específica.
“User does not have necessary permissions to access the Key Vault”
Comece verificando a identidade autenticada na referência e suas permissões.
Ter apenas Key Vault Reader não permite recuperar o valor do segredo. No Azure RBAC, confira a atribuição Key Vault Secrets User no cofre correto. Após alterar os papéis, aguarde alguns minutos para que as permissões sejam atualizadas.[learn.microsoft]
“Please ensure Key Vault exists and contains the necessary secrets”
Confira:
- Se o Account Name aponta para o cofre correto.
- Se o segredo existe nesse cofre.
- Se o campo Secret contém seu nome.
- Se a identidade da referência tem acesso.
- Se a rede permite alcançar o Key Vault.[learn.microsoft]
O Fabric consulta a versão atual, mais recente, do segredo. A referência não permite fixar uma versão específica. Por isso, revise a versão atual sempre que houver alterações no cofre.[learn.microsoft]
Se o Key Vault for privado, o guia prevê acesso por meio de um on-premises data gateway com conectividade via private endpoint. Não abra acesso público irrestrito apenas para contornar o erro.[learn.microsoft]
“Invalid credentials”
Confira a combinação:
Tenant ID
+
Application/Client ID
+
Valor do client secret dessa aplicaçãoVerifique se o segredo foi copiado corretamente, se pertence à aplicação informada e se não expirou no Entra ID. O fato de estar armazenado no Key Vault não torna válida uma credencial incorreta ou expirada.[learn.microsoft][learn.microsoft]
Quando permitido pela política da empresa, um teste temporário com a credencial preenchida diretamente na conexão ajuda a separar duas situações:
- Credencial aceita diretamente, mas não pela referência: investigar o cofre, o valor armazenado e a referência.
- Credencial rejeitada também diretamente: investigar primeiro o tenant, a aplicação e o segredo.
Esse teste é uma etapa de diagnóstico, não uma recomendação para abandonar o Key Vault.
10. Cuidados após a conexão funcionar
A configuração não termina na primeira validação bem-sucedida.
- Documente qual aplicação é utilizada pelo link e quem administra as credenciais dessa aplicação.
- Acompanhe a expiração do client secret no Entra ID.[learn.microsoft]
- Planeje a renovação: a referência do Fabric consulta a versão mais recente do segredo, portanto uma atualização no cofre precisa conter uma credencial válida para a mesma aplicação.[learn.microsoft]
- Separe as permissões de leitura das permissões de administração dos segredos.[learn.microsoft]
- Antes de publicar capturas de tela, oculte segredos, tokens e informações internas desnecessárias.
- Avalie Workspace identity em novos cenários, pois é a opção recomendada atualmente para evitar o gerenciamento de segredos.[learn.microsoft]
Conclusão
O maior aprendizado dessa configuração foi separar três perguntas:
- Quem está acessando o Key Vault?
- Qual segredo está sendo recuperado?
- Para qual aplicação esse segredo é válido?
Quando essas três respostas estão alinhadas, fica muito mais fácil distinguir uma falha de permissão, um problema de referência e um erro de autenticação.
Nenhum comentário:
Postar um comentário