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

  • Artigo

Observação

O serviço TSI (Time Series Insights) não terá mais suporte após março de 2025. Considere migrar os ambientes existentes do TSI para soluções alternativas assim que possível. Para obter mais informações sobre a substituição e a migração, visite nossa documentação.

Dependendo das necessidades da sua empresa, sua solução pode incluir um ou mais aplicativos cliente usados para interagir com as APIsdo 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 SDK, você precisa obter um token de portador com as permissões corretas e transmiti-lo junto com suas chamadas à 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 gerenciadas

As seções a seguir descrevem como usar uma identidade gerenciada da ID do Microsoft Entra para acessar a API do Azure Time Series Insights. No Azure, as identidades gerenciadas eliminam a necessidade de os desenvolvedores precisarem gerenciar credenciais fornecendo uma identidade para o recurso do Azure no Microsoft Entra ID e a usando 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 você.
  • Você pode usar identidades gerenciadas para se autenticar em qualquer serviço do Azure que ofereça suporte à autenticação do Microsoft Entra, incluindo o Cofre de Chaves do Azure.
  • Identidades gerenciadas podem ser usadas sem nenhum 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 Aplicativo do Azure
  • Funções do Azure
  • Instâncias de Contêiner do Azure
  • e muito mais…

Veja a lista completa em Serviços do Azure que oferecem suporte a identidades gerenciadas para recursos do Azure.

Registro de aplicativo do Microsoft Entra

É recomendável usar 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 tem um locatário único (acessível somente em seu locatário) ou se é multilocatário (acessível em outros locatários), além de definir um URI de redirecionamento opcionalmente para receber o token de acesso.

Ao concluir o registro do aplicativo, você tem uma instância globalmente exclusiva dele (o objeto do aplicativo), que reside em seu diretório ou locatário inicial. Tem também uma ID globalmente exclusiva para o seu aplicativo (a ID do aplicativo ou do cliente). No portal, você pode adicionar segredos ou certificados e escopos para fazer seu aplicativo funcionar, além de personalizar a identidade visual dele na caixa de diálogo de conexão, entre outras ações.

Se você registrar um aplicativo no portal, serão criados automaticamente um objeto de aplicativo e um objeto de entidade de serviço no seu locatário inicial. Ao registrar/criar um aplicativo com as APIs do Microsoft Graph, há uma etapa separada para a criação do objeto da entidade de serviço. Para solicitar tokens, é necessário um objeto de entidade de serviço.

Certifique-se de conferir 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 do cliente).

Consulte Objetos de entidade de aplicativo e serviço na ID do Microsoft Entra para obter mais detalhes.

Etapa 1: Criar sua identidade gerenciada ou seu registro de aplicativo

Depois de identificar se você usará uma identidade gerenciada ou um registro de aplicativo, a próxima etapa será provisionar esse item.

Identidade gerenciada

As etapas de criação de uma identidade gerenciada variam segundo o local do código e o fato de você estar ou não criando uma identidade atribuída pelo sistema ou pelo usuário. Leia Tipos de identidade gerenciada para entender a diferença. Depois de selecionar seu 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:

Registro de aplicativo

Siga as etapas listadas em Registrar um aplicativo.

  • Depois de selecionar a plataforma apropriada na etapa 4 das configurações de Configurar 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 e desktop). Lembre-se de definir cliente público como Sim.
      • Para aplicativos de página única hospedados no Serviço de Aplicativo do Azure, selecione Web.

    • Determine se uma URL de logout é apropriada.

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

    Create Redirect URIs

    Clique em Configurar e Salvar.

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

    Associate an API with your Microsoft Entra app

    Digite Azure Time Series Insights na barra em seguida e selecione Azure Time Series Insights.

  • Em seguida, especifique o tipo de permissão de API exigido por seu aplicativo. Por padrão, Permissões delegadas estará realçado. Escolha um tipo de permissão e selecione Adicionar permissões.

    Specify the kind of API permission your app requires

  • Adicione credenciais se o aplicativo for chamar as APIs do seu ambiente como ele mesmo. As credenciais permitem que seu aplicativo se autentique como ele mesmo, sem nenhuma interação com um usuário no runtime.

Etapa 2: Conceder acesso

