Comentários Editar

Noções básicas de autenticação e autorização

  • Artigo
  • 9 minutos para o fim da leitura

Para chamar o Microsoft Graph, seu aplicativo deve adquirir um token de acesso da plataforma de identidade da Microsoft. O token de acesso contém informações sobre o aplicativo e as permissões que ele tem para acessar os recursos e APIs disponíveis no Microsoft Graph. Para obter um token de acesso, o aplicativo deve ser registrado na plataforma de identidade da Microsoft e ter a autorização de um usuário ou administrador para acessar os recursos necessários do Microsoft Graph.

Este artigo fornece uma visão geral da plataforma de identidade da Microsoft, tokens de acesso e como seu aplicativo pode obter tokens de acesso. Para obter mais informações sobre a plataforma de identidade da Microsoft, confira O que é a plataforma de identidade da Microsoft?. Se você sabe como integrar um aplicativo à plataforma de identidade da Microsoft para obter tokens, confira as informações e amostras específicas do Microsoft Graph na seção Próximas etapas.

Registre um aplicativo na Microsoft Identity Platform

Antes que seu aplicativo possa receber um token da Microsoft Identity Platform, ele deve ser registrado no portal do Azure. O registro integra o aplicativo com a Microsoft Identity Platform e estabelece as informações que ele usa para acessar os tokens, incluindo:

  • ID do aplicativo: um identificador exclusivo atribuído pela Microsoft Identity Platform.
  • URI/URL de Redirecionamento: um ou mais pontos de extremidade nos quais seu aplicativo receberá respostas da plataforma de identidade da Microsoft. (Para aplicativos nativos e móveis, este é um URI atribuído pela plataforma de identidade da Microsoft.)
  • Segredo do Cliente: uma senha ou um par de chaves pública/privada que seu aplicativo usa para se autenticar na plataforma de identidade da Microsoft. (Não é necessário para aplicativos nativos ou móveis.)

As propriedades configuradas durante o registro são usadas na solicitação. Por exemplo, na seguinte solicitação de token: client_id é a ID do Aplicativo, redirect_uri é um dos URIs de Redirecionament o registrados do seu aplicativo e client_secret é o segredo do cliente.

// Line breaks for legibility only

POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps

Permissões do Microsoft Graph

O Microsoft Graph expõe permissões granulares que controlam o acesso de aplicativos a recursos, como usuários, grupos e email. Como desenvolvedor, você decide quais permissões solicitar ao Microsoft Graph. Quando um usuário faz logon no aplicativo, ele ou, em alguns casos, um administrador, tem a chance de consentir essas permissões. Se o usuário consentir, o aplicativo receberá acesso aos recursos e APIs solicitados. Para aplicativos que não aceitam um usuário conectado, as permissões podem ser previamente autorizadas por um administrador quando o aplicativo é instalado.

Práticas recomendadas para solicitar permissões

Observação

Como melhor prática, solicite as permissões com menos privilégios de que seu aplicativo precisa para acessar os dados e funcionar corretamente. Solicitar permissões com mais do que os privilégios necessários é uma prática de segurança ruim, o que pode fazer com que os usuários evitem o consentimento e afetem o uso do aplicativo.

Permissões delegadas e de aplicativo

O Microsoft Graph tem dois tipos de permissões:

  • Permissões delegadas são usadas por aplicativos que possuem um usuário conectado presente. Para esses aplicativos, o usuário ou um administrador consente com as permissões que o aplicativo solicita e o aplicativo atua como o usuário conectado ao fazer chamadas para o Microsoft Graph. Algumas permissões delegadas podem ser consentidas por usuários não administrativos, mas algumas permissões mais privilegiadas requerem o consentimento do administrador.

  • As permissões de aplicativo são usadas por aplicativos executados sem a presença de um usuário conectado; por exemplo, aplicativos executados como serviços ou daemons em segundo plano. As permissões do aplicativo só podem ser autorizadas por um administrador.

