Criar um registro de aplicativo para usar com os Gêmeos Digitais do Azure

Este artigo descreve como criar um registro de aplicativo de IDdo Microsoft Entra que pode acessar os Gêmeos Digitais do Azure. Este artigo inclui etapas para o portal do Azure e a CLI do Azure.

Ao trabalhar com Gêmeos Digitais do Azure, é comum interagir com seua instância por meio das aplicativos clientes. Será preciso autenticar esses aplicativos nos Gêmeos Digitais do Azure, e alguns dos mecanismos de autenticação que os aplicativos podem usar envolvem a obtenção de um registro de aplicativo.

O registro do aplicativo não é necessário para todos os cenários de autenticação. No entanto, caso esteja usando uma estratégia de autenticação ou um exemplo de código que exija um registro de aplicativo, este artigo mostrará como configurar isso e conceder a ele permissões para as APIs dos Gêmeos Digitais do Azure. Ele também abordará como coletar valores importantes que você precisará para usar o registro do aplicativo durante a autenticação.

Dica

Talvez você prefira configurar um novo registro de aplicativo sempre que precisar de um ou fazer isso somente uma vez, estabelecendo um registro de aplicativo único que será compartilhado entre todos os cenários em que ele é necessário.

Criar o registro

Comece selecionando a guia abaixo para sua interface de preferência.

Portal

Navegue até a ID do Microsoft Entra no portal do Azure (você pode usar esse link ou localizá-lo com a barra de pesquisa do portal). Selecione a opção Registros de aplicativo no menu de serviço, depois clique em +Novo registro.

Na seguinte página Registrar um aplicativo, preencha os valores solicitados:

• Nome: um nome de exibição do aplicativo Microsoft Entra para associar ao registro
• Tipos de contas com suporte: selecione Contas somente neste diretório organizacional (somente o diretório padrão – locatário único)
• URI de redirecionamento: uma URL de resposta do aplicativo Microsoft Entra para o aplicativo Microsoft Entra. Adicione um URI Cliente/nativo público (móvel e desktop) para http://localhost.

Quando terminar, escolha o botão Registrar.

Quando a configuração do registro for concluída, o portal vai redirecionar você para a página de detalhes.

CLI

Comece criando um arquivo de manifesto que contenha informações de serviço que seu registro de aplicativo precisará para acessar as APIs dos Gêmeos Digitais do Azure. Posteriormente, você passará esse arquivo para um comando da CLI para criar o registro.

Criar manifesto

Crie um arquivo .json em seu computador chamado manifest.json. Copie este texto no arquivo:

[
	{
		"resourceAppId": "0b07f429-9f4b-4714-9392-cc5e8e80c8b0",
		"resourceAccess": [
			{
				"id": "4589bd03-58cb-4e6c-b17f-b580e39652f8",
				"type": "Scope"
			}
		]
	}
]

O valor estático 0b07f429-9f4b-4714-9392-cc5e8e80c8b0 é a ID do recurso do ponto de extremidade de serviço dos Gêmeos Digitais do Azure, que o registro do aplicativo precisará para acessar as APIs dos Gêmeos Digitais do Azure.

Salve o arquivo concluído.

Usuários do Cloud Shell: fazer upload do manifesto

Se você estiver usando o Azure Cloud Shell para este tutorial, será necessário fazer o upload do arquivo de manifesto que você criou para o Cloud Shell, para que seja possível acessá-lo em comandos do Cloud Shell ao configurar o registro do aplicativo. Se você estiver usando uma instalação local da CLI do Azure, poderá passar para a próxima etapa, Executar o comando de criação.

Para carregar o arquivo, acesse a janela do Cloud Shell no navegador. Clique no ícone "Carregar/Baixar arquivos", depois em "Carregar".

Navegue até o arquivo manifest.json no computador e selecione Abrir. Ao fazer isso o arquivo será carregado na raiz do armazenamento do Cloud Shell.

Executar o comando de criação

Nesta seção, você executará um comando da CLI para criar um registro de aplicativo com as seguintes configurações:

