Использование сертификата клиента для проверки подлинности в веб-приложении Node.js

2025-04-30

Применяется: белый круг с серым символом X. Клиенты рабочей силы зеленый круг с символом белой галочки. Внешние клиенты (дополнительные сведения)

Внешний идентификатор Microsoft Entra поддерживает два типа проверки подлинности для конфиденциальных клиентских приложений; Проверка подлинности на основе паролей (например, секрет клиента) и проверка подлинности на основе сертификатов. Для повышения уровня безопасности рекомендуется использовать сертификат (вместо секрета клиента) в качестве учетных данных в конфиденциальных клиентских приложениях.

В рабочей среде необходимо приобрести сертификат, подписанный известным центром сертификации, а затем использовать Azure Key Vault для управления доступом к сертификатам и временем существования. Однако в целях тестирования можно создать самозаверяющий сертификат и настроить приложения для проверки подлинности с его помощью.

В этой статье описано, как создать самозаверяющий сертификат с помощью Azure Key Vault на портале Azure, OpenSSL или PowerShell. Если у вас уже есть секрет клиента, вы узнаете, как безопасно удалить его.

При необходимости вы также можете создать самозаверяющий сертификат программным способом с помощью клиентских библиотек .NET, Node.js, Go, Python или Java .

Необходимые условия

Node.js.
Visual Studio Code или другой редактор кода.
Внешний арендатор. Если у вас еще нет пробной версии, зарегистрируйтесь на бесплатную пробную версию.
OpenSSL или вы можете легко установить OpenSSL в Windows с помощью Chocolatey.
Windows PowerShell или подписку Azure.

Создание самозаверяющего сертификата

Если у вас есть самоподписанный сертификат на локальном компьютере, этот шаг можно пропустить, а затем перейти к загрузке сертификата для вашей регистрации приложения.

Azure Key Vault можно использовать для создания самозаверяющего сертификата для приложения. Используя Azure Key Vault, вы пользуетесь преимуществами, такими как назначение центра сертификации партнера (ЦС) и автоматизация смены сертификатов.

Если у вас есть самозаверяющий сертификат в Azure Key Vault и вы хотите использовать его, не скачивая его, пропустите этот шаг, а затем перейдите к использованию самозаверяющего сертификата непосредственно из Azure Key Vault. В противном случае выполните следующие действия, чтобы создать сертификат.

Выполните действия, описанные в разделе "Настройка" и получение сертификата из Azure Key Vault с помощью портала Azure , чтобы создать и скачать сертификат.
После создания сертификата скачайте файл .cer и PFX-файл , например ciam-client-app-cert.cer и ciam-client-app-cert.pfx. Файл .cer содержит открытый ключ и является тем, что вы отправляете в Центр администрирования Microsoft Entra.
В терминале выполните следующую команду, чтобы извлечь закрытый ключ из PFX-файла . При появлении запроса на ввод пассфразы просто нажмите клавишу ВВОД, если вы не хотите устанавливать её. В противном случае введите парольную фразу:
```
openssl pkcs12 -in ciam-client-app-cert.pfx -nocerts -out ciam-client-app-cert.key
```
Файл ciam-client-app-cert.key — это то, что вы используете в приложении.

Выполните действия, описанные в разделе "Создание самозаверяющего общедоступного сертификата" для проверки подлинности приложения. Убедитесь, что вы экспортируете общедоступный сертификат с его закрытым ключом. Для certificateName используйте ciam-client-app-cert.
В терминале выполните следующую команду, чтобы извлечь закрытый ключ из PFX-файла . При появлении запроса на ввод парольной фразы введите свою собственную парольную фразу.
```
openssl pkcs12 -in ciam-client-app-cert.pfx -nocerts -out ciam-client-app-cert.key
```

После выполнения этих действий у вас должен быть файл .cer и файл .key , например ciam-client-app-cert.key и ciam-client-app-cert.cer. Файл .key — это то, что вы используете в приложении. Файл .cer — это то, что вы отправляете в Центр администрирования Microsoft Entra.

В терминале выполните следующую команду. При появлении запроса на ввод парольной фразы введите свою собственную парольную фразу.

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

После завершения выполнения команды у вас должны появиться файлы .crt и .key, такие как ciam-client-app-cert.key и ciam-client-app-cert.crt. Файл .key — это то, что вы используете в приложении. Файл .cer — это то, что вы отправляете в Центр администрирования Microsoft Entra.

Загрузка сертификата в регистрацию вашего приложения

Чтобы использовать сертификат клиентского приложения, необходимо связать приложение, зарегистрированного в Центре администрирования Microsoft Entra, с сертификатом:

