Como projetar permissões delegadas em uma aplicação PHP

Permitir que uma pessoa gerencie tarefas em nome de outra pode atender a uma necessidade real de negócio, mas não deve implicar o compartilhamento de senhas nem a concessão de acesso geral à conta. Em uma aplicação PHP, uma delegação segura precisa deixar claro quem age, a quem representa, sobre quais recursos pode atuar e por quanto tempo. Também deve ser possível revogá-la e auditá-la.

O objetivo é autorizar uma ação específica preservando a identidade das duas pessoas. Isso exige mais do que uma tela para conceder permissões: afeta o modelo de dados, cada ponto de autorização, as operações assíncronas e os testes. Projetar esses elementos em conjunto reduz o risco de uma delegação válida em uma tela se transformar, por uma rota alternativa, em acesso excessivo.

Diferenciar delegação, impersonação e acesso compartilhado

Em uma delegação, quem inicia a operação continua sendo a identidade autenticada. Além disso, a aplicação registra que essa pessoa age em nome de outra, sob uma autorização limitada. A pessoa representada não iniciou a sessão e não deve aparecer como autora direta da requisição.

A impersonação altera a identidade efetiva com que o sistema trata uma requisição e pode ocultar quem realizou a ação se não for implementada com controles específicos. O acesso compartilhado, como fornecer credenciais, elimina a separação entre usuários e dificulta revogar ou atribuir atividades. Em um fluxo comum de delegação, nenhuma dessas abordagens substitui um contexto explícito de ator e principal representado.

Convém nomear ambos os papéis no código e nos registros. Por exemplo, actor_id identifica quem executou a operação e principal_id identifica a pessoa em cujo nome ela foi realizada. Evite nomes ambíguos como user_id em registros nos quais poderia se referir a qualquer um dos dois.

Definir escopo, recursos e validade antes de implementar

Uma delegação útil descreve com precisão o que autoriza. “Gerenciar a conta” costuma ser amplo demais. Em vez disso, é possível limitar a delegação a ações como revisar tarefas, atualizar o status delas ou responder a uma solicitação. Se as ações tiverem consequências diferentes, modele permissões separadas em vez de agrupar leitura, edição, aprovação e exclusão em uma capacidade genérica.

Defina também o escopo dos recursos: uma organização, um projeto, uma fila de tarefas ou um conjunto específico de registros. A permissão para editar tarefas de um projeto não deve habilitar a leitura de dados de outro projeto apenas porque o mesmo usuário delegado pode acessá-los em outra função.

A validade deve ter início e fim claros, além de um estado que permita revogar a delegação antes do vencimento. Decida qual fuso horário será usado para apresentar as datas e mantenha coerentes as comparações internas. Se a política exigir aprovação ou impedir delegações encadeadas, transforme isso em uma regra explícita e verificável; não deixe como uma convenção da interface.

Modelar a autorização e verificá-la em cada operação

Um esquema relacional pode representar uma delegação com campos como identificador, ator autorizado, principal representado, escopo, ações, data de início, data de expiração, status, criador e data de revogação. A estrutura exata depende do domínio: as ações podem ser armazenadas em uma tabela relacionada ou em outro formato validado, mas devem poder ser consultadas e verificadas sem interpretações ambíguas.

A autorização deve separar a autoridade do principal da autorização delegada ao ator. Para a operação solicitada, verifique se o principal representado teria acesso normal ao recurso e se as regras de negócio aplicáveis permitem a operação. Em seguida, verifique se o ator autenticado é o destinatário de uma delegação válida, vigente e não revogada, e se ela concede essa ação sobre esse recurso. A permissão efetiva fica limitada pelo acesso do principal e pelo escopo da delegação: ela não pode conceder ao ator mais ações ou recursos do que o principal pode autorizar, nem mais do que consta na própria delegação. Não exija que o ator também tenha acesso próprio ao recurso; ele pode agir justamente graças à delegação. Aplique, sim, as restrições que se aplicam à identidade do ator, como autenticação, pertencimento ao contexto exigido ou controles de segurança da operação.

Na prática, a verificação deve incluir:

• Que o ator esteja autenticado e que a delegação seja destinada a ele.
• Que o principal representado seja válido nesse contexto e tenha acesso normal ao recurso solicitado.
• Que a delegação esteja ativa no momento da operação, não tenha sido revogada e esteja dentro do período de validade.
• Que a ação solicitada e o recurso estejam dentro do escopo concedido, sem exceder a autoridade do principal.
• Que sejam cumpridas as restrições de negócio e segurança aplicáveis ao ator e à operação.

Centralize essa decisão em um serviço de autorização ou em uma política reutilizável, em vez de repetir condições parciais nos controladores. Ainda assim, invoque-a em cada operação relevante: uma view protegida não protege automaticamente uma API, um download, uma ação em massa ou uma rota de administração. Em PHP, o controlador pode obter o ator autenticado, resolver o contexto de delegação e solicitar ao serviço que autorize a ação sobre o recurso específico. A camada de domínio também pode impor invariantes críticas quando uma operação tiver consequências importantes.

