Použití klientského certifikátu k ověřování ve webové aplikaci Node.js

Článek
06/13/2024

Platí pro: Bílý kruh se šedým symbolem X. Tenanti pracovních sil – externí tenanti Zelený kruh s bílým symbolem zaškrtnutí (další informace)

Microsoft Entra Externí ID podporuje dva typy ověřování pro důvěrné klientské aplikace; ověřování založené na heslech (například tajný klíč klienta) a ověřování na základě certifikátů. Pokud chcete vyšší úroveň zabezpečení, doporučujeme v důvěrných klientských aplikacích použít certifikát (místo tajného klíče klienta) jako přihlašovací údaje.

V produkčním prostředí byste měli zakoupit certifikát podepsaný dobře známou certifikační autoritou a pak použít Azure Key Vault ke správě přístupu k certifikátům a životnosti. Pro účely testování ale můžete vytvořit certifikát podepsaný svým držitelem a nakonfigurovat aplikace tak, aby se s ním ověřily.

V tomto článku se naučíte generovat certifikát podepsaný svým držitelem pomocí služby Azure Key Vault na webu Azure Portal, OpenSSL nebo PowerShellu. Pokud už tajný klíč klienta máte, dozvíte se, jak ho bezpečně odstranit.

V případě potřeby můžete také programově vytvořit certifikát podepsaný svým držitelem pomocí klientských knihoven .NET, Node.js, Go, Python nebo Java .

Požadavky

Node.js.
Visual Studio Code nebo jiný editor kódu
Externí tenant. Pokud ho ještě nemáte, zaregistrujte si bezplatnou zkušební verzi.
OpenSSL nebo můžete snadno nainstalovat OpenSSL ve Windows přes Chocolatey.
Windows PowerShell nebo předplatné Azure

Vytvoření certifikátu podepsaného jeho držitelem (self-signed certificate)

Pokud máte v místním počítači existující certifikát podepsaný svým držitelem, můžete tento krok přeskočit a přejít k nahrání certifikátu do registrace aplikace.

Azure Key Vault můžete použít k vygenerování certifikátu podepsaného svým držitelem pro vaši aplikaci. Pomocí služby Azure Key Vault získáte výhody, jako je například přiřazení partnerské certifikační autority (CA) a automatizace obměny certifikátů.

Pokud máte ve službě Azure Key Vault existující certifikát podepsaný svým držitelem a chcete ho použít bez jeho stažení, přeskočte tento krok a pak pokračujte použitím certifikátu podepsaného svým držitelem přímo ze služby Azure Key Vault. V opačném případě vygenerujte certifikát pomocí následujícího postupu.

Postupujte podle pokynů v tématu Nastavení a načtení certifikátu ze služby Azure Key Vault pomocí webu Azure Portal a vytvořte a stáhněte si certifikát.
Po vytvoření certifikátu stáhněte soubor .cer i soubor .pfx , například ciam-client-app-cert.cer a ciam-client-app-cert.pfx. Soubor .cer obsahuje veřejný klíč a je to, co nahrajete do centra pro správu Microsoft Entra.
V terminálu spusťte následující příkaz, který extrahuje privátní klíč ze souboru .pfx . Když se zobrazí výzva k zadání hesla, stiskněte klávesu Enter , pokud ji nechcete nastavit. V opačném případě zadejte heslo podle vašeho výběru:
```
openssl pkcs12 -in ciam-client-app-cert.pfx -nocerts -out ciam-client-app-cert.key
```
Soubor ciam-client-app-cert.key je to, co používáte ve své aplikaci.

Postupujte podle kroků v části Vytvoření veřejného certifikátu podepsaného svým držitelem k ověření vaší aplikace. Ujistěte se, že veřejný certifikát exportujete s jeho privátním klíčem. Pro použití certificateNameciam-client-app-cert.
V terminálu spusťte následující příkaz, který extrahuje privátní klíč ze souboru .pfx . Po zobrazení výzvy k zadání hesla zadejte heslo podle svého výběru:
```
openssl pkcs12 -in ciam-client-app-cert.pfx -nocerts -out ciam-client-app-cert.key
```

Po dokončení těchto kroků byste měli mít soubor .cer a soubor .key , například ciam-client-app-cert.key a ciam-client-app-cert.cer. Soubor .key je to, co používáte ve své aplikaci. Soubor .cer je to, co nahrajete do centra pro správu Microsoft Entra.

V terminálu spusťte následující příkaz. Po zobrazení výzvy k zadání hesla zadejte heslo podle svého výběru:

