Obter tokens de acesso protegidos por Proof-of-Possession

Para aumentar a proteção dos tokens de acesso OAuth 2.0 armazenados no navegador contra "token replay", a MSAL fornece um Access Token Proof-of-Posession esquema de autenticação. Access Token Proof-of-Possession, ou AT PoP, é um esquema de autenticação que vincula criptograficamente os tokens de acesso ao navegador e à aplicação cliente de onde são solicitados, significando que não podem ser usados a partir de uma aplicação ou dispositivo diferente.

É importante compreender que, para AT PoP funcionar de ponta a ponta e fornecer a atualização de segurança pretendida, tanto o serviço de autorização que emite os tokens de acesso como o servidor de recursos ao qual estes fornecem acesso devem suportar AT PoP.

Token de Acesso ao Portador vs Token de Acesso Vinculado (PoP)

Token de acesso ao portador

O Resultado de Autenticação padrão devolvido pelas APIs MSAL v2 inclui uma accessToken propriedade. Quando usado com o esquema de autenticação padrão Bearer , o valor sob a accessToken propriedade é o segredo do token de acesso fornecido pelo servidor de autorização. Este artefacto é armazenado em cache pelo MSAL e deve ser adicionado aos pedidos de recursos como um token portador no cabeçalho do Authorization pedido.

Exemplo de Utilização do Token de Acesso ao Portador:

// Using the Bearer scheme (default), acquireTokenRedirect returns an AuthenticationResult object containing the Bearer access token secret
const { accessToken } = await myMSALObj.acquireTokenRedirect(popTokenRequest);

// The bearer token secret is appended to the Authorization header
const headers = new Headers();
const authHeader = `Bearer ${accessToken}`; // The Bearer label is used in this header
headers.append("Authorization", authHeader);

Token de Acesso Vinculado

Também conhecido como PoP Token ou Signed HTTP Request. Quando o esquema de autorização POP está ativado num pedido de token do MSAL, o servidor de autorização continuará a fornecer um segredo de token de acesso do tipo JSON Web Token, semelhante a um token de acesso Bearer, que o MSAL também colocará em cache. A principal diferença é que, ao usar o POP esquema, esse segredo do token de acesso será ligado ao navegador do utilizador através de um par de chaves criptográficas assimétricas.

O segredo do token de acesso é encapsulado num novo JSON Web Token, que será assinado utilizando o algoritmo de hashing HMAC (Hash-based Message Authentication Code) e a chave privada do par de chaves que a MSAL gera, armazena e gere. O JWT assinado é então adicionado ao AuthorizationResult objeto sob a accessToken propriedade e devolvido da API MSAL v2 chamada.

Assim que a aplicação cliente recebe o resultado de autenticação devolvido, pode extrair o valor accessToken do resultado de autenticação e adicioná-lo ao cabeçalho Authorization de um pedido de um recurso protegido por PoP, utilizando o rótulo PoP em vez do rótulo Bearer.

Nota: O JWT assinado (designado Signed HTTP Request ou SHR) nunca é armazenado em cache pela MSAL. Sempre que uma API MSAL v2 é chamada, a MSAL recupera um token de acesso bruto válido e secreto da cache ou solicita um novo token de acesso ao servidor de autorização. A MSAL assina então esse token de acesso e devolve-lo no resultado de autenticação.

Exemplo de utilização de token de acesso vinculado (PoP):

// Using the POP scheme (default), acquireTokenRedirect returns an AuthenticationResult object containing the Signed HTTP Request (PoP Token)
const { accessToken } = await myMSALObj.acquireTokenRedirect(popTokenRequest);

// The SHR is appended to the Authorization header
const headers = new Headers();
const authHeader = `PoP ${accessToken}`; // The PoP label is used in this header
headers.append("Authorization", authHeader);

Fazer um Pedido de Token PoP

Depois de determinar se o serviço de autorização e o servidor de recursos suportam a ligação do token de acesso, pode configurar os seus objetos de autenticação da MSAL e de pedido de autorização para adquirir tokens de acesso vinculados, construindo um objeto de pedido de token que contenha os atributos específicos de PoP do token de acesso. Todos os atributos seguintes são opcionais no objeto de pedido, no entanto, authorizationScheme deve ser definido manualmente para 'pop' para permitir a prova de posse.

Parâmetros do Pedido AT PoP

Nota: Embora este documento mostre como adicionar um shrNonce à SignedHttpRequest, o padrão para obtenção do nonce do servidor não é abordado. Por favor, consulte a documentação sobre o nonce do servidor SHR para mais informações sobre como obter nonces gerados pelo servidor.

Exemplo de pedido de redirecionamento para aquisição de token

const popTokenRequest = {
    scopes: ["User.Read"],
    authenticationScheme: msal.AuthenticationScheme.POP,
    resourceRequestMethod: "POST",
    resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
    shrClaims: "{\"shrClaim1\": \"claimValue\"}",
    shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER"
}