Não confie em um principal_id enviado pelo navegador como prova de autorização. O servidor deve verificar a relação entre ator, principal, delegação, recurso e ação usando dados confiáveis. Também não presuma que ocultar um botão na interface impeça a chamada direta ao endpoint.

Preservar a atribuição na auditoria e nas operações assíncronas

Um registro útil permite reconstruir o que aconteceu sem confundir identidades. Para cada evento relevante, preserve o ator, o principal representado, a ação, o tipo e o identificador do recurso, a data, o resultado e a referência à delegação aplicada. Conforme o risco, registre também o motivo da operação ou o identificador de correlação. Evite armazenar segredos ou dados pessoais desnecessários no histórico.

A atribuição deve ser preservada em filas e jobs em segundo plano. Se uma solicitação delegada agendar uma tarefa, a mensagem deverá transportar um contexto verificável com ator, principal e referência de autorização, sem depender da sessão web, que já não estará disponível. Ao executar o job, decida se a delegação ainda deve ser verificada como ativa. Para uma ação que ainda possa ser cancelada, uma verificação no momento da execução costuma evitar que uma revogação deixe uma tarefa pendente com uma permissão obsoleta. Se a operação já tiver se tornado irreversível, documente esse limite e registre o momento da autorização.

Proteja os registros contra modificações não autorizadas e limite quem pode consultá-los. A auditoria deve apoiar a investigação e a prestação de contas, mas não se tornar uma cópia indiscriminada dos dados operacionais.

Projetar a expiração e a revogação como parte do fluxo

A expiração e a revogação não são apenas alterações de status em uma tela. Uma sessão que mantém um contexto de delegação pode continuar exibindo opções antigas; por isso, a autorização do servidor deve verificar o status vigente em cada requisição, mesmo que a interface também seja atualizada. Se as permissões forem armazenadas em cache, defina como invalidá-las e qual atraso máximo será aceito até que uma revogação entre em vigor.

Ao revogar, registre quem o fez e quando. Avalie explicitamente as sessões ativas, os tokens emitidos, os jobs em fila e os links temporários associados. Não presuma que encerrar uma sessão ou alterar um dado no banco de dados invalide automaticamente todos esses elementos. A resposta adequada depende do projeto, mas deve estar definida antes de publicar o fluxo.

Testar limites e casos que costumam passar despercebidos

Os testes devem verificar tanto as ações permitidas quanto as negadas. Inclua, no mínimo, uma delegação ainda não vigente, expirada ou revogada; um ator diferente do autorizado; um recurso fora do escopo; uma ação não concedida; um principal incorreto ou sem acesso normal ao recurso; e o acesso direto a endpoints que a interface não exibe. Inclua também um caso positivo em que o ator não tenha acesso próprio ao recurso, mas o principal tenha acesso e a delegação cubra a ação e o recurso. Assim, verifica-se que o sistema não confunde as permissões próprias do ator com a autoridade delegada.

Adicione testes de limites temporais, alterações concorrentes e efeitos indiretos. Por exemplo, confirme o que acontece se uma delegação for revogada enquanto uma operação estiver em andamento ou um job estiver pendente, e se uma ação sobre uma tarefa disparar notificações, exportações ou alterações secundárias. Verifique se esses efeitos preservam a atribuição correta e não ampliam o escopo.

Separe os testes unitários da política de autorização dos testes de integração que percorrem rotas, persistência e filas. Um teste que verifica apenas o método de decisão não demonstra que todas as rotas o invocam; um teste de interface também não comprova a proteção do servidor.

Lista de verificação antes da publicação

• O ator e o principal representado estão claramente diferenciados no código, na interface e na auditoria?
• Cada delegação limita ações, recursos e validade, e combinações inválidas são impedidas?
• A política verifica o acesso do principal e limita o ator ao escopo delegado, sem exigir que ele tenha acesso próprio ao recurso?
• Cada operação no servidor verifica identidade, status, tempo, escopo e ação?
• A revogação afeta sessões, tokens, caches e jobs pendentes de acordo com uma política definida?
• Os registros permitem atribuir as ações sem armazenar informações desnecessárias?
• Os testes abrangem negações, limites temporais, delegações válidas sem acesso próprio do ator e efeitos indiretos?

Uma delegação é segura quando não se confunde com o acesso à conta de outra pessoa e quando cada ação pode ser justificada pela autoridade do principal e por uma delegação vigente e limitada. Se a equipe não conseguir responder com precisão quem agiu, em nome de quem, sobre qual recurso e com qual permissão, o fluxo ainda precisa de mais planejamento antes de chegar à produção.