openssl req -x509 -newkey rsa:2048 -keyout ciam-client-app-cert.key -out ciam-client-app-cert.crt -subj "/CN=ciamclientappcert.com"

Po dokončení příkazu byste měli mít soubor .crt a .key , například ciam-client-app-cert.key a ciam-client-app-cert.crt. Soubor .key je to, co používáte ve své aplikaci. Soubor .cer je to, co nahrajete do centra pro správu Microsoft Entra.

Nahrání certifikátu do registrace aplikace

Pokud chcete použít certifikát klientské aplikace, musíte k certifikátu přidružit aplikaci, kterou jste zaregistrovali v Centru pro správu Microsoft Entra:

Přihlaste se do Centra pro správu Microsoft Entra jako alespoň správce aplikací.
Pokud máte přístup k více tenantům, pomocí ikony Nastavení v horní nabídce přepněte do externího tenanta z nabídky Adresáře a předplatná.
Přejděte k aplikacím> identit>Registrace aplikací.
V seznamu registrací aplikace vyberte aplikaci, kterou chcete přidružit k certifikátu, například ciam-client-app.
V části Spravovat vyberte Certifikáty a tajné kódy.
Vyberte Certifikáty a pak vyberte Nahrát certifikát.
Vyberte ikonu Vybrat soubor a pak vyberte certifikát, který chcete nahrát, například ciam-client-app-cert.pem nebo ciam-client-app-cert.cer nebo ciam-client-app-cert.crt.
Jako popis zadejte popis, například certifikát klientské aplikace CIAM, a pak vyberte Přidat , aby se certifikát nahrál. Po nahrání certifikátu se zobrazí hodnoty Kryptografický otisk, Počáteční datum a Konec platnosti .
Poznamenejte si hodnotu kryptografického otisku pro pozdější použití při konfiguraci klientské aplikace.

Pokud už máte pro svou aplikaci zavedený tajný klíč klienta, musíte ho odstranit, abyste se vyhnuli škodlivé aplikaci pro zosobnění aplikace:

Přejděte na kartu Tajné kódy klienta a vyberte ikonu Odstranit .
V automaticky otevíraných otevíraných oknech, které se zobrazí, vyberte Ano.

Konfigurace aplikace Node.js tak, aby používala certifikát

Jakmile přidružíte registraci aplikace k certifikátu, musíte aktualizovat kód aplikace, abyste mohli začít používat certifikát:

Vyhledejte soubor, který obsahuje objekt konfigurace MSAL, například msalConfig v authConfig.js, a aktualizujte ho tak, aby vypadal podobně jako v následujícím kódu. Pokud máte tajný klíč klienta, ujistěte se, že ho odeberete:

require('dotenv').config();
const fs = require('fs'); //// import the fs module for reading the key file
const crypto = require('crypto');
const TENANT_SUBDOMAIN = process.env.TENANT_SUBDOMAIN || 'Enter_the_Tenant_Subdomain_Here';
const REDIRECT_URI = process.env.REDIRECT_URI || 'http://localhost:3000/auth/redirect';
const POST_LOGOUT_REDIRECT_URI = process.env.POST_LOGOUT_REDIRECT_URI || 'http://localhost:3000';

const privateKeySource = fs.readFileSync('PATH_TO_YOUR_PRIVATE_KEY_FILE')

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

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

/**
 * Configuration object to be passed to MSAL instance on creation.
 * For a full list of MSAL Node configuration parameters, visit:
 * https://github.com/AzureAD/microsoft-authentication-library-for-js/blob/dev/lib/msal-node/docs/configuration.md
 */
    const msalConfig = {
        auth: {
            clientId: process.env.CLIENT_ID || 'Enter_the_Application_Id_Here', // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
            authority: process.env.AUTHORITY || `https://${TENANT_SUBDOMAIN}.ciamlogin.com/`, 
            clientCertificate: {
                thumbprint: "YOUR_CERT_THUMBPRINT", // replace with thumbprint obtained during step 2 above
                privateKey: privateKey
            }
        },
        //... Rest of code in the msalConfig object
    };

module.exports = {
    msalConfig,
    REDIRECT_URI,
    POST_LOGOUT_REDIRECT_URI,
    TENANT_SUBDOMAIN
};

V kódu nahraďte zástupné symboly:

Add_Passphrase_Here pomocí hesla, který jste použili k šifrování privátního klíče.
YOUR_CERT_THUMBPRINTs hodnotou kryptografického otisku, kterou jste si poznamenali dříve.
PATH_TO_YOUR_PRIVATE_KEY_FILE s cestou k souboru privátního klíče.
Enter_the_Application_Id_Here s ID aplikace (klienta) aplikace, kterou jste zaregistrovali dříve.
Enter_the_Tenant_Subdomain_Here a nahraďte ji subdoménou adresáře (tenanta). Pokud je například primární doména vašeho tenanta contoso.onmicrosoft.com, použijte contoso. Pokud nemáte název tenanta, přečtěte si, jak si přečíst podrobnosti o tenantovi.

Klíč jsme zašifrovali (doporučujeme to udělat), takže ho musíme před předáním do objektu konfigurace MSAL dešifrovat.

//...
const privateKeyObject = crypto.createPrivateKey({
    key: privateKeySource,
    passphrase: 'Add_Passphrase_Here',
    format: 'pem'
});

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

K otestování aplikace použijte postup spuštění a otestování webové aplikace .

Použití certifikátu podepsaného svým držitelem přímo ze služby Azure Key Vault

Existující certifikát můžete použít přímo ze služby Azure Key Vault:

Vyhledejte soubor, který obsahuje objekt konfigurace MSAL, například msalConfig v authConfig.js, a pak tuto vlastnost odeberte clientSecret :

const msalConfig = {
    auth: {
        clientId: process.env.CLIENT_ID || 'Enter_the_Application_Id_Here', // 'Application (client) ID' of app registration in Azure portal - this value is a GUID
        authority: process.env.AUTHORITY || `https://${TENANT_SUBDOMAIN}.ciamlogin.com/`, 
    },
    //...
};

Nainstalujte Azure CLI a potom do konzoly zadejte následující příkaz pro přihlášení:
```
az login --tenant YOUR_TENANT_ID
```
Zástupný text YOUR_TENANT_ID nahraďte ID adresáře (tenanta), které jste zkopírovali dříve.

V konzole zadejte následující příkaz, který nainstaluje požadované balíčky:

npm install --save @azure/identity @azure/keyvault-certificates @azure/keyvault-secrets

V klientské aplikaci použijte následující kód k vygenerování thumbprint a privateKey;

const identity = require("@azure/identity");
const keyvaultCert = require("@azure/keyvault-certificates");
const keyvaultSecret = require('@azure/keyvault-secrets');

const KV_URL = process.env["KEY_VAULT_URL"] || "ENTER_YOUR_KEY_VAULT_URL"
const CERTIFICATE_NAME = process.env["CERTIFICATE_NAME"] || "ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT";

// Initialize Azure SDKs
const credential = new identity.DefaultAzureCredential();
const certClient = new keyvaultCert.CertificateClient(KV_URL, credential);
const secretClient = new keyvaultSecret.SecretClient(KV_URL, credential);

async function getKeyAndThumbprint() {

    // Grab the certificate thumbprint
    const certResponse = await certClient.getCertificate(CERTIFICATE_NAME).catch(err => console.log(err));
    const thumbprint = certResponse.properties.x509Thumbprint.toString('hex')

    // When you upload a certificate to Key Vault, a secret containing your private key is automatically created
    const secretResponse = await secretClient.getSecret(CERTIFICATE_NAME).catch(err => console.log(err));;

    // secretResponse contains both public and private key, but we only need the private key
    const privateKey = secretResponse.value.split('-----BEGIN CERTIFICATE-----\n')[0]
}

getKeyAndThumbprint();

V kódu nahraďte zástupné symboly:

ENTER_YOUR_KEY_VAULT_URL s adresou URL služby Azure Key Vault.
ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT s názvem vašeho certifikátu ve službě Azure Key Vault.

thumbprint K aktualizaci konfigurace použijte hodnoty a privateKey hodnoty:

let clientCert = {
    thumbprint: thumbprint, 
    privateKey: privateKey,
};

msalConfig.auth.clientCertificate = clientCert; //For this to work, you can't declares your msalConfig using const modifier

Pak pokračujte vytvořením instance důvěrného klienta, jak je znázorněno v getMsalInstance metodě:

class AuthProvider {
    //...
    getMsalInstance(msalConfig) {
        return new msal.ConfidentialClientApplication(msalConfig);
    }
    //...
}

K otestování aplikace použijte postup spuštění a otestování webové aplikace .

Další kroky

Naučte se:

Přihlaste se uživatele a volejte rozhraní API ve vlastní webové aplikaci Node.js.

Sdílet prostřednictvím