MSAL Düğümü ile sertifika kimlik bilgilerini kullanma

MSAL Node (web uygulamaları, daemon uygulamaları vb.) ile gizli istemci uygulamaları oluşturabilirsiniz. Gizli istemciler için istemci kimlik bilgileri zorunludur.

Prerequisites

• Gizli istemci uygulamalarını başlatma konusunda iyi derecede bilgi sahibi olmak.

MSAL Node (web uygulamaları, daemon uygulamaları vb.) ile gizli istemci uygulamaları oluşturabilirsiniz. Gizli istemciler için istemci kimlik bilgileri zorunludur. İstemci kimlik bilgileri şu şekilde olabilir:

• managed identity: Bu, Azure altyapısı aracılığıyla güvenin oluşturulduğu sertifikasız bir senaryodur. Gizli anahtar / sertifika yönetimi gerekmez. MSAL henüz bu özelliği uygulamaz, ancak bunun yerine Azure Kimlik SDK'sı kullanabilirsiniz. Azure kaynakları için yönetilen kimlikler belgelerine bakın
• clientSecret: Uygulama kaydı sırasında oluşturulan veya mevcut bir uygulama için güncelleştirilmiş bir gizli dizi dizesi. Bu, üretim için önerilmez.
• clientCertificate: uygulama kaydı sırasında ayarlanan bir sertifika. Sertifikanın özel anahtara sahip olması gerekir, çünkü MSAL tarafından oluşturulan bir onaylamayı imzalamak için kullanılır. thumbprintSha256, sertifikanın X.509 SHA-256 parmak izidir ve privateKey PEM ile kodlanmış özel anahtardır.
• clientAssertion: MSAL'nin onay oluşturmasına izin vermek yerine uygulama geliştiricisi denetimi ele alır. Onay işlemine ek talepler eklemek veya yerel sertifika yerine imzalama için KeyVault kullanmak için kullanışlıdır. Onaylama işlemini imzalamak için kullanılan sertifikanın yine de uygulama kaydı sırasında ayarlanması gerekir.

Not: 1p uygulamalarının ayrıca x5c göndermesi gerekebilir. Bu, konu adı/veren kimlik doğrulaması senaryolarında kullanılan X.509 sertifika zinciridir.

Gizli anahtarların ve sertifikaların güvenli kullanımı

Gizli bilgiler asla doğrudan koda gömülmemelidir. Dotenv npm paketi, gizli dizilerin yanlışlıkla karşıya yüklenmesini önlemek için .gitignore dosyasına eklenmesi gereken bir .env dosyasında (projenin kök dizininde bulunur) gizli dizileri veya sertifikaları depolamak için kullanılabilir.

Sertifikalar NodeJS'nin fs modülü aracılığıyla dosyalardan da okunabilir. Ancak, bunlar hiçbir zaman projenin dizininde depolanmamalıdır. Üretim uygulamaları Azure KeyVault veya diğer güvenli anahtar kasalarından sertifika getirmelidir.

Daha fazla bilgi için lütfen sertifikalar ve gizli anahtarlar bölümüne bakın.

MSAL örneğine bakın: auth-code-with-certs

Sertifikaları kaydetme

Sertifikanız yoksa, PowerShell kullanarak veya Azure KeyVault kullanarak otomatik olarak imzalanan bir sertifika oluşturabilirsiniz.

Sertifikanızı Microsoft Entra ID yüklemeniz gerekir.

1. Azure portalına gidin ve Microsoft Entra uygulama kaydınızı seçin.
2. Soldaki Sertifikalar ve gizli anahtarlar bölümünü seçin.
3. Sertifika Yükle düğmesine tıklayın ve yüklemek istediğiniz sertifika dosyasını seçin (ör. example.crt).
4. Ekle'yi tıklatın. Sertifika karşıya yüklendikten sonra parmak izi (SHA-256), başlangıç tarihi ve süre sonu değerleri görüntülenir.

Daha fazla bilgi için bkz.: Sertifikanızı Microsoft kimlik platformuna kaydetme

MSAL Node'u sertifikaları kullanarak başlatma

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

