Autorizar o acesso a APIs com a Biblioteca de Autenticação da Microsoft

  • 5 minutos

Agora, você pode conectar os usuários de sua empresa ao aplicativo Web. Em seguida, você deseja exibir informações como o cargo, o email de trabalho e assim por diante do perfil do funcionário na página. Você descobre que a API do Microsoft Graph fornece acesso a dados relacionados ao usuário.

Nesta unidade, você aprenderá como a MSAL pode ajudar você a obter acesso autorizado aos serviços da Microsoft, como a API do Microsoft Graph.

Permissões e escopos da API

Os serviços Web protegidos pelo Microsoft Entra ID definem um conjunto de permissões que fornecem acesso à funcionalidade da API e aos dados expostos pelo serviço. Um aplicativo pode solicitar essas permissões de usuários e administradores, que devem aprovar a solicitação antes que o aplicativo possa acessar dados ou agir em nome do usuário. Por exemplo, o Microsoft Graph definiu permissões para realizar as seguintes tarefas, entre outras:

  • Ler o calendário de um usuário
  • Escrever no calendário de um usuário
  • Enviar email como um usuário

Usuários e administradores podem exercer controle e saber quais dados o aplicativo pode acessar. Antes que seu aplicativo possa acessar uma API protegida pela Microsoft, você precisará fornecer a ele as permissões de aplicativo para executar as ações.

O Microsoft Entra ID dá suporte a dois tipos de permissões: permissões delegadas e permissões de aplicativo.

  • Permissões delegadas são usadas por aplicativos que têm um usuário conectado presente. Para esses aplicativos, o usuário ou um administrador consente com as permissões que o aplicativo solicita. É delegada ao aplicativo permissão para atuar como o usuário conectado quando ele faz chamadas à API de destino. Algumas permissões com privilégios elevados exigem o consentimento do administrador.

  • Permissões de aplicativo são usadas por aplicativos executados sem um usuário conectado presente, por exemplo, aplicativos executados como serviços em segundo plano ou daemons. Somente um administrador pode consentir as permissões do aplicativo.

Você pode atribuir estas permissões de API ao registro do aplicativo no portal do Azure.

Escopos

O Microsoft Entra ID implementa o protocolo de autorização OAuth 2.0, por meio do qual um aplicativo pode acessar recursos hospedados na Web em nome do usuário.

No OAuth 2.0, esses tipos de conjuntos de permissão são chamados de escopos. Ao fazer uma solicitação de autorização para o Microsoft Entra ID, um aplicativo solicita as permissões necessárias especificando a permissão no parâmetro de consulta scope da solicitação. Por exemplo, o valor de escopo https://graph.microsoft.com/Calendars.Read é usado para solicitar permissão para ler os calendários do usuário no Microsoft Graph.

Adquirir tokens de acesso com a MSAL

Tokens de acesso permitem que os aplicativos cliente chamem com segurança APIs Web protegidas pelo Microsoft Entra ID. Há várias maneiras de adquirir um token de acesso usando a MSAL (Biblioteca de Autenticação da Microsoft). Em geral, o método usado para adquirir um token depende de o aplicativo ser um aplicativo cliente público, como um aplicativo móvel ou de área de trabalho, ou um aplicativo cliente confidencial, como um aplicativo Web, de API Web ou um aplicativo daemon.

Vários dos métodos de aquisição de token da MSAL exigem um parâmetro scopes, que é uma lista de cadeias de caracteres que declaram as permissões desejadas e os recursos solicitados.

A MSAL armazena um token em cache após sua aquisição. Para aplicativos Web que usam o fluxo de código de autorização do OpenID Connect, o padrão recomendado nos controladores é:

  • Primeiro, tente obter um token silenciosamente do cache antes de tentar adquirir um token por outros meios. O código a seguir é um trecho da implementação do método acquireTokenSilently na classe AuthHelper.

    final SilentParameters parameters = SilentParameters
                                        .builder(Collections.singleton(Config.SCOPES), context.getAccount())
                                        .build();

final ConfidentialClientApplication client = getConfidentialClientInstance();

client.tokenCache().deserialize(context.getTokenCache());

final IAuthenticationResult result = client.acquireTokenSilently(parameters).get();

  • Se não houver nenhum token no cache e a solicitação de token silencioso falhar ao obter um token, você poderá adquirir o token usando o fluxo de código de autorização:

    final AuthorizationCodeParameters authParams = AuthorizationCodeParameters
                                                    .builder(authCode, new URI(Config.REDIRECT_URI)).scopes(Collections.singleton(Config.SCOPES))
                                                    .build();

final IAuthenticationResult result = app.acquireToken(authParams).get();

A MSAL também pode atualizar o token quando ele está próximo de expirar (pois o cache de token também contém um token de atualização).

Resultados da autenticação

Quando seu cliente solicita um token de acesso, o Microsoft Entra ID também retorna um resultado da autenticação que inclui metadados sobre o token de acesso. Esses dados permitem ao aplicativo realizar o cache inteligente dos tokens de acesso sem precisar analisar o token de acesso em si. Os resultados AuthenticationResult da MSAL expõem:

  • O token de acesso da API Web.
  • O token de ID do usuário (um JWT).
  • A expiração do token, que informa a data/hora da expiração do token.
  • A ID do locatário contém o locatário no qual o usuário foi encontrado.
  • Os escopos para os quais o token foi emitido.
  • A ID exclusiva para o usuário.

Introdução ao Microsoft Graph

A API do Microsoft Graph oferece apenas um ponto de extremidade, https://graph.microsoft.com, para fornecer acesso a dados e insights ricos e centrados em pessoas na nuvem da Microsoft. Você pode usar APIs REST ou SDKs para acessar o ponto de extremidade e criar aplicativos com suporte para cenários do Microsoft 365, abrangendo produtividade, colaboração, educação, inteligência de pessoas e local de trabalho e muito mais. O Microsoft Graph também inclui um conjunto poderoso de serviços que gerenciam a identidade do usuário e do dispositivo.

Por exemplo, você pode ler as propriedades de um usuário conectado acessando o ponto de extremidade https://graph.microsoft.com/v1.0/me.