Autenticação e autorização para API do Azure Time Series Insights

Nota

O serviço Time Series Insights (TSI) deixará de ser suportado após março de 2025. Ponderar, o mais rapidamente possível, a migração dos ambientes ETI existentes para soluções alternativas. Para obter mais informações sobre a substituição e migração, visite nossa documentação.

Dependendo das suas necessidades comerciais, a sua solução pode incluir uma ou mais aplicações cliente que utiliza para interagir com as APIs do seu ambiente do Azure Time Series Insights. O Azure Time Series Insights executa a autenticação usando os Tokens de Segurança do Microsoft Entra com base no OAUTH 2.0. Para autenticar o(s) seu(s) cliente(s), você precisará obter um token de portador com as permissões certas e passá-lo junto com suas chamadas de API. Este documento descreve vários métodos para obter credenciais que você pode usar para obter um token de portador e autenticar, incluindo o uso de identidade gerenciada e registro de aplicativo Microsoft Entra.

Identidades geridas

As seções a seguir descrevem como usar uma identidade gerenciada do Microsoft Entra ID para acessar a API do Azure Time Series Insights. No Azure, as identidades geridas eliminam a necessidade de os programadores terem de gerir credenciais ao fornecer uma identidade para o recurso do Azure no Microsoft Entra ID e ao utilizá-la para obter tokens do Microsoft Entra. Aqui estão alguns dos benefícios de usar identidades gerenciadas:

• Você não precisa gerenciar credenciais. As credenciais nem sequer estão acessíveis para si.
• Você pode usar identidades gerenciadas para autenticar em qualquer serviço do Azure que ofereça suporte à autenticação do Microsoft Entra, incluindo o Azure Key Vault.
• As identidades gerenciadas podem ser usadas sem qualquer custo adicional.

Para obter mais informações sobre os dois tipos de identidades gerenciadas, leia O que são identidades gerenciadas para recursos do Azure?

Você pode usar identidades gerenciadas de:

• VMs do Azure
• Serviços de Aplicações do Azure
• Funções do Azure
• Instâncias de contêiner do Azure
• e mais...

Consulte Serviços do Azure que dão suporte a identidades gerenciadas para recursos do Azure para obter a lista completa.

Registo da aplicação Microsoft Entra

Recomendamos o uso de identidades gerenciadas sempre que possível para que você não precise gerenciar credenciais. Se seu aplicativo cliente não estiver hospedado em um serviço do Azure que ofereça suporte a identidades gerenciadas, você poderá registrar seu aplicativo com um locatário do Microsoft Entra. Ao registrar seu aplicativo com o Microsoft Entra ID, você está criando uma configuração de identidade para seu aplicativo que permite que ele se integre ao Microsoft Entra ID. Ao registrar um aplicativo no portal do Azure, você escolhe se ele é um único locatário (acessível apenas em seu locatário) ou multilocatário (acessível em outros locatários) e, opcionalmente, pode definir um URI de redirecionamento (para onde o token de acesso é enviado).

Depois de concluir o registro do aplicativo, você terá uma instância globalmente exclusiva do aplicativo (o objeto do aplicativo) que reside dentro do seu locatário ou diretório residencial. Você também tem uma ID globalmente exclusiva para seu aplicativo (a ID do aplicativo ou do cliente). No portal, você pode adicionar segredos ou certificados e escopos para fazer seu aplicativo funcionar, personalizar a identidade visual do seu aplicativo na caixa de diálogo de entrada e muito mais.

Se você registrar um aplicativo no portal, um objeto de aplicativo, bem como um objeto principal de serviço serão criados automaticamente em seu locatário residencial. Se você registrar/criar um aplicativo usando as APIs do Microsoft Graph, a criação do objeto principal de serviço será uma etapa separada. Um objeto de entidade de serviço é necessário para solicitar tokens.

Certifique-se de revisar a lista de verificação de segurança do seu aplicativo. Como prática recomendada, você deve usar credenciais de certificado, não credenciais de senha (segredos de cliente).

Consulte Objetos principais de aplicativo e serviço no Microsoft Entra ID para obter mais detalhes.

Etapa 1: criar sua identidade gerenciada ou registro de aplicativo

Depois de identificar se você usará uma identidade gerenciada ou um registro de aplicativo, sua próxima etapa é provisionar um.

Identidade gerida

As etapas que você usará para criar uma identidade gerenciada variarão dependendo de onde seu código está localizado e se você está ou não criando uma identidade atribuída ao sistema ou ao usuário. Leia Tipos de identidade gerenciados para entender a diferença. Depois de selecionar o tipo de identidade, localize e siga o tutorial correto na documentação de identidades gerenciadas do Microsoft Entra. Lá você encontrará instruções sobre como configurar identidades gerenciadas para:

• Azure VMs
• Serviço de Aplicativo e Azure Functions
• Azure Container Instances
• e mais...

Registo de aplicação

Siga as etapas listadas em Registrar um aplicativo.