• Nome de sua preferência
• Disponível somente para contas no diretório padrão (locatário único)
• Uma URL de resposta da Web de http://localhost
• Permissões de leitura/gravação para as APIs dos Gêmeos Digitais do Azure

Execute o seguinte comando para criar o registro. Se você estiver usando Cloud Shell, o caminho para o arquivo manifest.json será @manifest.json.

az ad app create --display-name <app-registration-name> --available-to-other-tenants false --reply-urls http://localhost --native-app --required-resource-accesses "<path-to-manifest.json>"

A saída do comando contém informações sobre o registro de aplicativo que você criou.

Verificar êxito

Confirme se as permissões dos Gêmeos Digitais do Azure foram concedidas procurando os campos a seguir na saída do comando de criação, em requiredResourceAccess. Confirme se os valores são correspondentes ao listado abaixo.

• resourceAccess > id é 4589bd03-58cb-4e6c-b17f-b580e39652f8
• resourceAppId é 0b07f429-9f4b-4714-9392-cc5e8e80c8b0

Coletar valores importantes

Em seguida, colete alguns valores importantes sobre o registro de aplicativo que você precisará para usar o registro de aplicativo para autenticar um aplicativo cliente. Esses valores incluem:

• nome do recurso — Ao trabalhar com Gêmeos Digitais do Azure, o nome do recurso é http://digitaltwins.azure.net.
• ID do cliente
• ID do locatário
• segredo do cliente

As seções a seguir descrevem como encontrar os valores restantes.

Coletar a ID do cliente e a ID do locatário

Para usar o registro de aplicativo para autenticação, talvez seja necessário fornecer a ID do aplicativo (cliente) e a ID do diretório (locatário). Aqui, você coletará esses valores para que possa salvá-los e usá-los sempre que eles forem necessários.

Portal

Os valores ID do cliente e ID do locatário podem ser coletados na página de detalhes do registro de aplicativo no portal do Azure:

Anote a ID do aplicativo (cliente) e a ID do diretório (locatário) mostradas em sua página.

CLI

Você pode encontrar ambos os valores na saída do comando az ad app create executado anteriormente. (Você também pode ativar as informações do registro do aplicativo novamente usando az ad app show.)

Procure esses valores no resultado:

ID do aplicativo (cliente):

ID do diretório (locatário):

Coletar segredo do cliente

Configure um segredo do cliente para o registro do aplicativo, que outros aplicativos podem usar para autenticar.

Portal

Comece na página de registro do aplicativo no portal do Azure.

1. Selecione Certificados e segredos no menu do registro e, em seguida, selecione + Novo segredo do cliente.

   

2. Insira os valores que você desejar em Descrição e Expira e selecione Adicionar.

   

3. Confirme se o segredo do cliente aparece na página Certificados e segredos com os campos Expira e Valor.

4. Anote o a ID do Segredo e o Valor para usar posteriormente ou use os ícones Copiar para copiá-los para a área de transferência.

   

Importante

Copie os valores agora e armazene-os em um local seguro, pois eles não poderão ser recuperados novamente. Se você não os encontrar mais tarde, precisará criar outro segredo.

CLI

Para criar um segredo do cliente para o registro do aplicativo, você precisará do valor da ID do cliente do registro de aplicativo coletada na etapa anterior. Use o valor no comando da CLI a seguir para criar um segredo:

az ad app credential reset --id <client-ID> --append

Você também pode adicionar parâmetros opcionais a esse comando para especificar uma descrição de credencial, uma data de término e outros detalhes. Para obter informações sobre o comando e seus parâmetros adicionais, confira a documentação do az ad app credential reset.

A saída desse comando contém informações sobre o segredo do cliente que você criou.

Copie o valor de password a ser usado quando você precisar do segredo do cliente para autenticação.

Importante

Copie o valor agora e armazene-o em um local seguro, pois ele não poderá ser recuperado novamente. Se você não encontrar o valor mais tarde, precisará criar outro segredo.

Fornecer permissões aos Gêmeos Digitais do Azure

Em seguida, configure o registro de aplicativo criado com permissões para acessar os Gêmeos Digitais do Azure. Há dois tipos de permissões necessárias:

• Uma atribuição de função para o registro do aplicativo na instância do Gêmeos Digitais do Azure
• Permissões de API para o aplicativo ler e gravar nas APIs dos Gêmeos Digitais do Azure

Criar atribuição de função

Nesta seção, você criará uma atribuição de função para o registro do aplicativo na instância do Gêmeos Digitais do Azure. Essa função determinará quais permissões o registro do aplicativo mantém na instância, portanto, você deve selecionar a função que corresponde ao nível apropriado de permissão para sua situação. Uma função possível é o Proprietário dos Dados dos Gêmeos Digitais do Azure. Para ver uma lista completa de funções e suas descrições, confira Funções interna do Azure.

Portal

Use estas etapas para criar a atribuição de função para o registro.

1. Abra a página da instância dos Gêmeos Digitais do Azure no portal do Azure.

2. Selecione IAM (Controle de acesso) .

3. Selecione Adicionar>Adicionar atribuição de função para abrir a página Adicionar atribuição de função.

4. Atribua a função adequado. Para ver as etapas detalhadas, confira Atribuir funções do Azure usando o portal do Azure.

   Configuração	Valor
   Função	Selecione conforme adequado
   Membros > Atribuir acesso a	Usuário, grupo ou entidade de serviço
   Membros > Membros	+ Selecione membros e, em seguida, procure o nome ou ID do cliente do registro do aplicativo

   

   

   Depois que a função for selecionada, Revise + atribua-a .

Verificar atribuição de função

É possível ver uma atribuição de função configurada em Controle de acesso (IAM) > Atribuições de função.

O registro do aplicativo deve aparecer na lista junto com a função que você atribuiu a ele.

CLI

Use o comandoaz dt role-assignment create para atribuir a função (ela deverá ser executada por um usuário com permissões suficientes na assinatura do Azure). O comando exige que você passe o nome da função que deseja atribuir, o nome da instância dos Gêmeos Digitais do Azure e o nome ou a ID do objeto do registro do aplicativo.

az dt role-assignment create --dt-name <your-Azure-Digital-Twins-instance> --assignee "<name-or-ID-of-app-registration>" --role "<appropriate-role-name>"

O resultado desse comando mostrará informações geradas sobre uma atribuição de função criada para o registro do aplicativo.

Para verificar ainda mais a atribuição de função, você pode procurar por ela no portal do Azure (alterne para a guia instruções do Portal).

Fornecer permissões de API

Nesta seção, você concederá ao aplicativo permissões de leitura/gravação de linha de base do aplicativo às APIs dos Gêmeos Digitais do Azure.

Se você estiver usando a CLI do Azure e configurar seu registro de aplicativo anteriormente com um arquivo de manifesto, essa etapa já estará pronta. Se você estiver usando o portal do Azure para criar o registro do aplicativo, continue nesta seção para configurar as permissões de API.

Portal

Na página do portal do registro de aplicativo, selecione a opção Permissões de API no menu. Na página de permissões a seguir, selecione o botão + Adicionar uma permissão.

Na página Solicitar permissões de API exibida a seguir, mude para a guia APIs que minha organização usa e procure por Gêmeos Digitais do Azure. Selecione a opção Gêmeos Digitais do Azure nos resultados da pesquisa a fim de continuar com a atribuição de permissões para as APIs dos Gêmeos Digitais do Azure.

Observação

Caso sua assinatura ainda tenha uma instância existente dos Gêmeos Digitais do Azure da versão prévia pública anterior ao serviço (antes de julho de 2020), será preciso pesquisar e selecionar o Serviço de Espaços Inteligentes do Azure como alternativa. Esse é um nome anterior do mesmo conjunto de APIs (observe que a ID de aplicativo (cliente) é igual à captura de tela acima). Além disso, sua experiência não será alterada além desta etapa.

Depois, será preciso selecionar quais permissões conceder a essas APIs. Expanda a permissão Leitura (1) e marque a caixa que exibe a opção Leitura/Gravação para conceder a esse registro de aplicativo permissões de leitura e gravação de registro.