Hem thumbprintSha256 hem de privateKey değerlerinin dizge olması beklenir. privateKey aşağıdaki biçimde olması beklenir (PKCS#8):

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

Note

Alternatif olarak, özel anahtarınız (şifrelenmemiş -----BEGIN PRIVATE KEY-----) veya (-----BEGIN RSA PRIVATE KEY-----) ile başlayabilir. Bu biçimler de izin verilebilir. Aşağıdakiler, uyumlu herhangi bir anahtarı PKCS#8 anahtar türüne dönüştürmek için kullanılabilir:

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

Özel anahtarınızı bir geçiş tümceciğiyle şifrelediyseniz (veya özel anahtarınız zaten şifrelenmişse) MSAL Düğümü'ne geçirmeden önce şifresini çözmeniz gerekir.

Önemli: Kaynak kodunda parolaları hiçbir zaman sabit kodlamayın. Hem sertifika özel anahtarı hem de isteğe bağlı şifreleme parolası güvenli bir konumdan (örneğin, KeyVault Azure) getirilmeli ve web api'nizle güvenli bir şekilde dağıtılmalıdır.

Bu, Node'un şifreleme modülü kullanılarak yapılabilir. createPrivateKey() Anahtarınızı ayrıştırmak ve dışarı aktarmak için yöntemini kullanın:

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

(İsteğe bağlı) pfx'i pem'e dönüştürme

OpenSSL , pfx kodlanmış sertifika dosyalarını pem'e dönüştürmek için kullanılabilir:

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

Dönüştürmenin program aracılığıyla gerçekleşmesi gerekiyorsa, Node.js bunun için yerel bir yöntem sunmaması nedeniyle üçüncü taraf bir pakete güvenmeniz gerekebilir. Örneğin node-forge gibi popüler bir TLS uygulamasını kullanarak şunları yapabilirsiniz:

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

(İsteğe bağlı) HTTPS sunucusu oluşturma

OAuth 2.0 protokolü mümkün olduğunca HTTPS bağlantısı kullanılmasını önerir. Azure App Service gibi çoğu bulut hizmeti varsayılan olarak proxy aracılığıyla HTTPS bağlantısı sağlar. Test amacıyla kendi HTTPS sunucunuzu kurmak istiyorsanız, HTTPS sunucusu oluşturma yönergeleri için Node.js belgelerine bakın.

Ayrıca tarayıcının güvenlik ilkesini atlamak için otomatik olarak imzalanan sertifikalarınızı işletim sisteminizin / anahtar zincirine eklemeniz gerekir. Daha sonra tarayıcınızda hala bir uyarı görebilirsiniz (ör. Chrome).

• Windows kullanıcıları için buradaki kılavuzu izleyin: Nasıl yapılır: MMC ek bileşeniyle sertifikaları görüntüleme.

• Linux ve MacOS kullanıcıları için lütfen sertifikaların nasıl yükleneceğiyle ilgili işletim sistemi belgelerinize bakın.

Warning

Yukarıdaki komutları çalıştırmak için yönetici ayrıcalıklarına ihtiyacınız olabilir.

Yaygın sorunlar

Bazı durumlarda, sertifikaları kullanarak kimlik doğrulaması yapmaya çalışırken Microsoft Entra ID’den, MSAL Node’u başlatmak için kullandığınız sertifikaların ve/veya özel anahtarların hatalı biçimde oluşturulduğunu belirten AADSTS700027: Client assertion contains an invalid signature hatası gibi bir hata alabilirsiniz. Bunun yaygın nedenlerinden biri, MSAL Node’a sağladığınız sertifika / özel anahtar dizesinin, satır başı karakterleri (\r) veya yeni satırlar (\n) gibi beklenmeyen karakterler içermesidir:

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

Alternatif olarak, sertifikanız / anahtar dosyanız bag öznitelikleri içerebilir:

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

Böyle durumlarda, dizeyi MSAL Node yapılandırmasına iletmeden önce temizlemek sizin sorumluluğunuzdadır. Örneğin:

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

Ayrıca bakınız

• Microsoft kimlik platformu uygulama kimlik doğrulama sertifikası kimlik bilgileri
• Uygulamanızın kimliğini doğrulamak için otomatik olarak imzalanan bir ortak sertifika oluşturma
• Çeşitli SSL/TLS Sertifika Dosya Türleri/Uzantıları