Acessar a API dos Serviços de Mídia do Azure com a autenticação do Azure AD

logotipo dos Serviços de Mídia


Observação

Atualize os SDKs e a API REST de Serviços de Mídia do Azure para a v3 até 29 de fevereiro de 2024. A versão 3 da API REST de Serviços de Mídia do Azure e dos SDKs de cliente para .NET e Java oferece mais funcionalidades do que a versão 2. Estamos desativando a versão 2 da API REST de Serviços de Mídia do Azure e dos SDKs de cliente para .NET e Java.

Ação necessária: para minimizar a interrupção nas suas cargas de trabalho, examine o guia de migração para fazer a transição do código da API e dos SDKs da versão 2 para a API e o SDK da versão 3 antes de 29 de fevereiro de 2024. Após 29 de fevereiro de 2024, os Serviços de Mídia do Azure deixarão de aceitar o tráfego na API REST da versão 2, na API de gerenciamento de contas do ARM versão 2015-10-01 ou nos SDKs de cliente .NET da versão 2. Isso inclui todos os SDKS de cliente de código aberto de terceiros que possam chamar a API da versão 2. Saiba mais sobre a última versão, começando com a Visão geral dos Serviços de Mídia v3.

A API dos Serviços de Mídia do Azure é uma API RESTful. Você pode usá-la para executar operações em recursos de mídia usando uma API REST ou os SDKs de cliente disponíveis. Os Serviços de Mídia do Azure oferecem um SDK de cliente dos Serviços de Mídia para o Microsoft .NET. Para estar autorizado a acessar os recursos e a API dos Serviços de Mídia, primeiro você deve ser autenticado.

Os Serviços de Mídia dão suporte à autenticação baseada no Azure AD (Azure Active Directory). O serviço REST de Mídia do Azure exige que o usuário ou o aplicativo que faz as solicitações da API REST tenha a função Colaborador ou Proprietário para acessar os recursos. Para saber mais, veja O que é o RBAC (controle de acesso baseado em função) do Azure.

Este documento fornece uma visão geral de como acessar a API dos Serviços de Mídia usando as APIs REST ou as APIs do .NET.

Observação

A autorização de Controle de Acesso foi preterida em 1º de junho de 2018.

Controle de acesso

Para que a solicitação REST da Mídia do Azure seja bem-sucedida, o usuário chamador deve ter uma função Colaborador ou Proprietário na conta dos Serviços de Mídia que ele está tentando acessar.
Somente um usuário com a função Proprietário pode conceder acesso (conta) aos recursos de mídia para novos usuários ou aplicativos. A função Colaborador pode acessar somente o recurso de mídia. Solicitações não autorizadas falham, com o código de status 401. Se você receber esse código de erro, verifique se o usuário tem a função Colaborador ou Proprietário atribuída à conta dos Serviços de Mídia do usuário. Verifique isso no portal do Azure. Pesquise sua conta de mídia e, em seguida, clique na guia Controle de acesso.

Guia Controle de acesso

Tipos de autenticação

Quando você usar a autenticação do AD Azure com Serviços de Mídia do Azure haverá duas opções de autenticação:

  • Autenticação do usuário. Autentica uma pessoa que está usando o aplicativo para interagir com os recursos dos Serviços de Mídia. O aplicativo interativo deve primeiro solicitar ao usuário as credenciais do usuário. Um exemplo é um aplicativo de console de gerenciamento usado por usuários autorizados para monitorar trabalhos de codificação ou uma transmissão ao vivo.
  • Autenticação de entidade de serviço. Autentica um serviço. Os aplicativos que geralmente usam esse método de autenticação são aplicativos que executam serviços daemon, serviços de camada intermediária ou trabalhos agendados. Entre os exemplos estão aplicativos Web, aplicativos de funções, aplicativos lógicos, APIs e microsserviços.

Autenticação de usuário

Os aplicativos que devem usar o método de autenticação de usuário são aplicativos nativos de gerenciamento ou monitoramento: aplicativos móveis, aplicativos do Windows e aplicativos de Console. Esse tipo de solução é útil quando você deseja proporcionar interação humana com o serviço em um dos seguintes cenários:

  • Painel de monitoramento dos trabalhos de codificação.
  • Painel de monitoramento dos fluxos ao vivo.
  • Aplicativo de gerenciamento para usuários móveis ou da área de trabalho administrarem os recursos em uma conta dos Serviços de Mídia.

Observação

Esse método de autenticação não deve ser usado para aplicativos voltados para o consumidor.

Um aplicativo nativo deve primeiro adquirir um token de acesso do Azure AD e, em seguida, usá-lo ao fazer solicitações HTTP para a API REST dos Serviços de Mídia. Adicione o token de acesso ao cabeçalho da solicitação.

O seguinte diagrama mostra um fluxo típico de autenticação de aplicativo interativo:

Diagrama de aplicativos nativos

No diagrama anterior, os números representam o fluxo das solicitações em ordem cronológica.

Observação

