Noções básicas sobre o acesso delegado
Quando um usuário entra em um aplicativo e o usa para acessar algum outro recurso, como o Microsoft Graph, o aplicativo precisará, primeiro, pedir permissão para acessar esse recurso em nome do usuário. Esse cenário comum é chamado de acesso delegado.
Por que devo usar o acesso delegado?
Com frequência, as pessoas usam aplicativos diferentes para acessar dados de serviços de nuvem. Por exemplo, alguém pode querer usar um aplicativo de leitor de PDF favorito para visualizar os arquivos armazenados no OneDrive. Outro exemplo pode ser o aplicativo de linha de negócios de uma empresa que pode recuperar informações compartilhadas sobre os colegas de trabalho para que eles possam escolher com facilidade os revisores para uma solicitação. Nesses casos, o aplicativo cliente, o leitor de PDF ou a ferramenta de aprovação de solicitação da empresa precisam estar autorizados a acessar esses dados em nome do usuário que entrou no aplicativo.
Use o acesso delegado sempre que quiser permitir que um usuário conectado trabalhe com recursos próprios ou com os recursos que ele pode acessar. Seja um administrador configurando políticas para toda a organização ou um usuário excluindo um email da caixa de entrada, todos os cenários que envolvem ações do usuário devem usar o acesso delegado.
Por outro lado, o acesso delegado geralmente é uma opção ruim para os cenários que precisam ser executados sem um usuário conectado, como automação. Também pode ser uma opção ruim para os cenários que envolvem o acesso a recursos de muitos usuários, como prevenção contra perda de dados ou backups. Considere o uso do acesso somente ao aplicativo para esses tipos de operações.
Como solicitar escopos como um aplicativo cliente
Seu aplicativo precisará solicitar que o usuário conceda um escopo específico ou um conjunto de escopos para o aplicativo de recursos que você deseja acessar. Os escopos também podem ser chamados de permissões delegadas. Esses escopos descrevem quais recursos e operações seu aplicativo deseja executar em nome do usuário. Por exemplo, caso você deseje que o seu aplicativo mostre ao usuário uma lista de mensagens de email e mensagens de chat recebidas recentemente, peça ao usuário que forneça consentimento para os escopos Mail.Read e Chat.Read do Microsoft Graph.
Depois que o aplicativo solicitar um escopo, um usuário ou um administrador precisará permitir o acesso solicitado. Os usuários consumidores que tenham contas Microsoft, como as contas do Outlook.com ou do Xbox Live, sempre podem conceder escopos para si mesmos. Os usuários organizacionais que tenham contas do Microsoft Entra podem ou não conseguir conceder escopos, dependendo das configurações da organização. Se um usuário organizacional não puder consentir com os escopos diretamente, ele precisará pedir ao administrador da organização que forneça o consentimento para ele.
Siga sempre o princípio de privilégios mínimos: você nunca deve solicitar escopos de que o seu aplicativo não precisa. Esse princípio ajuda a limitar o risco de segurança caso o aplicativo seja comprometido e facilita a permissão de acesso ao aplicativo pelos administradores. Por exemplo, se o aplicativo precisar listar apenas os chats aos quais um usuário pertence, mas não precisar mostrar as mensagens de chat em si, você deverá solicitar o escopo Chat.ReadBasic mais limitado do Microsoft Graph em vez de Chat.Read. Para obter mais informações sobre os escopos do OpenID, confira Escopos do OpenID.
Como projetar e publicar escopos para um serviço de recurso
Se você estiver criando uma API e quiser permitir o acesso delegado em nome dos usuários, precisará criar escopos que outros aplicativos poderão solicitar. Esses escopos devem descrever as ações ou os recursos disponíveis para o cliente. Você deve considerar os cenários de desenvolvedor ao projetar os escopos.
Como funciona o acesso delegado?
O mais importante a ser lembrado sobre o acesso delegado é que o aplicativo cliente e o usuário conectado precisam estar devidamente autorizados. A concessão de um escopo não é suficiente. Se o aplicativo cliente não tiver o escopo certo ou o usuário não tiver direitos suficientes para ler ou modificar o recurso, ocorrerá uma falha na chamada.
- Autorização do aplicativo cliente – Os aplicativos cliente são autorizados pela concessão de escopos. Quando um aplicativo cliente receber um escopo de um usuário ou um administrador para acessar um recurso, essa concessão será registrada na ID do Microsoft Entra. Todos os tokens de acesso delegados solicitados pelo cliente para acessar o recurso em nome do usuário relevante conterão os valores de declaração desses escopos na declaração
scp. O aplicativo de recurso verifica essa declaração para determinar se o aplicativo cliente recebeu o escopo correto para a chamada. - Autorização do usuário – Os usuários são autorizados pelo recurso que você está chamando. Os aplicativos de recursos podem usar um ou mais sistemas para autorização do usuário, como o controle de acesso baseado em função, as relações de propriedade/associação, as listas de controle de acesso ou outras verificações. Por exemplo, a ID do Microsoft Entra verifica se um usuário foi atribuído a uma função de gerenciamento de aplicativo ou de administrador geral antes de permitir que ele exclua os aplicativos de uma organização, mas também permite que todos os usuários excluam os aplicativos dos quais são proprietários. Da mesma forma, o serviço do SharePoint Online verifica se um usuário tem direitos de proprietário ou de leitor apropriados em um arquivo antes de permitir que esse usuário o abra.
Exemplo de acesso delegado – OneDrive por meio do Microsoft Graph
Considere o seguinte exemplo:
Alice deseja usar um aplicativo cliente para abrir um arquivo protegido por uma API de recurso, o Microsoft Graph. Para a autorização do usuário, o serviço do OneDrive verificará se o arquivo está armazenado na unidade de Alice. Se ele estiver armazenado na unidade de outro usuário, o OneDrive negará a solicitação de Alice como não autorizada, pois Alice não tem o direito de ler as unidades de outros usuários.
Para a autorização do aplicativo cliente, o OneDrive verificará se o cliente que está fazendo a chamada recebeu o escopo Files.Read em nome do usuário conectado. Nesse caso, o usuário conectado é a Alice. Se Files.Read não tiver sido concedido ao aplicativo para Alice, o OneDrive também causará a falha da solicitação.
| GET /drives/{id}/files/{id} | Escopo Files.Read concedido ao aplicativo cliente para Alice |
Escopo Files.Read não concedido ao aplicativo cliente para Alice |
|---|---|---|
| O documento está no OneDrive de Alice. | 200 – Acesso permitido. | 403 – Não Autorizado. Alice (ou o administrador dela) não permitiu que esse cliente lesse os arquivos. |
| O documento está no OneDrive de outro usuário*. | 403 – Não Autorizado. Alice não tem direitos de ler esse arquivo. Embora o cliente tenha recebido Files.Read, ele será negado ao agir em nome de Alice. |
403 – Não Autorizado. Alice não tem direitos de ler esse arquivo, e o cliente também não tem permissão para ler arquivos aos quais ela tem acesso. |
O exemplo dado é simplificado para ilustrar a autorização delegada. O serviço de produção do OneDrive dá suporte a muitos outros cenários de acesso, como arquivos compartilhados.