Usando credenciais de certificado com o MSAL Node

Você pode criar aplicativos cliente confidenciais com o Nó MSAL (aplicativos Web, aplicativos daemon etc. Uma credencial de cliente é obrigatória para clientes confidenciais.

Pré-requisitos

• Uma boa compreensão de como Inicializar aplicativos cliente confidenciais.

Você pode criar aplicativos cliente confidenciais com o Nó MSAL (aplicativos Web, aplicativos daemon etc. Uma credencial de cliente é obrigatória para clientes confidenciais. A credencial do cliente pode ser:

• managed identity: este é um cenário sem certificado, em que a confiança é estabelecida por meio da infraestrutura Azure. Nenhum gerenciamento de segredo/certificado é necessário. O MSAL ainda não oferece esse recurso, mas você pode usar o SDK de Identidade do Azure. Consulte a documentação sobre identidades gerenciadas para recursos do Azure
• clientSecret: uma sequência de caracteres secreta gerada durante o registro do aplicativo ou atualizada após o registro para um aplicativo existente. Isso não é recomendado para produção.
• clientCertificate: um conjunto de certificados durante o registro do aplicativo. O certificado precisa ter a chave privada, pois é usado para assinar uma declaração gerada pela MSAL. É thumbprintSha256 uma impressão digital X.509 SHA-256 do certificado e privateKey a chave privada codificada em PEM.
• clientAssertion: em vez de permitir que a MSAL crie uma declaração, o desenvolvedor do aplicativo assume o controle. Útil para adicionar declarações extras à declaração ou para usar KeyVault para assinatura, em vez de um certificado local. O certificado usado para assinar a declaração ainda precisa ser definido durante o registro do aplicativo.

Observação: aplicativos próprios talvez precisem enviar também x5c. Esta é a cadeia de certificados X.509 usada em cenários de autenticação de nome do titular/emissor.

Usando segredos e certificados com segurança

Os segredos nunca devem ser codificados. O pacote dotenv npm pode ser usado para armazenar segredos ou certificados em um arquivo .env (localizado no diretório raiz do projeto) que deve ser incluído em .gitignore para evitar uploads acidentais dos segredos.

Os certificados também podem ser lidos de arquivos por meio do módulo fs do NodeJS. No entanto, eles nunca devem ser armazenados no diretório do projeto. Os aplicativos de produção devem buscar certificados de Azure KeyVault ou outros cofres de chaves seguros.

Consulte certificados e segredos para obter mais informações.

Confira o exemplo de MSAL: auth-code-with-certs

Registrando certificados

Se você não tiver um certificado, poderá criar um certificado autoassinado usando o PowerShell ou usando Azure KeyVault.

Você precisa carregar seu certificado para Microsoft Entra ID.

1. Navegue até Azure portal e selecione o registro do aplicativo Microsoft Entra.
2. Selecione o painel Certificados e segredos à esquerda.
3. Clique em Carregar certificado e selecione o arquivo de certificado a ser carregado (por exemplo , example.crt).
4. Clique em Adicionar. Depois que o certificado é carregado, a impressão digital (SHA-256),a data de início e os valores de expiração são exibidos.

Para obter mais informações, consulte: Registrar seu certificado com plataforma de identidade da Microsoft

Inicializando o MSAL Node com certificados

const msal = require('@azure/msal-node');
require('dotenv').config(); // process.env now has the values defined in a .env file

const config = {
    auth: {
        clientId: "YOUR_CLIENT_ID",
        authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
        clientCertificate: {
            thumbprintSha256: process.env.thumbprint,
            privateKey: process.env.privateKey,
        }
    }
};

// Create msal application object
const cca = new msal.ConfidentialClientApplication(config);

Ambos thumbprintSha256 e privateKey devem ser cadeias de caracteres. privateKey também se espera que esteja no seguinte formato (PKCS#8):

-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIJQwIBADANBgkqhkiG9w0BAQEFAASCCS0wggkpAgEAAoICAQDkpKPrsfpIijS3
z2HCpDsa7dxOsKIrm7F1AtGBjyB0yVDjlh/FA7jT5sd2ypBh3FVsZGJudQsLRKfE
// ...
-----END ENCRYPTED PRIVATE KEY-----

openssl pkcs8 -topk8 -inform PEM -outform PEM -in example.key -out example.key

Se você tiver criptografado sua chave privada (ou se sua chave privada já estiver criptografada) com uma frase secreta, será necessário descriptografá-la antes de passá-la para o nó MSAL.

Importante: nunca codificar senhas no código-fonte. A chave privada do certificado e a senha de desscriptografia opcional devem ser buscadas de um local seguro (por exemplo, Azure KeyVault) e implantadas com segurança com sua api Web.

Isso pode ser feito usando o módulo de criptografia do Node. Use o createPrivateKey() método para analisar e exportar sua chave:

const fs = require('fs');
const crypto = require('crypto');

const privateKeySource = fs.readFileSync('<path_to_key>/example.key')

const privateKeyObject = crypto.createPrivateKey({
    key: privateKeySource,
    passphrase: process.env.YOUR_PASSPHRASE,
    format: 'pem'
});

const privateKey = privateKeyObject.export({
    format: 'pem',
    type: 'pkcs8'
});

(Opcional) Convertendo pfx em pem

O OpenSSL pode ser usado para converter arquivos de certificado codificados em pfx em pem:

    openssl pkcs12 -in certificate.pfx -out certificate.pem

Se a conversão precisar acontecer programaticamente, talvez você precise contar com um pacote de terceiros, pois Node.js não oferece nenhum método nativo para isso. Por exemplo, usando uma implementação popular do TLS, como o node-forge, você pode fazer:

const forge = require('node-forge');

/**
 * @param {string} pfx: certificate + private key combination in pfx format
 * @param {string} passphrase: passphrase used to encrypt pfx file
 * @returns {Object}
 */
function convertPFX(pfx, passphrase = null) {

    const asn = forge.asn1.fromDer(forge.util.decode64(pfx));
    const p12 = forge.pkcs12.pkcs12FromAsn1(asn, true, passphrase);

    // Retrieve key data
    const keyData = p12.getBags({ bagType: forge.pki.oids.pkcs8ShroudedKeyBag })[forge.pki.oids.pkcs8ShroudedKeyBag]
        .concat(p12.getBags({ bagType: forge.pki.oids.keyBag })[forge.pki.oids.keyBag]);

    // Retrieve certificate data
    const certBags = p12.getBags({ bagType: forge.pki.oids.certBag })[forge.pki.oids.certBag];
    const certificate = forge.pki.certificateToPem(certBags[0].cert)

    // Convert a Forge private key to an ASN.1 RSAPrivateKey
    const rsaPrivateKey = forge.pki.privateKeyToAsn1(keyData[0].key);

    // Wrap an RSAPrivateKey ASN.1 object in a PKCS#8 ASN.1 PrivateKeyInfo
    const privateKeyInfo = forge.pki.wrapRsaPrivateKey(rsaPrivateKey);

    // Convert a PKCS#8 ASN.1 PrivateKeyInfo to PEM
    const privateKey = forge.pki.privateKeyInfoToPem(privateKeyInfo);

    console.log("Converted certificate: \n", certificate);
    console.log("Converted key: \n", privateKey);

    return {
        certificate: certificate,
        key: privateKey
    };
}

(Opcional) Criando um servidor HTTPS

O protocolo OAuth 2.0 recomenda usar uma conexão HTTPS sempre que possível. A maioria dos serviços de nuvem, como Serviço de Aplicativo do Azure, fornecerá conexão HTTPS por padrão por proxy. Se para fins de teste você quiser configurar seu próprio servidor HTTPS, consulte a documentação do Node.js para obter diretrizes sobre como criar um servidor HTTPS.

Você também precisará adicionar seus certificados autoassinados àcadeia de chaves do / de credenciais do sistema operacional para ignorar a política de segurança do navegador. Você ainda poderá ver um aviso em seu navegador posteriormente (por exemplo, Chrome).

• Para Windows usuários, siga o guia aqui: Como exibir certificados com o snap-in do MMC.

• Para usuários do Linux e do MacOS, consulte a documentação do sistema operacional sobre como instalar certificados.

Problemas comuns

Em alguns casos, você pode receber um erro do Microsoft Entra ID ao tentar se autenticar usando certificados, como o erro AADSTS700027: Client assertion contains an invalid signature, indicando que os certificados e/ou as chaves privadas que você usa para inicializar o MSAL Node estão mal formatados. Um motivo comum para isso é que o certificado/cadeia de caracteres de chave privada que você está fornecendo ao Nó da MSAL contém caracteres inesperados, como carros de retorno (\r) ou linhas novas (\n):

-----BEGIN CERTIFICATE-----\nMIIDDzCCAfegAwIBAgIJAMkyzQVK88NHMA0GCSqGSIb3DQEBBQUAMIGCMQswCQYDVQQGEwJTRTESMBAGA1UECBMJU3RvY2tob2xtMQ4wDAYDVQQHEwVLaXN0YTEQMA4G0fbkqbKulrchGbNgkankZtEVg4PGjobZq7B+njvcVa7SsWF/WLq5AUbw==\r\n-----END CERTIFICATE-----

Alternativamente, seu arquivo de certificado / chave pode conter bag attributes:

Bag Attributes
    localKeyID: 28 B5 8E 16 11 88 E9 00 58 D5 76 30 12 B9 59 B8 E4 CE 7C AA
subject=/C=UK/ST=Suffolk/L=Ipswich/O=Example plc/CN=alice
issuer=/C=UK/ST=Suffolk/L=Ipswich/O=Example plc/CN=Certificate Authority/emailAddress=ca@example.com\n
-----BEGIN CERTIFICATE-----
MIIDDzCCAfegAwIBAgIJAMkyzQVK88NHMA0GCSqGSIb3DQEBBQUAMIGCMQswCQYD
VQQGEwJTRTESMBAGA1UECBMJU3RvY2tob2xtMQ4wDAYDVQQHEwVLaXN0YTEQMA4G
0fbkqbKulrchGbNgkankZtEVg4PGjo+Y8MdMjtfSZB29hwYvfMX09jzJ68ZqmpYQ
njvcVtLbEZN5OGCkaslb/f2OxLbsUNgIbws538WnaaufDvKmQe2kUdWmpl9Wn9Bf
bZq7B+njvcVa7SsWF/WLq5AUbw==
-----END CERTIFICATE-----

Nesses casos, você é responsável por limpar a string antes de passá-la para a configuração do MSAL Node. Por exemplo:

const msal = require('@azure/msal-node');
const fs = require('fs');

const privateKeySource = fs.readFileSync('<path_to_key>/certs/example.key');
const privateKey = Buffer.from(privateKeySource, 'base64').toString().replace(/\r/g, "").replace(/\n/g, "");

const config = {
    auth: {
        clientId: "YOUR_CLIENT_ID",
        authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
        clientCertificate: {
            thumbprintSha256: process.env.thumbprint,
            privateKey: privateKey,
        }
    }
};

// Create msal application object
const cca = new msal.ConfidentialClientApplication(config);

Consulte também

• Credenciais de certificado de autenticação do aplicativo da plataforma de identidade da Microsoft
• Criar um certificado público autoassinado para autenticar seu aplicativo
• Vários tipos/extensões de arquivo de certificado SSL/TLS