Udostępnij za pośrednictwem

Używanie certyfikatu klienta do uwierzytelniania w aplikacji internetowej Node.js

  • Artykuł

Dotyczy:Biały okrąg z szarym symbolem X. Dzierżawcy siły roboczej — dzierżawcy zewnętrzni Zielony okrąg z białym symbolem znacznika wyboru. (dowiedz się więcej)

Tożsamość zewnętrzna Microsoft Entra obsługuje dwa typy uwierzytelniania dla poufnych aplikacji klienckich; uwierzytelnianie oparte na hasłach (takie jak wpis tajny klienta) i uwierzytelnianie oparte na certyfikatach. Aby uzyskać wyższy poziom zabezpieczeń, zalecamy użycie certyfikatu (zamiast klucza tajnego klienta) jako poświadczenia w poufnych aplikacjach klienckich.

W środowisku produkcyjnym należy zakupić certyfikat podpisany przez dobrze znany urząd certyfikacji, a następnie użyć usługi Azure Key Vault do zarządzania dostępem do certyfikatów i okresem istnienia. Jednak na potrzeby testowania można utworzyć certyfikat z podpisem własnym i skonfigurować aplikacje do uwierzytelniania za pomocą niego.

Z tego artykułu dowiesz się, jak wygenerować certyfikat z podpisem własnym przy użyciu usługi Azure Key Vault w witrynie Azure Portal, programie OpenSSL lub programie PowerShell. Jeśli masz już wpis tajny klienta, dowiesz się, jak bezpiecznie go usunąć.

W razie potrzeby można również programowo utworzyć certyfikat z podpisem własnym przy użyciu bibliotek klienckich .NET, Node.js, Go, Python lub Java .

Wymagania wstępne

Tworzenie certyfikatu z podpisem własnym

Jeśli masz istniejący certyfikat z podpisem własnym na komputerze lokalnym, możesz pominąć ten krok, a następnie przejść do sekcji Przekazywanie certyfikatu do rejestracji aplikacji.

Możesz użyć usługi Azure Key Vault do wygenerowania certyfikatu z podpisem własnym dla aplikacji. Korzystając z usługi Azure Key Vault, możesz korzystać z korzyści, takich jak przypisywanie urzędu certyfikacji partnera i automatyzowanie rotacji certyfikatów.

Jeśli masz istniejący certyfikat z podpisem własnym w usłudze Azure Key Vault i chcesz go używać bez pobierania, pomiń ten krok, a następnie przejdź do sekcji Używanie certyfikatu z podpisem własnym bezpośrednio z usługi Azure Key Vault. W przeciwnym razie wykonaj następujące kroki, aby wygenerować certyfikat

  1. Wykonaj kroki opisane w temacie Ustawianie i pobieranie certyfikatu z usługi Azure Key Vault przy użyciu witryny Azure Portal , aby utworzyć i pobrać certyfikat.

  2. Po utworzeniu certyfikatu pobierz zarówno plik .cer , jak i plik pfx , taki jak ciam-client-app-cert.cer i ciam-client-app-cert.pfx. Plik .cer zawiera klucz publiczny i jest tym, co przekazujesz do centrum administracyjnego firmy Microsoft Entra.

  3. W terminalu uruchom następujące polecenie, aby wyodrębnić klucz prywatny z pliku pfx . Po wyświetleniu monitu o wpisanie frazy pass wystarczy nacisnąć Enter , jeśli nie chcesz go ustawić. W przeciwnym razie wpisz wybraną frazę dostępu:

    openssl pkcs12 -in ciam-client-app-cert.pfx -nocerts -out ciam-client-app-cert.key

    Plik ciam-client-app-cert.key jest używany w aplikacji.

Przekazywanie certyfikatu do rejestracji aplikacji

