Criar um registo de aplicação para utilizar com os Gêmeos Digitais do Azure

Este artigo descreve como criar um registro de aplicativo Microsoft Entra ID que pode acessar o Azure Digital Twins. 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 sua instância por meio de aplicativos cliente. Esses aplicativos precisam se autenticar com os Gêmeos Digitais do Azure, e alguns dos mecanismos de autenticação que os aplicativos podem usar envolvem um registro de aplicativo.

O registro do aplicativo não é necessário para todos os cenários de autenticação. No entanto, se você estiver usando uma estratégia de autenticação ou exemplo de código que exija um registro de aplicativo, este artigo mostra como configurar um e conceder permissões para as APIs do Azure Digital Twins. Ele também aborda como coletar valores importantes que você precisará usar o registro do aplicativo ao autenticar.

Gorjeta

Você pode preferir configurar um novo registro de aplicativo sempre que precisar de um, ou fazer isso apenas uma vez, estabelecendo um único registro de aplicativo que será compartilhado entre todos os cenários que o exigirem.

Criar o registo

Comece selecionando a guia abaixo para sua interface preferida.

Portal

Navegue até Microsoft Entra ID no portal do Azure (você pode usar este link ou encontrá-lo com a barra de pesquisa do portal). Selecione Registos de aplicações no menu de serviço e, em seguida , + Novo registo.

Na página Registar uma candidatura que se segue, preencha os valores solicitados:

• Nome: Um nome de exibição do aplicativo Microsoft Entra para associar ao registro.
• Tipos de conta suportados: Selecione Contas somente neste diretório organizacional (Somente diretório padrão - Locatário único).

Quando terminar, selecione o botão Registrar .

Quando o registo estiver concluído, o portal irá redirecioná-lo para a sua página de detalhes.

CLI

Comece criando um arquivo de manifesto, que contém informações de serviço que o registro do seu aplicativo precisará para acessar as APIs do Azure Digital Twins. Depois, você passará esse arquivo para um comando da CLI para criar o registro.

Crie o manifesto.

Crie um novo arquivo de .json no seu computador chamado manifest.json. Copie este texto para o arquivo:

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

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

Salve o arquivo concluído.

Usuários do Cloud Shell: Carregar manifesto

Se você estiver usando o Azure Cloud Shell para este tutorial, precisará carregar o arquivo de manifesto criado para o Cloud Shell, para que possa acessá-lo nos comandos do Cloud Shell ao configurar o registro do aplicativo. Se estiver a utilizar uma instalação local da CLI do Azure, pode avançar para o passo seguinte, Executar o comando de criação.

Para carregar o arquivo, vá para a janela do Cloud Shell no navegador. Selecione o ícone "Upload/Download de arquivos" e escolha "Upload".

Navegue até o arquivo manifest.json em sua máquina e selecione Abrir. Isso fará o upload do arquivo para a raiz do seu armazenamento do Cloud Shell.

Execute 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 da sua escolha
• Disponível apenas para contas no diretório padrão (locatário único)
• Um URL de resposta da Web de http://localhost
• Permissões de leitura/gravação para as APIs do Azure Digital Twins

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

az ad app create --display-name <app-registration-name> --sign-in-audience AzureADMyOrg --required-resource-accesses "manifest.json"

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

Verificar o sucesso

Você pode confirmar que as permissões do Azure Digital Twins foram concedidas procurando os seguintes campos na saída do comando creation, em requiredResourceAccess. Confirme se seus valores correspondem ao que está listado abaixo.

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

Recolher valores importantes

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

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

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

Coletar ID do cliente e ID do locatário

Para usar o registro do 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 salvá-los e usá-los sempre que necessário.

Portal

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

Anote o ID do aplicativo (cliente) e o ID do diretório (locatário) mostrados na sua página.

CLI

Você pode encontrar o ID do aplicativo na saída do az ad app create comando que executou anteriormente (ou exibir as informações novamente usando az ad app show).

appId Procure no resultado:

Você pode exibir seu ID de locatário no shell usando o comando az account tenant list .

Nota

Este grupo de comando é experimental e está atualmente em desenvolvimento.

Coletar segredo do cliente

Configure um segredo de cliente para o registro do seu aplicativo, que outros aplicativos podem usar para autenticar por meio dele.

Portal

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

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

   

2. Insira os valores desejados para Descrição e Expira e selecione Adicionar.

   

3. Verifique se o segredo do cliente está visível na página Certificados & segredos com os campos Expira e Valor.

4. Anote seu ID Secreto e Valor para usar mais tarde (você também pode copiá-los para a área de transferência com os ícones Copiar).

   

Importante

Certifique-se de copiar os valores agora e armazená-los em um local seguro, pois eles não podem ser recuperados novamente. Se não conseguir encontrá-los mais tarde, terá de criar um novo segredo.

CLI

Para criar um segredo de cliente para o registro do aplicativo, você precisará do valor da ID do cliente do registro do aplicativo coletado na etapa anterior. Use o valor no seguinte comando da CLI para criar um novo 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, data de término e outros detalhes. Para obter mais informações sobre o comando e seus parâmetros, consulte a documentação de redefinição de credenciais do aplicativo az ad.

A saída deste comando são informações sobre o segredo do cliente que você criou.

Copie o valor para password usar quando precisar do segredo do cliente para autenticação.

Importante

Certifique-se de copiar o valor agora e armazená-lo em um local seguro, pois ele não pode ser recuperado novamente. Se não conseguir encontrar o valor mais tarde, terá de criar um novo segredo.