Quando seu ambiente do Azure Time Series Insights recebe uma solicitação, primeiramente o token de portador do chamador é validado. Se a validação for aprovada, significa que o chamador foi autenticado e será feita outra verificação para garantir que esse chamador esteja autorizado a executar a ação solicitada. Para autorizar qualquer usuário ou entidade de serviço, primeiro você deve conceder-lhes acesso ao ambiente, atribuindo-lhe 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 em um ambiente. Ao selecionar o usuário, você pode pesquisar a identidade gerenciada ou o registro do aplicativo por seu nome ou sua ID.

  • Para conceder acesso usando a CLI do Azure, execute o comando a seguir. Veja na documentação existente aqui 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"

Observação

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

Etapa 3: Solicitação de tokens

Depois que a identidade gerenciada ou o registro do aplicativo tiver sido provisionado e recebido uma função, você estará pronto para começar a usá-lo para solicitar tokens de portador OAuth 2.0. O método usado para obter um token varia, dependendo de onde seu código está hospedado e do idioma escolhido. 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 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 gerenciadas

Ao acessar do Serviço de Aplicativo do Azure ou do Functions, siga as orientações contidas 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 clientes de Identidade do Azure para .NET. Essa biblioteca de clientes é muito usada devido a seus benefícios de simplicidade e segurança. Os desenvolvedores podem escrever códigos uma vez e permitir que a biblioteca de clientes determine como autenticar com base no ambiente do aplicativo – seja em uma estação de trabalho de desenvolvedor usando a conta de um desenvolvedor ou implantado no Azure usando uma identidade de serviço gerenciada. Para obter diretrizes de migração da biblioteca predecessora AppAuthentication, leia Diretrizes de migração de AppAuthentication para Azure.Identity.

Solicite um token para o Azure Time Series Insights usando C# e a biblioteca de clientes de Identidade do Azure 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;

Registro do aplicativo

A MSAL pode ser usada em muitos cenários de aplicativos, inclusive estes:

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

Importante

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

Cabeçalhos e parâmetros comuns

Esta seção descreve cabeçalhos de solicitação HTTP e parâmetros comuns usados para fazer consultas nas APIs de 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.

Dica

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

Cabeçalhos HTTP

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

Cabeçalho de solicitação necessário Descrição
Autorização Para autenticar com o Azure Time Series Insights, é preciso transmitir um token de Portador OAuth 2.0 válido no Cabeçalho de autorização.

Dica

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

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

Cabeçalho de solicitação opcional Descrição
Content-type Apenas application/json tem suporte.
x-ms-client-request-id Uma ID de solicitação do cliente. O serviço registra esse valor. Permite que o serviço rastreie a operação entre serviços.
x-ms-client-session-id Uma 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-client-application-name Nome do aplicativo que gerou a solicitação. O serviço registra esse valor.

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

Cabeçalho de resposta Descrição
Content-type Apenas application/json tem suporte.
x-ms-request-id ID da solicitação gerada pelo servidor. Pode ser usada para contatar a Microsoft para investigar uma solicitação.
x-ms-property-not-found-behavior Cabeçalho de resposta opcional da API de GA. Os valores possíveis são ThrowError (padrão) ou UseNull.

Parâmetros HTTP

Dica

Saiba mais sobre as informações de consulta necessárias e opcionais na documentação de referência.

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

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

Os parâmetros opcionais de cadeia 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 Descrição Versão
timeout=<timeout> Tempo limite do lado do servidor para a execução da solicitação HTTP. Aplicável somente às APIs Obter Eventos de Ambiente e Obter Agregações de Ambiente. O valor do tempo limite deve estar no formato de duração ISO 8601, por exemplo, "PT20S" e deve estar no intervalo 1-30 s. O valor padrão é 30 s. Gen1
storeType=<storeType> Para ambientes de Gen2 com armazenamento warm habilitado, a consulta pode ser executada em WarmStore ou ColdStore. Esse parâmetro na consulta define em qual armazenamento a consulta deve ser executada. Se ele não estiver definido, a consulta será executada no armazenamento cold. Para consultar o armazenamento warm, storeType precisa ser definido como WarmStore. Se ele não estiver definido, a consulta será executada no armazenamento cold. Gen2

Próximas etapas