Quando você usa o método de autenticação de usuário, todos os aplicativos compartilham a mesma ID do cliente do aplicativo nativo (padrão) e o mesmo URI de redirecionamento do aplicativo nativo.

  1. Solicite as credenciais a um usuário.

  2. Solicite um token de acesso do Azure AD com os seguintes parâmetros:

    • Ponto de extremidade do locatário do Azure AD.

      As informações do locatário podem ser recuperadas no portal do Azure. Coloque o cursor sobre o nome do usuário conectado no canto superior direito.

    • URI de recurso dos Serviços de Mídia.

      Esse URI é o mesmo das contas dos Serviços de Mídia que estão no mesmo ambiente do Azure (por exemplo, https://rest.media.azure.net).

    • ID do cliente do aplicativo (nativo) dos Serviços de Mídia.

    • URI de redirecionamento do aplicativo (nativo) dos Serviços de Mídia.

    • URI de recurso dos Serviços de Mídia REST.

      O URI representa o ponto de extremidade da API REST (por exemplo, https://test03.restv2.westus.media.azure.net/api/).

      Para obter valores para esses parâmetros, consulte Usar o portal do Azure para acessar as configurações de autenticação do Azure AD usando a opção de autenticação de usuário.

  3. O token de acesso do Azure AD é enviado ao cliente.

  4. O cliente envia uma solicitação para a API REST da Mídia do Azure com o token de acesso do Azure AD.

  5. O cliente recebe novamente os dados dos Serviços de Mídia.

Para obter informações sobre como usar a autenticação do Azure AD para se comunicar com solicitações REST usando o SDK de cliente do .NET dos Serviços de Mídia, consulte Usar a autenticação do Azure AD para acessar a API dos Serviços de Mídia com o .NET.

Se você não estiver usando o SDK de cliente do .NET dos Serviços de Mídia, deverá criar manualmente uma solicitação de token de acesso do Azure AD usando os parâmetros descritos na etapa 2. Para obter mais informações, consulte Como usar a Biblioteca de Autenticação do Azure AD para obter o token do Azure AD.

Autenticação de entidade de serviço

Os aplicativos que geralmente usam esse método de autenticação são aplicativos que executam serviços de camada intermediária e trabalhos agendados: aplicativos Web, aplicativos de funções, aplicativos lógicos, APIs e microsserviços. Esse método de autenticação também é adequado para aplicativos interativos nos quais você talvez deseje usar uma conta de serviço para gerenciar os recursos.

Quando você usa o método de autenticação de entidade de serviço para criar cenários de consumidor, a autenticação normalmente é manipulada na camada intermediária (por meio de alguma API) e não diretamente em um aplicativo móvel ou da área de trabalho.

Para usar esse método, crie um aplicativo e uma entidade de serviço do Azure AD em seu próprio locatário. Depois de criar o aplicativo, conceda o acesso da função de Colaborador ou Proprietário ao aplicativo à conta dos Serviços de Mídia. Você pode fazer isso no portal do Azure, usando a CLI do Azure ou com um script do PowerShell. Use também um aplicativo existente do Azure AD. Registre e gerencie o aplicativo e a entidade de serviço do Azure AD no portal do Azure. Também faça isso usando a CLI do Azure ou o PowerShell.

Aplicativos de camada intermediária

Depois de criar o aplicativo do Azure AD, você obtém valores para as configurações a seguir. Você precisa destes valores para autenticação:

  • ID do Cliente
  • Segredo do cliente

Na figura anterior, os números representam o fluxo das solicitações em ordem cronológica:

  1. Um aplicativo de camada intermediária (API Web ou aplicativo Web) solicita um token de acesso do Azure AD que tem os seguintes parâmetros:

    • Ponto de extremidade do locatário do Azure AD.

      As informações do locatário podem ser recuperadas no portal do Azure. Coloque o cursor sobre o nome do usuário conectado no canto superior direito.

    • URI de recurso dos Serviços de Mídia.

      Esse URI é o mesmo das contas dos Serviços de Mídia que estão localizadas no mesmo ambiente do Azure (por exemplo, https://rest.media.azure.net).

    • URI de recurso dos Serviços de Mídia REST.

      O URI representa o ponto de extremidade da API REST (por exemplo, https://test03.restv2.westus.media.azure.net/api/).

    • Valores do aplicativo do Azure AD: a ID do cliente e o segredo do cliente.

      Para obter valores para esses parâmetros, consulte Usar o portal do Azure para acessar as configurações de autenticação do Azure AD usando a opção de autenticação de entidade de serviço.

  2. O token de acesso do Azure AD é enviado à camada intermediária.

  3. A camada intermediária envia a solicitação à API REST da Mídia do Azure com o token do Azure AD.

  4. A camada intermediária obtém novamente os dados dos Serviços de Mídia.

Para obter mais informações sobre como usar a autenticação do Azure AD para se comunicar com solicitações REST usando o SDK de cliente do .NET dos Serviços de Mídia, consulte Usar a autenticação do Azure AD para acessar a API dos Serviços de Mídia do Azure com o .NET.

Se você não estiver usando o SDK de cliente do .NET dos Serviços de Mídia, deverá criar manualmente uma solicitação de token do Azure AD usando os parâmetros descritos na etapa 1. Para obter mais informações, consulte Como usar a Biblioteca de Autenticação do Azure AD para obter o token do Azure AD.

Solução de problemas

Exceção: “O servidor remoto retornou um erro: (401) Não autorizado”.

Solução: para que a solicitação REST dos Serviços de Mídia seja bem-sucedida, o usuário chamador deve ter uma função Colaborador ou Proprietário na conta dos Serviços de Mídia que ele está tentando acessar. Para obter mais informações, consulte a seção Controle de acesso.

Recursos

Os seguintes artigos são visões gerais dos conceitos de autenticação do Azure AD:

Próximas etapas