Permissões efetivas

Permissões efetivas são as permissões que seu aplicativo possui ao fazer solicitações ao Microsoft Graph. As permissões efetivas são determinadas por uma combinação das permissões do Microsoft Graph que você concedeu ao aplicativo, e os privilégios do usuário conectado ou do aplicativo de chamada. Dentro das organizações, a política ou a associação em uma ou mais funções determinam os privilégios do usuário conectado ou de um aplicativo. É importante entender a diferença entre as permissões delegadas e de aplicativo concedidas ao seu aplicativo e suas permissões efetivas ao fazer chamadas para o Microsoft Graph.

Permissões efetivas em cenários de permissão delegado versus somente aplicativos

  • Para permissões delegadas, as permissões efetivas do seu aplicativo são a interseção menos privilegiada das permissões delegadas que o aplicativo recebeu (por consentimento) e os privilégios do usuário conectado no momento. Seu aplicativo nunca pode ter mais privilégios do que o usuário conectado.

    Suponha que seu aplicativo tenha recebido a permissão delegada User.ReadWrite.All e chame a API Atualizar usuário. Essa permissão concede nominalmente ao seu aplicativo permissão para ler e atualizar o perfil de cada usuário em uma organização. No entanto, devido a permissões efetivas, as seguintes restrições se aplicam aos privilégios do usuário conectado:

    • Se o usuário conectado for um administrador global, seu aplicativo poderá atualizar o perfil de cada usuário na organização.
    • No entanto, se o usuário conectado não estiver em uma função de administrador, seu aplicativo poderá atualizar apenas o perfil do usuário conectado. Ele não atualizará os perfis de outros usuários na organização porque o usuário conectado não possui esses privilégios.

  • Para permissões de aplicativo, as permissões efetivasdo seu aplicativo estarão no nível completo de privilégios implícitos na permissão. Por exemplo, um aplicativo que tem a permissão de aplicativo User.ReadWrite.All pode atualizar o perfil de cada usuário na organização.

Comparação de permissões delegadas e de aplicativo

Item Permissões delegadas Permissões de aplicativos
Cenários de tipo de aplicativo Aplicativo web/móvel/de página única (SPA) Web / Daemon
Contexto de acesso Obter acesso em nome de um usuário Obter acesso como um serviço
Quem pode consentir?
  • Os usuários podem consentir com seus dados
  • Os administradores podem consentir com todos os usuários
    		•  Apenas o administrador pode consentir
    Outros nomes
  • escopos
  • Permissões OAuth2
    		•
  • Funções de aplicativo
  • Permissões somente de aplicativo
  • Permissões de acesso direto
    		•
    Resultado do consentimento oauth2PermissionGrants appRoleAssignments

    O Microsoft Graph expõe as permissões delegadas e de aplicativo, mas autoriza solicitações com base nas permissões efetivas do aplicativo.

    Para uma lista completa das permissões delegadas e de aplicativos para o Microsoft Graph, e quais permissões exigem o consentimento do administrador, consulte a Referência Permissões.

    Tokens de acesso

    Tokens de acesso emitidos pela plataforma de identidade da Microsoft contêm informações (declarações) que as APIs da Web protegidas pela Plataforma de Identidade da Microsoft, como o Microsoft Graph, usam para validar o chamador e para garantir que o chamador tenha as permissões adequadas para executar a operação solicitada. O chamador deve tratar tokens de acesso como cadeias de caracteres opacos porque o conteúdo do token destina-se apenas à API. Ao chamar o Microsoft Graph, sempre proteja tokens de acesso transmitindo-os por um canal seguro que usa o protocolo TLS (segurança de camada de transporte).

    O exemplo a seguir mostra um token de acesso à plataforma de identidade da Microsoft:

    EwAoA8l6BAAU7p9QDpi/D7xJLwsTgCg3TskyTaQAAXu71AU9f4aS4rOK5xoO/SU5HZKSXtCsDe0Pj7uSc5Ug008qTI+a9M1tBeKoTs7tHzhJNSKgk7pm5e8d3oGWXX5shyOG3cKSqgfwuNDnmmPDNDivwmi9kmKqWIC9OQRf8InpYXH7NdUYNwN+jljffvNTewdZz42VPrvqoMH7hSxiG7A1h8leOv4F3Ek/XbrnbEErTDLWrV6Lc3JHQMs0bYUyTBg5dThwCiuZ1evaT6BlMMLuSCVxdBGzXTBcvGwihFzZbyNoX+52DS5x+RbIEvd6KWOpQ6Ni+1GAawHDdNUiQTQFXRxLSHfc9fh7hE4qcD7PqHGsykYj7A0XqHCjbKKgWSkcAg==

    Para chamar o Microsoft Graph, anexe o token de acesso como um token de portador ao cabeçalho de autorização em uma solicitação HTTP. Por exemplo, a seguinte chamada que retorna as informações de perfil do usuário conectado (o token de acesso foi abreviado para facilitar a leitura):

    GET https://graph.microsoft.com/v1.0/me/ HTTP/1.1
Host: graph.microsoft.com
Authorization: Bearer EwAoA8l6BAAU ... 7PqHGsykYj7A0XqHCjbKKgWSkcAg==

    Tokens de acesso são um tipo de token de segurança fornecido pela plataforma de identidade da Microsoft. Eles são de curta duração, mas com tempos de vida padrão variáveis. Para obter mais informações sobre tokens de acesso e como os clientes usam esses tokens, confira Tokens de acesso.

    Obter um token de acesso

    Como a maioria dos desenvolvedores, você provavelmente utilizará as bibliotecas de autenticação para gerenciar suas interações de token com a plataforma de identidade da Microsoft. Bibliotecas de autenticação abstraem muitos detalhes de protocolo, como validação, manipulação de cookies, cache de token e manutenção de conexões seguras, longe do desenvolvedor, e permitem que você concentre o desenvolvimento no seu aplicativo. A Microsoft publica bibliotecas de cliente de código aberto e middleware de servidor.

    Sobre o ponto de extremidade da plataforma de identidade para desenvolvedores da Microsoft:

    • As bibliotecas de cliente da Biblioteca de Autenticação da Microsoft (MSAL) estão disponíveis para .NET, JavaScript, Android e Objective-C. Todas as plataformas estão em pré-visualização com suporte à produção e, caso alterações importantes sejam introduzidas, a Microsoft garante um caminho para a atualização.
    • O middleware de servidor da Microsoft está disponível para .NET core e ASP.NET (OWIN OpenID Connect e OAuth) e para Node.js (Microsoft Identity Platform Passport.js).
    • A Microsoft Identity Platform é compatível com várias bibliotecas de autenticação de terceiros.

    Para obter uma lista completa de bibliotecas de cliente da Microsoft, middleware de servidor da Microsoft e bibliotecas de terceiros compatíveis, confira Bibliotecas de autenticação da Microsoft Identity Platform.

    Você não precisa usar uma biblioteca de autenticação para obter um token de acesso. Para saber mais sobre o uso direto dos pontos de extremidade da plataforma de identidade da Microsoft sem precisar de uma biblioteca de autenticação, confira Autenticação da plataforma de identidade da Microsoft.

    Próximas etapas

    Se já estiver pronto para entrar no código, você pode usar os seguintes recursos para ajudá-lo a implementar a autenticação e a autorização com a Microsoft Identity Platform em seu aplicativo.

    Exemplos e treinamento do Microsoft Graph

    Para ajudá-lo a começar rapidamente, criamos uma série de módulos de treinamento e outros recursos que mostram como autenticar e usar a API em várias plataformas.

    Documentação e exemplos da Microsoft Identity Platform

    A documentação da Microsoft Identity Platform contém artigos e exemplos que se concentram especificamente na autenticação e autorização com a Microsoft Identity Platform.

    Confira também