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

  • 5 minutos

Agora você pode entrar nos usuários da sua empresa no aplicativo Web. Em seguida, você deseja exibir informações como cargo, e-mail profissional e assim por diante no perfil do funcionário na página. Você achar que a API do Microsoft Graph fornece acesso a dados relacionados ao usuário.

Nesta unidade, você aprenderá como a MSAL pode ajudá-lo 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 que o serviço expõe. 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 de um usuário. Como exemplo, o Microsoft Graph definiu permissões para executar as seguintes tarefas, entre outras:

  • Ler o calendário de um utilizador
  • Gravar no calendário de um usuário
  • Enviar e-mail como 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ê precisa fornecer as permissões do aplicativo para executar as ações.

O Microsoft Entra ID suporta dois tipos de permissões: permissões delegadas e permissões de aplicativos.

  • As permissões delegadas são utilizadas por aplicações que têm um utilizador com sessão iniciada presente. Para estas aplicações, o utilizador ou um administrador consentem as permissões solicitadas pela aplicação. O aplicativo recebe permissão delegada para atuar como o usuário conectado quando faz chamadas para a API de destino. Algumas permissões com privilégios elevados requerem o consentimento do administrador.

  • As permissões de aplicativos são usadas por aplicativos que são executados sem a presença de um usuário conectado, por exemplo, aplicativos que são executados como serviços em segundo plano ou daemons. Apenas um administrador pode consentir permissões de aplicação.

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

Âmbitos

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

No OAuth 2.0, esses tipos de conjuntos de permissões 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 da scope solicitação. Por exemplo, o valor https://graph.microsoft.com/Calendars.Read do escopo é usado para solicitar permissão para ler calendários do usuário no Microsoft Graph.

Adquira tokens de acesso com o MSAL

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

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

O MSAL armazena em cache um token depois que ele é adquirido. 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 acquireTokenSilently método na AuthHelper classe.

    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 não conseguir 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();

O MSAL também é capaz de atualizar um token quando ele está se aproximando da expiração (já que o cache de token também contém um token de atualização).

Resultados da autenticação

Quando o cliente solicita um token de acesso, o Microsoft Entra ID também retorna um resultado de autenticação que inclui metadados sobre o token de acesso. Esses dados permitem que seu aplicativo faça cache inteligente de tokens de acesso sem ter que analisar o token de acesso em si. O AuthenticationResult MSAL retorna expõe:

  • O token de acesso para a API da Web.
  • O token de ID para o usuário (um JWT).
  • A expiração do token, que informa a data/hora em que o token expira.
  • O 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.
  • O ID exclusivo para o usuário.

Introdução ao Microsoft Graph

A API do Microsoft Graph oferece um único ponto de extremidade, https://graph.microsoft.com, para fornecer acesso a informações e dados avançados e centrados nas pessoas na nuvem da Microsoft. Você pode usar APIs ou SDKs REST para acessar o ponto de extremidade e criar aplicativos que oferecem suporte a 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 poderoso conjunto 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 https://graph.microsoft.com/v1.0/me ponto de extremidade.