Войдите в центр администрирования Microsoft Entra с правами как минимум администратора приложений .
Если у вас есть доступ к нескольким тенантам, используйте значок Настройки в верхнем меню, чтобы переключиться на внешний тенант из меню Каталоги + Подписки.
Перейдите к Entra ID>Регистрация приложений.
В списке регистрации приложений выберите приложение, которое вы хотите связать с сертификатом, например ciam-client-app.
В разделе "Управление" выберите сертификаты и секреты.
Выберите сертификаты, а затем нажмите кнопку "Отправить сертификат".
Щелкните значок "Выбрать файл" , а затем выберите сертификат, который нужно отправить, например ciam-client-app-cert.pem или ciam-client-app-cert.cer или ciam-client-app-cert.crt.
В поле "Описание" введите описание, например сертификат клиентского приложения CIAM, а затем нажмите кнопку "Добавить ", чтобы отправить сертификат. После загрузки сертификата отображаются значения: отпечаток , дата начала - , и срок действия истекает - .
Для дальнейшего применения при настройке клиентского приложения, запишите значение отпечатка .

Если у вас уже настроен ключ доступа клиента для вашего приложения, необходимо удалить его, чтобы предотвратить возможность использования вашего приложения злоумышленниками.

Перейдите на вкладку секретов клиента и щелкните значок "Удалить ".
В появившемся всплывающем окне нажмите кнопку "Да".

Настройка приложения Node.js для использования сертификата

После связывания регистрации приложения с сертификатом необходимо обновить код приложения, чтобы начать использование сертификата:

Найдите файл, содержащий объект конфигурации MSAL, например msalConfig в authConfig.js, а затем обновите его, чтобы он выглядел примерно так, как показано в следующем коде. Если у вас есть секрет клиента, удалите его:

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

В коде замените заполнители:

Add_Passphrase_Here с фразой-паролем, которую вы использовали для шифрования вашего закрытого ключа.
YOUR_CERT_THUMBPRINT значение отпечатка , записанное ранее.
PATH_TO_YOUR_PRIVATE_KEY_FILE с указанием пути к файлу вашего закрытого ключа.
Enter_the_Application_Id_Here с идентификатором приложения (клиента), зарегистрированного ранее.
Enter_the_Tenant_Subdomain_Here и замените его поддоменом каталога (клиента). Например, если основной домен клиента contoso.onmicrosoft.com, используйте contoso. Если у вас нет имени арендатора, узнайте, как прочитать сведения об арендаторе.

Мы зашифровали ключ (рекомендуется это сделать), поэтому необходимо расшифровать его перед передачей в объект конфигурации MSAL.

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

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

Выполните действия, описанные в разделе "Запуск и тестирование веб-приложения" для тестирования приложения.

Использование самозаверяющего сертификата непосредственно из Azure Key Vault

Существующий сертификат можно использовать непосредственно из Azure Key Vault:

Найдите файл, содержащий объект конфигурации MSAL, например msalConfig в authConfig.js, а затем удалите 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/`, 
    },
    //...
};

Установите Azure CLI, а затем в консоли введите следующую команду для входа:
```
az login --tenant YOUR_TENANT_ID
```
Замените заполнитель YOUR_TENANT_ID идентификатором каталога (клиента), скопированным ранее.
В консоли введите следующую команду, чтобы установить необходимые пакеты:
```
npm install --save @azure/identity @azure/keyvault-certificates @azure/keyvault-secrets
```

В клиентском приложении используйте следующий код для создания thumbprint и 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();

В коде замените заполнители:

Замените ENTER_YOUR_KEY_VAULT_URL на URL-адрес вашего Azure Key Vault.
ENTER_THE_NAME_OF_YOUR_CERTIFICATE_ON_KEY_VAULT с именем вашего сертификата в Azure Key Vault.

Используйте значения thumbprint и privateKey для обновления конфигурации:

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

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

Затем создайте экземпляр конфиденциального клиента, как показано в методе getMsalInstance:
```
class AuthProvider {
    //...
    getMsalInstance(msalConfig) {
        return new msal.ConfidentialClientApplication(msalConfig);
    }
    //...
}
```
Выполните действия, описанные в разделе "Запуск и тестирование веб-приложения" для тестирования приложения.

Узнайте, как:

Войдите в систему пользователей и вызовите API в собственном Node.js веб-приложении.

Поделиться через

Использование сертификата клиента для проверки подлинности в веб-приложении Node.js

Необходимые условия

Создание самозаверяющего сертификата

Загрузка сертификата в регистрацию вашего приложения

Настройка приложения Node.js для использования сертификата

Использование самозаверяющего сертификата непосредственно из Azure Key Vault

Связанное содержимое

Обратная связь

Дополнительные ресурсы