• Depois de selecionar a plataforma apropriada na etapa 4 de Configurar configurações da plataforma, configure seus URIs de redirecionamento e tokens de acesso no painel lateral à direita da interface do usuário.

  • Os URIs de redirecionamento devem corresponder ao endereço fornecido pela solicitação de autenticação:

    • Para aplicativos hospedados em um ambiente de desenvolvimento local, selecione Cliente público (móvel ou desktop). Certifique-se de definir o cliente público como Sim.
    • Para Aplicativos de Página Única hospedados no Serviço de Aplicativo do Azure, selecione Web.

  • Determine se um URL de Logout é apropriado.

  • Habilite o fluxo de concessão implícito marcando Tokens de acesso ou tokens de ID.

  

  Clique em Configurar e, em seguida, em Guardar.

• Associe seu aplicativo Microsoft Entra Azure Time Series Insights. Selecione Permissões>de API Adicione uma permissão>APIs que minha organização usa.

  

  Digite Azure Time Series Insights na barra de pesquisa e selecione Azure Time Series Insights.

• Em seguida, especifique o tipo de permissão de API que seu aplicativo exige. Por padrão, as permissões delegadas serão realçadas. Escolha um tipo de permissão e, em seguida, selecione Adicionar permissões.

  

• Adicione credenciais se o aplicativo estiver chamando as APIs do seu ambiente como ele mesmo. As credenciais permitem que seu aplicativo se autentique como ele mesmo, não exigindo nenhuma interação de um usuário em tempo de execução.

Etapa 2: Conceder acesso

Quando seu ambiente do Azure Time Series Insights recebe uma solicitação, primeiro o token de portador do chamador é validado. Se a validação for aprovada, o chamador foi autenticado e, em seguida, outra verificação será feita para garantir que o chamador esteja autorizado a executar a ação solicitada. Para autorizar qualquer usuário ou entidade de serviço, você deve primeiro conceder-lhes acesso ao ambiente, atribuindo-lhes a função de Leitor ou Colaborador.

• Para conceder acesso por meio da interface do usuário do portal do Azure, siga as instruções listadas no artigo Conceder acesso a dados a um ambiente. Ao selecionar o usuário, você pode pesquisar a identidade gerenciada ou o registro do aplicativo por seu nome ou por ID.

• Para conceder acesso usando a CLI do Azure, execute o seguinte comando. Consulte a documentação aqui para obter a lista completa de comandos disponíveis para gerenciar o acesso.

  az tsi access-policy create --name "ap1" --environment-name "env1" --description "some description" --principal-object-id "aGuid" --roles Reader Contributor --resource-group "rg1"
  

Nota

A extensão timeseriesinsights para CLI do Azure requer a versão 2.11.0 ou superior. A extensão será instalada automaticamente na primeira vez que você executar um comando az tsi access-policy. Saiba mais sobre extensões.

Etapa 3: Solicitando tokens

Depois que sua identidade gerenciada ou registro de aplicativo tiver sido provisionado e atribuído uma função, você estará pronto para começar a usá-lo para solicitar tokens de portador OAuth 2.0. O método que você usa para obter um token será diferente dependendo de onde seu código está hospedado e seu idioma de escolha. Ao especificar o recurso (também conhecido como "audiência" do token), você pode identificar o Azure Time Series Insights por sua URL ou GUID:

• https://api.timeseries.azure.com/
• 120d688d-1518-4cf7-bd38-182f158850b6

Importante

Se você usar a URL como ID do recurso, o token deverá ser emitido exatamente para https://api.timeseries.azure.com/. A barra à direita é necessária.

• Se estiver usando o Postman , sua AuthURL será: https://login.microsoftonline.com/microsoft.onmicrosoft.com/oauth2/authorize?scope=https://api.timeseries.azure.com//.default
• https://api.timeseries.azure.com/ é válido, mas https://api.timeseries.azure.com não é.

Identidades geridas

Ao acessar a partir do Serviço de Aplicativo do Azure ou do Functions, siga as orientações em Obter tokens para recursos do Azure.

Para aplicativos e funções .NET, a maneira mais simples de trabalhar com uma identidade gerenciada é por meio da biblioteca de cliente do Azure Identity para .NET. Esta biblioteca de cliente é popular devido à sua simplicidade e benefícios de segurança. Os desenvolvedores podem escrever código uma vez e permitir que a biblioteca do cliente determine como autenticar com base no ambiente do aplicativo - seja em uma estação de trabalho do desenvolvedor usando a conta de um desenvolvedor ou implantada no Azure usando uma identidade de serviço gerenciado. Para obter orientações de migração da biblioteca AppAuthentication predecessora, leia AppAuthentication to Azure.Identity Migration Guidance.

Solicite um token para o Azure Time Series Insights usando C# e a biblioteca de cliente do Azure Identity para .NET:

using Azure.Identity;
// ...
var credential = new DefaultAzureCredential();
var token = credential.GetToken(
new Azure.Core.TokenRequestContext(
    new[] { "https://api.timeseries.azure.com/" }));
