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

Observação

O serviço Time Series Insights será desativado em 7 de julho de 2024. Considere migrar os ambientes existentes para soluções alternativas o mais rápido possível. Para mais informações sobre a obsolescência e a migração, visite a nossa documentação .

Dependendo das suas necessidades empresariais, a sua solução pode incluir uma ou mais aplicações cliente utilizadas para interagir com as APIs de do seu ambiente do Azure Time Series Insights,. O Azure Time Series Insights executa a autenticação usando 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 gerenciadas

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 gerenciadas eliminam a necessidade de os desenvolvedores terem que gerenciar credenciais fornecendo uma identidade para o recurso do Azure na ID do Microsoft Entra e usando-a 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:

• Azure VMs
• Serviços de Aplicativo do Azure
• Azure Functions
• 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 é 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 Security para seu aplicativo. Como prática recomendada, você deve usar credenciais de certificado, não credenciais de senha (segredos do 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 gerenciada

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:

• Máquinas Virtuais do Azure
• Serviço de Aplicativo e Azure Functions
• Instâncias de Contêiner do Azure
• e mais...

Registo de candidaturas

Siga as etapas listadas em Registrar um aplicativo.

• Depois de selecionar a plataforma apropriada na etapa 4 de Configurar plataforma, configure os seus URIs de redirecionamento e os Tokens de acesso no painel lateral à direita da interface do utilizador.

  • 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 & desktop). Certifique-se de definir o cliente público como Sim.
    • Para Single-Page Aplicações hospedadas no Serviço de Aplicações do Azure, selecione Web.

  • Determine se uma URL de Logout é apropriada.

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

  

  Clique Configurare, em seguida, Guardar.

• Associe seu aplicativo Microsoft Entra Azure Time Series Insights. Selecione permissões de API>Adicionar 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, permissões delegadas serão realçadas. Escolha um tipo de permissão e, em seguida, selecione Adicionar permissões.

  

• Adicionar credenciais se a aplicação precisar chamar as APIs do seu ambiente por si própria. 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 utilizador do portal 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"
  

Observação

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 final é necessária.

• Se estiver usando Postman seu 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 a partir do Serviço de Aplicativo do Azure ou do Functions, siga as orientações no 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 para 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 na aplicação

• Use o Microsoft Authentication Library (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:

• Aplicações de página única (JavaScript)
• aplicação web fazendo login de um utilizador e chamando uma API web em nome do utilizador
• API Web chamando outra API Web downstream em nome do utilizador autenticado
• aplicativo da área de trabalho 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.
• Aplicação daemon de desktop/serviço que chama a API web em seu próprio nome

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

Importante

Se estiveres a usar a Biblioteca de Autenticação do Active Directory do Azure (ADAL), migra 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, .

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 obrigatório	Descrição
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.

Dica

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 juntamente com gráficos e tabelas.

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

Cabeçalho de solicitação opcional	Descrição
Tipo de conteúdo	apenas application/json é suportado.
ID DO CLIENTE 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	Descrição
Tipo de conteúdo	Apenas 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

Dica

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.

Lançamento	Valores de versão da API
Gen1	api-version=2016-12-12
Gen2	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	Descrição	Versão
timeout=<timeout>	Tempo limite do lado do servidor para execução de solicitações HTTP. Aplicável apenas às APIs Obter Eventos de Ambiente e Obter Agregados de Ambiente. 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 padrão é 30 s.	Gen1
storeType=<storeType>	Para ambientes Gen2 com armazenamento quente habilitado, a consulta pode ser executada no WarmStore 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 estiver definida, a consulta será executada no armazenamento a frio.	Gen2

Próximos passos

• Para obter um código de exemplo que chama a API Gen1 Azure Time Series Insights, leia Consultar dados Gen1 usando C#.

• Para consultar o código de exemplo que demonstra como chamar a 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 Query API .