Noções básicas sobre 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?
As pessoas utilizam frequentemente diferentes aplicações para aceder aos seus dados a partir de serviços em nuvem. Por exemplo, alguém pode querer usar um aplicativo de leitor de PDF favorito para exibir arquivos armazenados em seu OneDrive. Outro exemplo pode ser o aplicativo de linha de negócios de uma empresa que pode recuperar informações compartilhadas sobre seus colegas de trabalho para que eles possam escolher facilmente 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 ser 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 seus próprios recursos ou recursos que ele possa acessar. Seja um administrador configurando políticas para toda a organização ou um usuário excluindo um e-mail em sua caixa de entrada, todos os cenários que envolvem ações do usuário devem usar acesso delegado.
Por outro lado, o acesso delegado geralmente é uma escolha ruim para cenários que devem ser executados sem um usuário conectado, como a automação. Também pode ser uma má escolha para cenários que envolvem o acesso aos recursos de muitos usuários, como prevenção de perda de dados ou backups. Considere o uso de acesso somente de aplicativo para esses tipos de operações.
Solicitando escopos como um aplicativo cliente
Seu aplicativo precisará solicitar ao usuário que conceda um escopo específico, ou 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, se você quiser que seu aplicativo mostre ao usuário uma lista de mensagens de email e mensagens de bate-papo recebidas recentemente, você pode pedir ao usuário para consentir com o Microsoft Graph Mail.Read e Chat.Read escopos.
Depois que seu aplicativo solicitar um escopo, um usuário ou administrador precisará conceder o acesso solicitado. Os usuários consumidores com Contas da Microsoft, como contas Outlook.com ou Xbox Live, sempre podem conceder escopos para si mesmos. Os usuários organizacionais com contas do Microsoft Entra podem ou não conceder escopos, dependendo das configurações de sua organização. Se um usuário organizacional não puder consentir diretamente com os escopos, ele precisará solicitar ao administrador da organização o consentimento para eles.
Siga sempre o princípio do menor privilégio: você nunca deve solicitar escopos que seu aplicativo não precisa. Este princípio ajuda a limitar o risco de segurança se a sua aplicação estiver comprometida e torna mais fácil para os administradores concederem acesso à sua aplicação. Por exemplo, se seu aplicativo só precisa listar os chats aos quais um usuário pertence, mas não precisa mostrar as próprias mensagens de bate-papo, você deve solicitar o escopo mais limitado do Microsoft Graph Chat.ReadBasic em vez de Chat.Read. Para obter mais informações sobre escopos openID, consulte Escopos OpenID.
Projetando e publicando escopos para um serviço de recursos
Se você estiver criando uma API e quiser permitir acesso delegado em nome dos usuários, precisará criar escopos que outros aplicativos possam solicitar. Esses escopos devem descrever as ações ou recursos disponíveis para o cliente. Você deve considerar cenários de desenvolvedor ao projetar seus escopos.
Token para si mesmo
No cenário em que:
- O aplicativo de recurso e o aplicativo cliente são os mesmos.
- O aplicativo não tem nenhuma API da Web registrada.
- O aplicativo está solicitando um token para uma permissão delegada que ele mesmo expõe
Nenhum consentimento será necessário ou exibido para esta solicitação de token. Além disso, os aplicativos que são criados dentro de um locatário e solicitam um token para si mesmos podem ser inferidos como tendo acesso aos dados do perfil e receberão acesso ao perfil automaticamente.
Como funciona o acesso delegado?
A coisa mais importante a lembrar sobre o acesso delegado é que tanto o aplicativo cliente quanto o usuário conectado precisam ser devidamente autorizados. Conceder um escopo não é suficiente. Se o aplicativo cliente não tiver o escopo correto ou se o usuário não tiver direitos suficientes para ler ou modificar o recurso, a chamada falhará.
- Autorização do aplicativo cliente - Os aplicativos cliente são autorizados pela concessão de escopos. Quando um usuário ou administrador concede um escopo a um aplicativo cliente para acessar algum recurso, essa concessão será registrada na ID do Microsoft Entra. Todos os tokens de acesso delegado solicitados pelo cliente para acessar o recurso em nome do usuário relevante conterão os valores de declaração desses escopos na
scpdeclaração. O aplicativo de recursos 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 controle de acesso baseado em função, relações de propriedade/associação, listas de controle de acesso ou outras verificações. Por exemplo, o Microsoft Entra ID verifica se um usuário foi atribuído a uma função de gerenciamento de aplicativos ou administrador geral antes de permitir que ele exclua os aplicativos de uma organização, mas também permite que todos os usuários excluam aplicativos de sua propriedade. Da mesma forma, o serviço do SharePoint Online verifica se um usuário tem direitos apropriados de proprietário ou leitor sobre um arquivo antes de permitir que esse usuário o abra.
Exemplo de acesso delegado – OneDrive através do Microsoft Graph
Considere o seguinte exemplo:
Alice quer usar um aplicativo cliente para abrir um arquivo protegido por uma API de recurso, o Microsoft Graph. Para autorização do usuário, o serviço OneDrive verificará se o arquivo está armazenado na unidade de Alice. Se estiver armazenado na unidade de outro utilizador, o OneDrive negará o pedido de Alice como não autorizado, uma vez que Alice não tem o direito de ler as unidades de outros utilizadores.
Para autorização de aplicativo cliente, o OneDrive verificará se o cliente que fez a chamada recebeu o Files.Read escopo em nome do usuário conectado. Nesse caso, a usuária conectada é Alice. Se Files.Read não tiver sido concedido ao aplicativo para Alice, o OneDrive também falhará na solicitação.
| GET /unidades/{id}/files/{id} | Aplicativo cliente com escopo concedido Files.Read para Alice |
Aplicativo cliente sem escopo concedido Files.Read para Alice |
|---|---|---|
| O documento está no OneDrive de Alice. | 200 – Acesso concedido. | 403 - Não autorizado. Alice (ou o seu administrador) não permitiu que este cliente lesse os seus ficheiros. |
| O documento está no OneDrive de outro usuário*. | 403 - Não autorizado. Alice não tem direitos para ler este ficheiro. Mesmo que o cliente tenha sido concedido Files.Read , ele deve ser negado ao agir em nome de Alice. |
403 – Não autorizado. Alice não tem direitos para ler este ficheiro, e o cliente também não tem permissão para ler ficheiros aos quais tem acesso. |
O exemplo dado é simplificado para ilustrar a autorização delegada. O serviço OneDrive de produção suporta muitos outros cenários de acesso, como ficheiros partilhados.