Proteger aplicativos e APIs validando declarações

  • Artigo

Interagir com tokens é uma parte fundamental da criação de aplicativos para autorizar usuários. De acordo com o princípio de Confiança Zero, para acesso com privilégios mínimos, é essencial que os aplicativos validem os valores de determinadas declarações presentes no token de acesso ao executar a autorização.

A autorização baseada em declarações permite que os aplicativos garantam que o token contenha os valores corretos para itens como o locatário, o assunto e o ator presentes no token. Dito isto, a autorização baseada em declarações pode parecer complexa, dados os vários métodos a serem usados e cenários a serem controlados. Este artigo pretende simplificar o processo de autorização baseado em declarações para que você possa garantir que seus aplicativos sigam as práticas mais seguras.

Para garantir que sua lógica de autorização seja segura, você deve validar as seguintes informações nas declarações:

  • O público apropriado é especificado para o token.
  • A ID do locatário do token corresponde à ID do locatário em que os dados são armazenados.
  • O assunto do token é apropriado.
  • O ator (aplicativo cliente) está autorizado.

Observação

Os tokens de acesso são validados apenas nas APIs Web para as quais foram adquiridos por um cliente. O cliente não deve validar tokens de acesso.

Para obter mais informações sobre as declarações mencionadas neste artigo, confira tokens de acesso da plataforma de identidade da Microsoft.

Validar o público-alvo

A declaração aud identifica o público-alvo destinado do token. Antes de validar declarações, você sempre deve verificar se o valor da declaração aud contida no token de acesso corresponde à API Web. O valor pode depender de como o cliente solicitou o token. O público-alvo no token de acesso depende do ponto de extremidade:

  • Para tokens v2.0, o público-alvo é a ID do cliente da API Web. É um GUID.
  • Para tokens v1.0, o público-alvo é um dos URIs da appID declarados na API Web que valida o token. Por exemplo, api://{ApplicationID}, ou um nome exclusivo começando com um nome de domínio (se o nome de domínio estiver associado a um locatário).

Para obter mais informações sobre o URI da appID de um aplicativo, confira URI da ID do Aplicativo.

Validar o locatário

Sempre verifique se o tid em um token corresponde à ID do locatário usada para armazenar dados com o aplicativo. Quando as informações são armazenadas para um aplicativo no contexto de um locatário, elas só devem ser acessadas novamente mais tarde no mesmo locatário. Nunca permita que dados em um locatário sejam acessados de outro locatário.

A validação do locatario é apenas o primeiro passo, e as verificações sobre assunto e o ator descritas neste artigo ainda são necessárias. Se a sua intenção for autorizar todos os usuários em um locatário, é altamente recomendável adicionar explicitamente esses usuários a um grupo e autorizar com base nesse grupo. Por exemplo, verificando apenas a ID do locatário e a presença de uma declaração oid, sua API pode autorizar inadvertidamente todas as entidades de serviço nesse locatário, além dos usuários.

Validar o assunto

Determine se o assunto do token, como o usuário (ou o próprio aplicativo para um token somente de aplicativo), está autorizado.

Você pode verificar declarações específicas sub ou oid.

Ou,

Você pode verificar se a entidade pertence a uma função ou grupo apropriado com as declarações roles, scp, groups e wids. Por exemplo, use os valores de declaração imutáveis tid e oid como uma chave combinada para dados do aplicativo e determine se um usuário deve receber acesso.

As declarações roles, groups ou wids também podem ser usadas para determinar se a entidade tem autorização para executar uma operação, embora não sejam uma lista completa de todas as maneiras pelas quais uma entidade pode receber permissões. Por exemplo, um administrador pode ter permissão para gravar em uma API, mas não um usuário normal, ou o usuário pode estar em um grupo com permissão para executar alguma ação. A declaração wid representa as funções de todo o locatário atribuídas ao usuário das funções presentes em funções internas do Microsoft Entra. Para obter mais informações, confira Funções internas do Microsoft Entra.

Aviso

Nunca use declarações como email, preferred_username ou unique_name para determinar se o usuário em um token de acesso deve ter acesso aos dados. Essas declarações não são exclusivas e podem ser controláveis por administradores de locatários ou às vezes usuários, o que as torna inadequadas para decisões de autorização. Elas só podem ser usadas para fins de exibição. Também não use a declaração upn para autorização. Embora o UPN seja exclusivo, ele geralmente muda ao longo do tempo de vida de uma entidade de usuário, o que o torna não confiável para autorização.

Validar o ator

Um aplicativo cliente que está agindo em nome de um usuário (conhecido como ator), também deve ser autorizado. Use a declaração scp (escopo) para validar se o aplicativo tem permissão para executar uma operação. As permissões em scp devem ser limitadas ao que o usuário realmente precisa e seguem os princípios de privilégios mínimos.

No entanto, há ocorrências conhecidas em que scp não está presente no token: Você deve verificar a ausência da declaração scp para os seguintes cenários:

  • Permissão somente para aplicativo / aplicativos de daemon
  • Tokens de ID

Para obter mais informações sobre escopos e permissões, confira Escopos e permissões na plataforma de identidade da Microsoft.

Observação

Um aplicativo pode lidar com tokens somente de aplicativo (solicitações de aplicativos sem usuários, como aplicativos daemon) e deseja autorizar um aplicativo específico em vários locatários, em vez de IDs de entidade de serviço individuais. Nesse caso, a declaração appid (para tokens v1.0) ou a declaração azp (para tokens v2.0) pode ser usada para autorização de entidade. No entanto, ao usar essas declarações, o aplicativo deve garantir que o token tenha sido emitido diretamente para o aplicativo validando a declaração opcional idtyp. Somente tokens do tipo app podem ser autorizados dessa forma, pois os tokens de usuário delegados podem ser obtidos potencialmente por entidades diferentes do aplicativo.

Próximas etapas