Clique em Adicionar permissões após a conclusão.

Verifique as Permissões de API

Na página Permissões de API, verifique se agora há uma entrada para os Gêmeos Digitais do Azure representando as permissões de Leitura/Gravação:

Também é possível verificar se a conexão com os Gêmeos Digitais do Azure está no arquivo manifest.json do registro de aplicativo, que foi atualizado de modo automático com as informações dos Gêmeos Digitais do Azure quando você adicionou as permissões de API.

Para fazer isso, selecione a opção Manifesto na barra de menus para ver o código do manifesto do registro de aplicativo. Role até a parte inferior da janela de código e procure os seguintes campos e valores em requiredResourceAccess:

• "resourceAppId": "0b07f429-9f4b-4714-9392-cc5e8e80c8b0"
• "resourceAccess" > "id": "4589bd03-58cb-4e6c-b17f-b580e39652f8"

Esses valores são mostrados na captura de tela abaixo:

Caso esses valores estejam ausentes, repita as etapas da seção criada para adicionar a permissão de API.

CLI

Se estiver usando a CLI, as permissões de API foram configuradas anteriormente como parte da etapa Criar o registro.

Você pode verificá-los agora usando o portal do Azure (alternar para a guia Instruções do portal).

Outras etapas possíveis para sua organização

É possível que sua organização precise de ações adicionais de proprietários ou administradores de assinatura para concluir a configuração do registro de aplicativo. As etapas necessárias podem variar dependendo das configurações específicas da organização. Escolha uma guia abaixo para que essas informações sejam adaptadas à interface de preferência.

Portal

Aqui, temos algumas atividades comuns que um proprietário ou administrador da assinatura poderá ter que fazer. Essas e outras operações podem ser executadas na página de registros do Aplicativo Microsoft Entra no portal do Azure.

• Conceda consentimento do administrador para o registro do aplicativo. Sua organização pode ter o Consentimento de Administrador Necessário globalmente ativado na ID do Microsoft Entra para todos os registros de aplicativos em sua assinatura. Nesse caso, o proprietário/administrador precisará clicar neste botão na página de permissões de API do registro de aplicativo a fim de validar o registro de aplicativo para sua empresa:

  

  • Caso o consentimento seja fornecido com êxito, a entrada para os Gêmeos Digitais do Azure deverá mostrar um valor de Status da opção Fornecido para (sua empresa)

  

• Ativar o acesso de cliente público

• Definir URLs de resposta específicas para obter acesso à Web e à área de trabalho

• Permitir fluxos de autenticação implícitos do OAuth2

CLI

Aqui, temos algumas atividades comuns que um proprietário ou administrador da assinatura poderá ter que fazer.

• Conceda consentimento do administrador para o registro do aplicativo. Sua organização pode ter o Consentimento de Administrador Necessário globalmente ativado na ID do Microsoft Entra para todos os registros de aplicativos em sua assinatura. Nesse caso, o proprietário/administrador pode precisar conceder permissões adicionais delegadas ou de aplicativo.
• Ative o acesso de cliente público anexando --set publicClient=true a um comando criar ou atualizar para o registro.
• Defina URLs de resposta específicas para obter acesso à Web e à área de trabalho usando o parâmetro --reply-urls. Para obter mais informações sobre como usar esse parâmetro com comandos az ad, veja a documentação do az ad app.
• Permita fluxos de autenticação OAuth2 implícitos usando o parâmetro --oauth2-allow-implicit-flow. Para obter mais informações sobre como usar esse parâmetro com comandos az ad, veja a documentação do az ad app.

Para obter mais informações sobre o registro de aplicativo e as diferentes opções de configuração, confira como Registrar um aplicativo na plataforma de identidade da Microsoft.

Próximas etapas

Neste artigo, você configura um registro de aplicativo do Microsoft Entra que pode ser usado para autenticar aplicativos cliente com as APIs do Gêmeos Digitais do Azure.

Em seguida, leia informações sobre os mecanismos de autenticação, incluindo um que usa Registros de aplicativo e outros que não usam:

• Escrever código de autenticação do aplicativo