Fornecer permissões do Azure Digital Twins

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

• Uma atribuição de função para o registro do aplicativo na instância do Azure Digital Twins
• Permissões de API para o aplicativo ler e gravar nas APIs do Azure Digital Twins

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 Azure Digital Twins. 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 de Dados do Azure Digital Twins. Para obter uma lista completa de funções e suas descrições, consulte Funções internas do Azure.

Portal

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

1. Abra a página da sua instância do Azure Digital Twins no portal do Azure.

2. Selecione Controlo de acesso (IAM) .

3. Selecione Adicionar>Adicionar atribuição de funções para abrir o painel Adicionar atribuição de funções.

4. Atribua a função apropriada. Para obter os passos detalhados, veja o artigo Atribuir funções do Azure com o portal do Azure.

   Definição	Value
   Role	Selecione conforme apropriado
   Membros > Atribuir acesso a	Usuário, grupo ou entidade de serviço
   Membros > Membros	+ Selecione membros e, em seguida, procure o nome do registo da aplicação

   

   

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

Verificar atribuição de função

Você pode exibir a atribuição de função que configurou em Atribuições de função de controle de acesso (IAM). >

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

CLI

Use o comando az dt role-assignment create para atribuir a função (ela deve 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 sua instância do Azure Digital Twins 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 são informações geradas sobre a atribuição de função que foi criada para o registro do aplicativo.

Para verificar ainda mais a atribuição de função, você pode procurá-la no portal do Azure (alterne para a guia Instruções do Portal).

Fornecer permissões de API

Nesta seção, você concederá à linha de base do seu aplicativo permissões de leitura/gravação para as APIs do Azure Digital Twins.

Se você estiver usando a CLI do Azure e configurar o registro do aplicativo anteriormente com um arquivo de manifesto, esta etapa já está concluída. Se você estiver usando o portal do Azure para criar seu registro de aplicativo, continue pelo restante desta seção para configurar as permissões de API.

Portal

Na página do portal para o registro do seu aplicativo, selecione 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 da API a seguir, alterne para a guia APIs que minha organização usa e pesquise gêmeos digitais do Azure. Selecione Gêmeos Digitais do Azure nos resultados da pesquisa para continuar com a atribuição de permissões para as APIs dos Gêmeos Digitais do Azure.

Nota

Se a sua subscrição ainda tiver uma instância existente do Azure Digital Twins da pré-visualização pública anterior do serviço (antes de julho de 2020), terá de procurar e selecionar o Serviço Azure Smart Spaces. Este é um nome antigo para o mesmo conjunto de APIs (observe que o ID do aplicativo (cliente) é o mesmo da captura de tela acima) e sua experiência não será alterada além desta etapa.

Em seguida, você selecionará quais permissões conceder para essas APIs. Expanda a permissão Ler (1) e marque a caixa que diz Read.Write para conceder permissões de leitor e gravador de registro a este aplicativo.

Selecione Adicionar permissões quando terminar.

Verificar permissões de API

Na página de permissões da API, verifique se agora há uma entrada para Gêmeos Digitais do Azure refletindo as permissões Read.Write:

Você também pode verificar a conexão com os Gêmeos Digitais do Azure no manifest.json de registro do aplicativo, que foi atualizado automaticamente com as informações dos Gêmeos Digitais do Azure quando você adicionou as permissões da API.

Para fazer isso, selecione Manifesto no menu para exibir o código de manifesto do registro do aplicativo. Desloque-se para 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:

Se esses valores estiverem faltando, repita as etapas na seção para adicionar a permissão da API.

CLI

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

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

Outros passos possíveis para a sua organização

É possível que sua organização exija mais ações dos proprietários ou administradores da assinatura para concluir a configuração do registro do aplicativo. Os passos necessários podem variar consoante as configurações específicas da sua organização. Escolha uma guia abaixo para ver essas informações adaptadas à sua interface preferida.

Portal

Aqui estão algumas atividades potenciais comuns que um proprietário ou administrador na assinatura pode precisar 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 registo da aplicação. 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. Em caso afirmativo, o proprietário/administrador terá de selecionar este botão para a sua empresa na página de permissões da API de registo da aplicação para que o registo da aplicação seja válido:

  

  • Se o consentimento tiver sido concedido com êxito, a entrada para Gêmeos Digitais do Azure deverá mostrar um valor de Status de Concedido para (sua empresa)

  

• Ativar acesso de cliente público

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

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

CLI

Aqui estão algumas atividades potenciais comuns que um proprietário ou administrador na assinatura pode precisar fazer.

• Conceda consentimento do administrador para o registo da aplicação. 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. Em caso afirmativo, o proprietário/administrador pode precisar conceder permissões delegadas ou de aplicativo adicionais.
• Ative o acesso público do cliente anexando --set publicClient=true a um comando create ou update para o registro.
• Defina URLs de resposta específicas para acesso à Web e à área de trabalho usando o --reply-urls parâmetro. Para obter mais informações sobre como usar esse parâmetro com az ad comandos, consulte a documentação do aplicativo az ad.
• Permita fluxos de autenticação OAuth2 implícitos usando o --oauth2-allow-implicit-flow parâmetro. Para obter mais informações sobre como usar esse parâmetro com az ad comandos, consulte a documentação do aplicativo az ad.

Para obter mais informações sobre o registro de aplicativos e suas diferentes opções de configuração, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft.

Próximos passos

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

Em seguida, leia sobre mecanismos de autenticação, incluindo um que usa registros de aplicativo e outros que não usam:

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