var accessToken = token.Token;

Registo de aplicações

• Use a Biblioteca de Autenticação da Microsoft (MSAL) para obter tokens para registros de aplicativos.

O MSAL pode ser usado em muitos cenários de aplicativos, incluindo, mas não limitado a:

• Aplicativos de página única (JavaScript)
• Aplicativo Web entrando em um usuário e chamando uma API da Web em nome do usuário
• API Web chamando outra API Web downstream em nome do usuário conectado
• Aplicativo de desktop chamando uma API da Web em nome do usuário conectado
• Aplicativo móvel chamando uma API da Web em nome do usuário que está conectado interativamente.
• Aplicativo daemon de desktop/serviço chamando API da Web em nome próprio

Para obter um código C# de exemplo mostrando como adquirir um token como um registro de aplicativo e dados de consulta de um ambiente Gen2, exiba o aplicativo de exemplo no GitHub

Importante

Se você estiver usando a Biblioteca de Autenticação do Ative Directory do Azure (ADAL), migre para o MSAL.

Cabeçalhos e parâmetros comuns

Esta seção descreve cabeçalhos e parâmetros comuns de solicitação HTTP usados para fazer consultas nas APIs Gen1 e Gen2 do Azure Time Series Insights. Os requisitos específicos da API são abordados com mais detalhes na documentação de referência da API REST do Azure Time Series Insights.

Gorjeta

Leia a Referência da API REST do Azure para saber mais sobre como consumir APIs REST, fazer solicitações HTTP e lidar com respostas HTTP.

Cabeçalhos de HTTP

Os cabeçalhos de solicitação necessários são descritos abaixo.

Cabeçalho de solicitação obrigatório	Description
Autorização	Para autenticar com o Azure Time Series Insights, um token OAuth 2.0 Bearer válido deve ser passado no cabeçalho Authorization.

Gorjeta

Leia a visualização de exemplo do SDK do cliente Azure Time Series Insights hospedado para saber como autenticar com as APIs do Azure Time Series Insights programaticamente usando o SDK do Cliente JavaScript junto com gráficos e tabelas.

Os cabeçalhos de solicitação opcionais são descritos abaixo.

Cabeçalho de pedido opcional	Description
Tipo de conteúdo	apenas application/json é suportado.
ID DO X-MS-CLIENT-REQUEST-	Um ID de solicitação do cliente. O serviço registra esse valor. Permite que o serviço rastreie a operação entre serviços.
ID DE SESSÃO X-MS-CLIENT-	Um ID de sessão do cliente. O serviço registra esse valor. Permite que o serviço rastreie um grupo de operações relacionadas entre serviços.
x-ms-cliente-nome-da-aplicação	Nome do aplicativo que gerou essa solicitação. O serviço registra esse valor.

Os cabeçalhos de resposta opcionais, mas recomendados, são descritos abaixo.

Cabeçalho da resposta	Description
Tipo de conteúdo	Só o application/json é suportado.
ID DE SOLICITAÇÃO X-MS	ID de solicitação gerada pelo servidor. Pode ser usado para entrar em contato com a Microsoft para investigar uma solicitação.
x-ms-property-not-found-behavior	Cabeçalho de resposta opcional da API GA. Os valores possíveis são ThrowError (padrão) ou UseNull.

Parâmetros HTTP

Gorjeta

Encontre mais informações sobre informações de consulta obrigatórias e opcionais na documentação de referência.

Os parâmetros de cadeia de caracteres de consulta de URL necessários dependem da versão da API.

Versão	Valores de versão da API
Gen1	api-version=2016-12-12
Ger2	api-version=2020-07-31

Os parâmetros opcionais da cadeia de caracteres de consulta de URL incluem a definição de um tempo limite para os tempos de execução da solicitação HTTP.

Parâmetro de consulta opcional	Description	Versão
timeout=<timeout>	Tempo limite do lado do servidor para execução de solicitações HTTP. Aplicável apenas às APIs Get Environment Events e Get Environment Aggregates . O valor de tempo limite deve estar no formato de duração ISO 8601, por exemplo "PT20S" , e deve estar no intervalo 1-30 s. O valor predefinido é 30 s.	Gen1
storeType=<storeType>	Para ambientes Gen2 com armazenamento quente habilitado, a consulta pode ser executada WarmStore no ou ColdStore. Esse parâmetro na consulta define em qual armazenamento a consulta deve ser executada. Se não for definida, a consulta será executada no frigorífico. Para consultar o armazenamento quente, storeType precisa ser definido como WarmStore. Se não for definida, a consulta será executada no frigorífico.	Ger2

Próximos passos

• Para obter o código de exemplo que chama a API do Azure Time Series Insights Gen1, leia Query Gen1 data using C#.

• Para obter um código de exemplo que chama os exemplos de código da API Gen2 Azure Time Series Insights, leia Query Gen2 data using C#.

• Para obter informações de referência da API, leia a documentação de referência da API de consulta.