Aby użyć certyfikatu aplikacji klienckiej, musisz skojarzyć aplikację zarejestrowaną w centrum administracyjnym firmy Microsoft Entra z certyfikatem:

  1. Zaloguj się do centrum administracyjnego firmy Microsoft Entra co najmniej jako administrator aplikacji.

  2. Jeśli masz dostęp do wielu dzierżaw, użyj ikony Ustawienia w górnym menu, aby przełączyć się do dzierżawy zewnętrznej z menu Katalogi i subskrypcje.

  3. Przejdź do aplikacji tożsamości>> Rejestracje aplikacji.

  4. Z listy rejestracji aplikacji wybierz aplikację, którą chcesz skojarzyć z certyfikatem, taką jak ciam-client-app.

  5. W obszarze Zarządzanie wybierz pozycję Certyfikaty i wpisy tajne.

  6. Wybierz pozycję Certyfikaty, a następnie wybierz pozycję Przekaż certyfikat.

  7. Wybierz ikonę Wybierz plik pliku, a następnie wybierz certyfikat, który chcesz przekazać, na przykład ciam-client-app-cert.pem lub ciam-client-app-cert.cer lub ciam-client-app-cert.crt.

  8. W polu Opis wpisz opis, taki jak certyfikat aplikacji klienckiej CIAM, a następnie wybierz pozycję Dodaj , aby przekazać certyfikat. Po przekazaniu certyfikatu zostaną wyświetlone wartości Odcisk palca, Data rozpoczęcia i Wygaśnięcie .

  9. Zarejestruj wartość odcisku palca do użycia później podczas konfigurowania aplikacji klienckiej.

Jeśli masz już wpis tajny klienta dla aplikacji, musisz go usunąć, aby uniknąć złośliwej aplikacji podszywającej się pod aplikację:

  1. Przejdź do karty Wpisy tajne klienta i wybierz ikonę Usuń .
  2. W wyświetlonym oknie podręcznym wybierz pozycję Tak.

Konfigurowanie aplikacji Node.js do używania certyfikatu

Po skojarzeniu rejestracji aplikacji z certyfikatem należy zaktualizować kod aplikacji, aby rozpocząć korzystanie z certyfikatu:

  1. Znajdź plik zawierający obiekt konfiguracji biblioteki MSAL, taki jak msalConfig w authConfig.js, a następnie zaktualizuj go, aby wyglądał podobnie do poniższego kodu. Jeśli masz obecny klucz tajny klienta, upewnij się, że został on usunięty:

    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
};

    W kodzie zastąp symbole zastępcze:

    • Add_Passphrase_Here przy użyciu frazy pass użytej do zaszyfrowania klucza prywatnego.

    • YOUR_CERT_THUMBPRINTza pomocą zarejestrowanej wcześniej wartości odcisku palca.

    • PATH_TO_YOUR_PRIVATE_KEY_FILE z ścieżką pliku do pliku klucza prywatnego.

    • Enter_the_Application_Id_Here za pomocą identyfikatora aplikacji (klienta) zarejestrowanej wcześniej aplikacji.

    • Enter_the_Tenant_Subdomain_Here i zastąp ją poddomeną Katalog (dzierżawa). Jeśli na przykład domena podstawowa dzierżawy to contoso.onmicrosoft.com, użyj polecenia contoso. Jeśli nie masz swojej nazwy dzierżawy, dowiedz się, jak odczytywać szczegóły dzierżawy.

    Zaszyfrowaliśmy klucz (zalecamy, aby to zrobić), dlatego musimy go odszyfrować przed przekazaniem go do obiektu konfiguracji biblioteki MSAL.

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

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

  2. Wykonaj kroki opisane w temacie Uruchamianie i testowanie aplikacji internetowej, aby przetestować aplikację .

Używanie certyfikatu z podpisem własnym bezpośrednio z usługi Azure Key Vault

Możesz użyć istniejącego certyfikatu bezpośrednio z usługi Azure Key Vault:

  1. Znajdź plik zawierający obiekt konfiguracji biblioteki MSAL, taki jak msalConfig w authConfig.js, a następnie usuń clientSecret właściwość:

    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/`, 
    },
    //...
};

  2. Zainstaluj interfejs wiersza polecenia platformy Azure, a następnie w konsoli wpisz następujące polecenie, aby się zalogować:

    az login --tenant YOUR_TENANT_ID

    Zastąp symbol zastępczy YOUR_TENANT_ID skopiowaną wcześniej identyfikatorem katalogu (dzierżawy).

  3. W konsoli wpisz następujące polecenie, aby zainstalować wymagane pakiety:

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

  4. W aplikacji klienckiej użyj następującego kodu, aby wygenerować thumbprint i 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();

    W kodzie zastąp symbole zastępcze:

    • ENTER_YOUR_KEY_VAULT_URL przy użyciu adresu URL usługi Azure Key Vault.

    • ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT z nazwą certyfikatu w usłudze Azure Key Vault.

  5. thumbprint Użyj wartości iprivateKey, aby zaktualizować konfigurację:

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

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

  6. Następnie przejdź do wystąpienia poufnego klienta, jak pokazano w metodzie getMsalInstance :

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

  7. Wykonaj kroki opisane w temacie Uruchamianie i testowanie aplikacji internetowej, aby przetestować aplikację .

Następne kroki

Instrukcje: