Usar o controle de acesso baseado em função em seu aplicativo Web Node.js

Aplica-se a: Locatários da força de trabalho Locatários externos (saiba mais)

O RBAC (controle de acesso baseado em função) é um mecanismo usado para impor a autorização em aplicativos. A ID Externa do Microsoft Entra permite que você defina funções de aplicativo para o seu aplicativo e atribua essas funções a usuários e grupos. As funções atribuídas a um usuário ou grupo definem seu nível de acesso aos recursos e operações em seu aplicativo. Quando a ID Externa emite um token de segurança para um usuário autenticado, ela inclui os nomes das funções que você atribuiu ao usuário ou grupo na declaração de funções do token de segurança.

Você também pode configurar seu locatário externo para retornar as associações de grupo do usuário. Os desenvolvedores podem usar grupos de segurança para implementar o RBAC nos aplicativos, onde as associações do usuário em grupos específicos são interpretadas como associações de função.

Depois de atribuir usuários e grupos a funções, a declaração de funções será emitida no token de segurança. No entanto, para emitir a declaração de associação de grupos em tokens de segurança, é necessário configuração adicional no locatário do cliente.

Neste artigo, você aprenderá a receber funções de usuário ou associação de grupo ou ambas como declarações em um token de segurança do seu aplicativo Web Node.js.

Pré-requisitos

• Se você não tiver feito ainda conclua as etapas no artigo Usando o controle de acesso baseado em função para aplicativos . Este artigo mostra como criar funções para seu aplicativo, como atribuir usuários e grupos a essas funções, como adicionar membros a um grupo e como adicionar uma declaração de grupo a um token de segurança. Saiba mais sobre tokens de ID e tokens de acesso.

• Caso ainda não tenha feito, conclua as etapas em Conectar usuários em seu próprio aplicativo Web Node.js

Receber declarações de grupos e de funções em seu aplicativo Web Node.js

Depois de configurar o locatário do cliente, você poderá recuperar suas declarações de funções e de grupos em seu aplicativo cliente. As declarações de funções e de grupos estão presentes no token de ID e no token de acesso, mas seu aplicativo cliente só precisa verificar essas declarações no token de ID para implementar a autorização no lado do cliente. O aplicativo de API também pode recuperar essas declarações quando receber o token de acesso.

Você verifica o valor da declaração de funções, conforme mostrado no exemplo de trecho de código a seguir:

const msal = require('@azure/msal-node');
const { msalConfig, TENANT_SUBDOMAIN, REDIRECT_URI, POST_LOGOUT_REDIRECT_URI } = require('../authConfig');

...
class AuthProvider {
...
    async handleRedirect(req, res, next) {
        const authCodeRequest = {
            ...req.session.authCodeRequest,
            code: req.body.code, // authZ code
            codeVerifier: req.session.pkceCodes.verifier, // PKCE Code Verifier
        };
    
        try {
            const msalInstance = this.getMsalInstance(this.config.msalConfig);
            const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);
            let roles = tokenResponse.idTokenClaims.roles;
        
            //Check roles
            if (roles && roles.includes("Orders.Manager")) {
                //This user can view the ID token claims page.
                res.redirect('/id');
            }
            
            //User can only view the index page.
            res.redirect('/');
        } catch (error) {
            next(error);
        }
    }
...
}

Se você atribuir um usuário a várias funções, a cadeia de caracteres roles conterá todas as funções separadas por uma vírgula, como Orders.Manager,Store.Manager,.... Certifique-se de criar seu aplicativo para lidar com as seguintes condições:

• ausência da declaração roles no token
• o usuário não foi atribuído a nenhuma função
• vários valores na declaração roles quando você atribui um usuário a várias funções

Você também pode verificar o valor da declaração de grupos, conforme mostrado no exemplo de trecho de código a seguir:

const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);
let groups = tokenResponse.idTokenClaims.groups;

O valor da declaração de grupos é o objectId do grupo. Se um usuário for membro de vários grupos, a cadeia de caracteres groups conterá todos os grupos separados por uma vírgula, como 7f0621bc-b758-44fa-a2c6-...,6b35e65d-f3c8-4c6e-9538-....

Observação

Se você atribuir a um usuário funções internas do Microsoft Entra ou comumente conhecidas como funções do diretório, essas funções aparecerão na declaração de grupos do token de segurança.

Lidar com excedente de grupos

Para garantir que o tamanho do token de segurança não exceda o limite de tamanho do cabeçalho HTTP, a ID Externa limita o número de IDs de objeto que ela inclui na declaração grupos. O limite de excedente é 150 para tokens SAML e 200 para tokens JWT. É possível exceder esse limite se um usuário pertencer a muitos grupos e você solicitar todos os grupos.

Detectar excedente de grupo no código-fonte

Se você não puder evitar excedentes de grupos, precisará lidar com isso em seu código. Quando você ultrapassar o limite de excedente, o token não conterá a declaração de grupos . Em vez disso, o token conterá uma declaração _claim_names com um membro de grupos da matriz. Portanto, você precisará verificar se a declaração _claim_names está presente para ver se ocorreu um excedente. O trecho de código a seguir mostra como detectar um excedente de grupos:

const tokenResponse = await msalInstance.acquireTokenByCode(authCodeRequest, req.body);

if(tokenResponse.idTokenClaims.hasOwnProperty('_claim_names') && tokenResponse.idTokenClaims['_claim_names'].hasOwnProperty('groups')) {
    //overage has occurred
}

Use as instruções no artigo Configurando declarações de grupo e funções de aplicativo em tokens para saber como solicitar a lista completa de grupos quando ocorrer excedente de grupos.

Como usar valores de grupos e de funções em seu aplicativo Web Node.js

No aplicativo cliente, você pode verificar se um usuário conectado tem as funções necessárias para acessar uma rota protegida ou chamar um ponto de extremidade de API. Isso pode ser feito verificando a declaração roles no token de ID. Para implementar essa proteção em seu aplicativo, crie proteções usando um middleware personalizado.

No aplicativo de serviço (aplicativo de API), você também pode proteger os pontos de extremidade da API. Depois de validar o token de acesso enviado pelo aplicativo cliente, você poderá verificar as declarações de funções ou de grupos nas declarações de conteúdo do token de acesso.

Uso Funções ou Grupos de Aplicativos?

Nesse artigo, você aprendeu que pode usar Funções de Aplicativo ou de Grupos para implementar o RBAC em seu aplicativo. A abordagem preferencial é usar funções de aplicativo, pois fornece um controle mais granular ao gerenciar o acesso/permissões de acesso no nível do aplicativo. Para obter mais informações sobre como escolher uma abordagem, confira Escolher uma abordagem.

Próximas etapas

• Saiba mais sobre Como configurar declarações de grupo e funções de aplicativos em tokens.