Uma vez configurado o pedido e POP definido como authenticationScheme, pode ser enviado para a acquireTokenRedirect API MSAL v2.

const response = await myMSALObj.acquireTokenRedirect(popTokenRequest);

// Once a Pop Token has been acquired, it can be added on the authorization header of a resource request
const headers = new Headers();
const authHeader = `${response.tokenType} ${response.accessToken}`;

headers.append("Authorization", authHeader);

const options = {
    method: popTokenRequest.resourceRequestMethod,
    headers: headers
};

// After the request has been built and the POP access token has bee appended, the request can be executed using an API like "fetch"
fetch(endpoint, options)
    .then(response => response.json())
    .then(response => callback(response, endpoint))
    .catch(error => console.log(error));
});

Exemplo de Pedido Silencioso de Aquisição de Token

A aquisição silenciosa de tokens de acesso PoP exige as mesmas alterações na configuração do pedido de token tal como nas APIs interativas acquireToken:

const silentPopTokenRequest = {
    scopes: ["User.Read"],
    authenticationScheme: msal.AuthenticationScheme.POP, // Default is "BEARER"
    resourceRequestMethod: "POST",
    resourceRequestUri: "YOUR_RESOURCE_ENDPOINT",
    shrClaims: "{\"shrClaim1\": \"claimValue\"}",
    shrNonce: "NONCE_ACQUIRED_FROM_RESOURCE_SERVER"
}

// Try to acquire token silently
const { accessToken } = await myMSALObj.acquireTokenSilent(silentPopTokenRequest).catch(async (error) => {
        console.log("Silent token acquisition failed.");
        if (error instanceof msal.InteractionRequiredAuthError) {
            // Fallback to interaction if silent call fails
            console.log("Acquiring token using redirect");
            myMSALObj.acquireTokenRedirect(silentPopTokenRequest);
        } else {
            console.error(error);
        }
    });

// Once a Pop Token has been acquired, it can be added on the authorization header of a resource request
const headers = new Headers();
const authHeader = `PoP ${accessToken}`;

headers.append("Authorization", authHeader);

const options = {
    method: popTokenRequest.resourceRequestMethod,
    headers: headers
};

// After the request has been built and the POP access token has bee appended, the request can be executed using an API like "fetch"
fetch(endpoint, options)
    .then(response => response.json())
    .then(response => callback(response, endpoint))
    .catch(error => console.log(error));
});

Gestão de Chaves PoP

O esquema de autenticação Proof-of-Possession baseia-se num par de chaves criptográficas assimétricas para ligar o token de acesso ao navegador do utilizador. O MSAL Browser gera este par de chaves ao solicitar inicialmente um token de acesso ao serviço de autorização e armazena-o usando o IndexedDB. Este par de chaves criptográficas é então usado para assinar o SHR sempre que o token de acesso vinculado é solicitado silenciosamente.

No caso de atualizar um token de acesso vinculado, a MSAL elimina o par de chaves criptográficas gerado ao solicitar o token de acesso vinculado expirado, gera um novo par de chaves criptográficas para o novo token de acesso e armazena o novo par de chaves na keystore.

Funcionalidade avançada: Par de chaves criptográficas geridas por aplicação

Se optar por gerar o seu próprio par de chaves criptográficas, esta funcionalidade permite que a aplicação forneça o popKid como parâmetro de pedido. O MSAL JS assegura que o emissor do token incorpora o cnf no token, mas devolve o token emitido sem assinatura. Cabe à aplicação assinar o token de acesso antes de este ser encaminhado para o recurso de destino.

Tenha também em atenção que, se optares por tirar partido deste comportamento, deves assegurar-te de que os parâmetros de PoP restantes, com exceção de authenticationScheme, não estão definidos.

Porque é que os tokens de acesso são guardados de forma assíncrona

A maioria das credenciais MSAL e itens de cache, como ID Tokens por exemplo, podem ser armazenados e removidos de forma síncrona. Isto deve-se ao facto de estes itens de cache estarem armazenados em ou localStoragesessionStorage (que podem ser manipulados de forma síncrona), e não dependem de outros itens armazenados que tenham restrições de acesso assíncronas.

Ao contrário de outros itens de cache, Access Tokens são guardados na cache de forma assíncrona. A razão para isto é que, no caso de um token de acesso estar vinculado a um par de chaves criptográficas, que está armazenado em IndexedDB, substituir o token de acesso implica também substituir o par de chaves criptográficas. Dado que remover e escrever chaves em IndexedDB são operações assíncronas, o processo de guardar um token de acesso torna-se inevitavelmente assíncrono por consequência.

Exemplos de código

• Aquisição de tokens PoP numa SPA JavaScript