Node.js uygulamasını ADAL'dan MSAL'ye geçirme
Düğüm için Microsoft Kimlik Doğrulama Kitaplığı (MSAL Node) artık Microsoft kimlik platformu kayıtlı uygulamalarınız için kimlik doğrulamasını ve yetkilendirmeyi etkinleştirmek için önerilen SDK'dır. Bu makale, uygulamalarınızı Düğüm için Active Directory Kimlik Doğrulama Kitaplığı'ndan (ADAL Düğümü) MSAL Düğümü'ne geçirmek için izlenmesi gereken önemli adımları kapsar.
Önkoşullar
- Düğüm sürüm 10, 12, 14, 16 veya 18. Sürüm desteğiyle ilgili nota bakın
Uygulama kayıt ayarlarını güncelleştirme
ADAL Düğümü ile çalışırken büyük olasılıkla Azure AD v1.0 uç noktasını kullanıyordunuz. ADAL'dan MSAL'ye geçen uygulamalar Azure AD v2.0 uç noktasına geçmelidir.
MSAL'yi yükleme ve içeri aktarma
- npm aracılığıyla MSAL Node paketini yükleyin:
npm install @azure/msal-node
- Bundan sonra kodunuzda MSAL Düğümünü içeri aktarin:
const msal = require('@azure/msal-node');
- Son olarak, ADAL Node paketini kaldırın ve kodunuzdaki başvuruları kaldırın:
npm uninstall adal-node
MSAL'ı başlatma
ADAL Düğümü'nde, farklı kimlik doğrulama akışlarında kullanabileceğiniz yöntemleri (örneğin, acquireTokenWithAuthorizationCode
web uygulamaları için) kullanıma sunan bir AuthenticationContext
nesne başlatırsınız. Başlatılırken, tek zorunlu parametre yetkili URI'dir:
var adal = require('adal-node');
var authorityURI = "https://login.microsoftonline.com/common";
var authenticationContex = new adal.AuthenticationContext(authorityURI);
MSAL Node'da bunun yerine iki alternatif vardır: Mobil uygulama veya masaüstü uygulaması oluşturuyorsanız bir nesne örneği oluşturursunuz PublicClientApplication
. Oluşturucu en azından parametresini clientId
içeren bir yapılandırma nesnesi bekler. Belirtmezseniz MSAL, yetkili URI'sini https://login.microsoftonline.com/common
varsayılan olarak kullanır.
const msal = require('@azure/msal-node');
const pca = new msal.PublicClientApplication({
auth: {
clientId: "YOUR_CLIENT_ID"
}
});
Not
v2.0'da yetkiliyi https://login.microsoftonline.com/common
kullanırsanız, kullanıcıların herhangi bir Microsoft Entra kuruluşuyla veya kişisel bir Microsoft hesabıyla (MSA) oturum açmasına izin verirsiniz. MSAL Node'da, herhangi bir Microsoft Entra hesabıyla (ADAL Düğümü ile aynı davranış) oturum açmayı kısıtlamak istiyorsanız, bunun yerine kullanın https://login.microsoftonline.com/organizations
.
Öte yandan, bir web uygulaması veya daemon uygulaması oluşturuyorsanız bir ConfidentialClientApplication
nesne örneği oluşturursunuz. Bu tür uygulamalarla istemci gizli dizisi veya sertifika gibi bir istemci kimlik bilgisi sağlamanız da gerekir:
const msal = require('@azure/msal-node');
const cca = new msal.ConfidentialClientApplication({
auth: {
clientId: "YOUR_CLIENT_ID",
clientSecret: "YOUR_CLIENT_SECRET"
}
});
ADAL'ın AuthenticationContext
aksine hem hem ConfidentialClientApplication
de PublicClientApplication
, bir istemci kimliğine bağlıdır. Başka bir deyişle, uygulamanızda kullanmak istediğiniz farklı istemci kimlikleriniz varsa, her bir örnek için yeni bir MSAL örneği oluşturmanız gerekir. Daha fazla bilgi için bkz. MSAL Düğümünün Başlatılması
MSAL'yi yapılandırma
Microsoft kimlik platformu üzerinde uygulama oluştururken, uygulamanız kimlik doğrulamasıyla ilgili birçok parametre içerir. ADAL Düğümü'nde nesnenin AuthenticationContext
örneği oluşturabileceğiniz sınırlı sayıda yapılandırma parametresi vardır, kalan parametreler ise kodunuzda serbestçe yanıtsız kalır (örneğin, clientSecret):
var adal = require('adal-node');
var authority = "https://login.microsoftonline.com/YOUR_TENANT_ID"
var validateAuthority = true,
var cache = null;
var authenticationContext = new adal.AuthenticationContext(authority, validateAuthority, cache);
authority
: Belirteç yetkilisini tanımlayan URLvalidateAuthority
: Kodunuzun kötü amaçlı olabilecek bir yetkiliden belirteç istemesini engelleyen bir özellikcache
: bu AuthenticationContext örneği tarafından kullanılan belirteç önbelleğini ayarlar. Bu parametre ayarlı değilse, bellek önbelleğinde varsayılan bir değer kullanılır
Öte yandan MSAL Düğümü, Yapılandırma türünde bir yapılandırma nesnesi kullanır. Aşağıdaki özelliklerde oluşur:
const msal = require('@azure/msal-node');
const msalConfig = {
auth: {
clientId: "YOUR_CLIENT_ID",
authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
clientSecret: "YOUR_CLIENT_SECRET",
knownAuthorities: [],
},
cache: {
// your implementation of caching
},
system: {
loggerOptions: { /** logging related options */ }
}
}
const cca = new msal.ConfidentialClientApplication(msalConfig);
Önemli bir fark olarak, MSAL'nin yetkili doğrulamasını devre dışı bırakmak için bir bayrağı yoktur ve yetkililer her zaman varsayılan olarak doğrulanır. MSAL, istediğiniz yetkiyi Microsoft tarafından bilinen bir yetkili listesiyle veya yapılandırmanızda belirttiğiniz yetkili listesiyle karşılaştırır. Daha fazla bilgi için bkz. Yapılandırma Seçenekleri
MSAL API'sine geçiş yapma
ADAL Düğümündeki genel yöntemlerin çoğunun MSAL Düğümündeki eşdeğerleri vardır:
ADAL | MSAL | Notlar |
---|---|---|
acquireToken |
acquireTokenSilent |
Yeniden adlandırıldı ve şimdi bir hesap nesnesi bekliyor |
acquireTokenWithAuthorizationCode |
acquireTokenByCode |
|
acquireTokenWithClientCredentials |
acquireTokenByClientCredential |
|
acquireTokenWithRefreshToken |
acquireTokenByRefreshToken |
Geçerli yenileme belirteçlerini geçirmek için kullanışlıdır |
acquireTokenWithDeviceCode |
acquireTokenByDeviceCode |
Şimdi kullanıcı kodu alımını soyutlar (aşağıya bakın) |
acquireTokenWithUsernamePassword |
acquireTokenByUsernamePassword |
Ancak, MSAL Düğümü yeni yöntemler sunarken, ADAL Düğümündeki bazı yöntemler kullanım dışı bırakılmıştır:
ADAL | MSAL | Notlar |
---|---|---|
acquireUserCode |
Yok | ile acquireTokeByDeviceCode birleştirildi (yukarıya bakın) |
Yok | acquireTokenOnBehalfOf |
OBO akışını soyutlayan yeni bir yöntem |
acquireTokenWithClientCertificate |
Yok | Şimdi başlatma sırasında sertifikalar atandığından artık gerekli değildir (bkz . yapılandırma seçenekleri) |
Yok | getAuthCodeUrl |
Yetkilendirme uç noktası URL'si oluşturmayı soyutlayan yeni bir yöntem |
Kaynaklar yerine kapsamları kullanma
v1.0 ile v2.0 uç noktaları arasındaki önemli bir fark, kaynaklara nasıl erişildiğinden farklıdır. ADAL Düğümü'nde, önce uygulama kayıt portalına bir izin kaydeder ve ardından aşağıda gösterildiği gibi bir kaynak (Microsoft Graph gibi) için erişim belirteci isteyebilirsiniz:
authenticationContext.acquireTokenWithAuthorizationCode(
req.query.code,
redirectUri,
resource, // e.g. 'https://graph.microsoft.com'
clientId,
clientSecret,
function (err, response) {
// do something with the authentication response
}
);
MSAL Düğümü yalnızca v2.0 uç noktasını destekler. v2.0 uç noktası, kaynaklara erişmek için kapsam odaklı bir model kullanır. Bu nedenle, bir kaynak için erişim belirteci istediğinizde, bu kaynağın kapsamını da belirtmeniz gerekir:
const tokenRequest = {
code: req.query.code,
scopes: ["https://graph.microsoft.com/User.Read"],
redirectUri: REDIRECT_URI,
};
pca.acquireTokenByCode(tokenRequest).then((response) => {
// do something with the authentication response
}).catch((error) => {
console.log(error);
});
Kapsam odaklı modelin avantajlarından biri dinamik kapsamları kullanabilmektir. v1.0 kullanarak uygulama oluştururken, kullanıcının oturum açma sırasında onay verebilmek için uygulamanın gerektirdiği tam izin kümesini (statik kapsamlar olarak adlandırılır) kaydetmeniz gerekiyordu. v2.0'da scope parametresini kullanarak izinleri istediğiniz anda isteyebilirsiniz (dolayısıyla dinamik kapsamlar). Bu, kullanıcının kapsamlara artımlı onay sağlamasına olanak tanır. Bu nedenle, başlangıçta yalnızca kullanıcının uygulamanızda oturum açmasını istiyorsanız ve herhangi bir erişime ihtiyacınız yoksa, bunu yapabilirsiniz. Daha sonra kullanıcının takvimini okuma yeteneğine ihtiyacınız varsa, acquireToken yöntemlerinde takvim kapsamını isteyebilir ve kullanıcının onayını alabilirsiniz. Daha fazla bilgi için bkz. Kaynaklar ve kapsamlar
Geri çağırmalar yerine promises kullanma
ADAL Düğümünde, kimlik doğrulaması başarılı olduktan ve bir yanıt alındıktan sonra geri çağırmalar herhangi bir işlem için kullanılır:
var context = new AuthenticationContext(authorityUrl, validateAuthority);
context.acquireTokenWithClientCredentials(resource, clientId, clientSecret, function(err, response) {
if (err) {
console.log(err);
} else {
// do something with the authentication response
}
});
MSAL Düğümü'nde bunun yerine promise'ler kullanılır:
const cca = new msal.ConfidentialClientApplication(msalConfig);
cca.acquireTokenByClientCredential(tokenRequest).then((response) => {
// do something with the authentication response
}).catch((error) => {
console.log(error);
});
ES8 ile birlikte gelen zaman uyumsuz/await söz dizimini de kullanabilirsiniz:
try {
const authResponse = await cca.acquireTokenByCode(tokenRequest);
} catch (error) {
console.log(error);
}
Günlü kaydını etkinleştir
ADAL Düğümü'nde, günlüğü kodunuzun herhangi bir yerinde ayrı olarak yapılandırabilirsiniz:
var adal = require('adal-node');
//PII or OII logging disabled. Default Logger does not capture any PII or OII.
adal.logging.setLoggingOptions({
log: function (level, message, error) {
console.log(message);
if (error) {
console.log(error);
}
},
level: logging.LOGGING_LEVEL.VERBOSE, // provide the logging level
loggingWithPII: false // Determine if you want to log personal identification information. The default value is false.
});
MSAL Düğümü'nde günlük, yapılandırma seçeneklerinin bir parçasıdır ve MSAL Node örneğinin başlatılmasıyla oluşturulur:
const msal = require('@azure/msal-node');
const msalConfig = {
auth: {
// authentication related parameters
},
cache: {
// cache related parameters
},
system: {
loggerOptions: {
loggerCallback(loglevel, message, containsPii) {
console.log(message);
},
piiLoggingEnabled: false,
logLevel: msal.LogLevel.Verbose,
}
}
}
const cca = new msal.ConfidentialClientApplication(msalConfig);
Belirteç önbelleğe almayı etkinleştirme
ADAL Düğümü'nde bellek içi belirteç önbelleğini içeri aktarma seçeneğiniz vardı. Belirteç önbelleği, bir AuthenticationContext
nesne başlatılırken parametre olarak kullanılır:
var MemoryCache = require('adal-node/lib/memory-cache');
var cache = new MemoryCache();
var authorityURI = "https://login.microsoftonline.com/common";
var context = new AuthenticationContext(authorityURI, true, cache);
MSAL Düğümü varsayılan olarak bellek içi belirteç önbelleği kullanır. Açıkça içeri aktarmanız gerekmez; bellek içi belirteç önbelleği ve PublicClientApplication
sınıflarının ConfidentialClientApplication
bir parçası olarak kullanıma sunulur.
const msalTokenCache = publicClientApplication.getTokenCache();
Önemli olan, önbellek şemaları uyumsuz olduğundan ADAL Düğümü ile önceki belirteç önbelleğiniz MSAL Düğümüne aktarılamaz. Ancak, uygulamanızın daha önce MSAL Düğümü'nde ADAL Düğümü ile edinmiş olduğu geçerli yenileme belirteçlerini kullanabilirsiniz. Daha fazla bilgi için yenileme belirteçleri bölümüne bakın.
Ayrıca kendi önbellek eklentinizi sağlayarak önbelleğinizi diske yazabilirsiniz. Önbellek eklentisi arabirimini ICachePlugin
uygulamalıdır. Günlüğe kaydetme gibi önbelleğe alma da yapılandırma seçeneklerinin bir parçasıdır ve MSAL Node örneğinin başlatılmasıyla oluşturulur:
const msal = require('@azure/msal-node');
const msalConfig = {
auth: {
// authentication related parameters
},
cache: {
cachePlugin // your implementation of cache plugin
},
system: {
// logging related options
}
}
const msalInstance = new ConfidentialClientApplication(msalConfig);
Aşağıdaki gibi örnek bir önbellek eklentisi uygulanabilir:
const fs = require('fs');
// Call back APIs which automatically write and read into a .json file - example implementation
const beforeCacheAccess = async (cacheContext) => {
cacheContext.tokenCache.deserialize(await fs.readFile(cachePath, "utf-8"));
};
const afterCacheAccess = async (cacheContext) => {
if(cacheContext.cacheHasChanged) {
await fs.writeFile(cachePath, cacheContext.tokenCache.serialize());
}
};
// Cache Plugin
const cachePlugin = {
beforeCacheAccess,
afterCacheAccess
};
Masaüstü uygulamaları gibi genel istemci uygulamaları geliştiriyorsanız, Node için Microsoft Authentication Extensions, istemci uygulamalarının platformlar arası belirteç önbelleği serileştirmesi ve kalıcılığı gerçekleştirmesi için güvenli mekanizmalar sunar. Desteklenen platformlar Windows, Mac ve Linux'tır.
Not
Ölçeklendirme ve performans sorunlarına neden olabileceği için, Web uygulamaları için Node için Microsoft Kimlik Doğrulama Uzantıları önerilmez. Bunun yerine, web uygulamalarının önbelleği oturumda kalıcı hale getirmek için kullanılması önerilir.
Yenileme belirteçlerinin etrafındaki mantığı kaldırma
ADAL Düğümü'nde yenileme belirteçleri (RT) kullanıma sunuldu ve bu belirteçleri önbelleğe alarak ve yöntemini kullanarak acquireTokenWithRefreshToken
bu belirteçlerin kullanımına yönelik çözümler geliştirmenizi sağlar. RT'lerin özellikle ilgili olduğu tipik senaryolar:
- Kullanıcıların artık bağlı olmadığı kullanıcılar adına panoları yenileme gibi eylemlerde bulunan uzun süre çalışan hizmetler.
- İstemcinin RT'yi web hizmetine getirmesini sağlamak için WebFarm senaryoları (önbelleğe alma, sunucu tarafı değil istemci tarafı, şifrelenmiş tanımlama bilgisi yapılır).
MSAL Düğümü, diğer MSAL'lerle birlikte güvenlik nedeniyle yenileme belirteçlerini kullanıma sunmaz. Bunun yerine, MSAL sizin için yenileme belirteçlerini işler. Bu nedenle, artık bunun için mantık oluşturmanız gerekmez. Ancak, MSAL Node ile yeni bir belirteç kümesi almak için ADAL Düğümü önbelleğinden daha önce edindiğiniz (ve hala geçerli) yenileme belirteçlerinizi kullanabilirsiniz. Bunu yapmak için MSAL Node, ADAL Node'un acquireTokenWithRefreshToken
yöntemine eşdeğer olan öğesini sunaracquireTokenByRefreshToken
:
var msal = require('@azure/msal-node');
const config = {
auth: {
clientId: "ENTER_CLIENT_ID",
authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
clientSecret: "ENTER_CLIENT_SECRET"
}
};
const cca = new msal.ConfidentialClientApplication(config);
const refreshTokenRequest = {
refreshToken: "", // your previous refresh token here
scopes: ["https://graph.microsoft.com/.default"],
forceCache: true,
};
cca.acquireTokenByRefreshToken(refreshTokenRequest).then((response) => {
console.log(response);
}).catch((error) => {
console.log(error);
});
Daha fazla bilgi için lütfen ADAL Düğümünden MSAL Düğümüne geçiş örneğine bakın.
Not
Yukarıda gösterildiği gibi MSAL Node'un acquireTokenByRefreshToken
yöntemini kullanarak yeni bir belirteç kümesi almak için hala geçerli yenileme belirteçlerini kullandıktan sonra eski ADAL Düğümü belirteç önbelleğini yok etmenizi öneririz.
Hataları ve özel durumları işleme
MSAL Düğümü kullanırken karşılaşabileceğiniz en yaygın hata türü hatadır interaction_required
. Bu hata genellikle etkileşimli bir belirteç alma istemi başlatılarak çözülür. Örneğin, kullanırken acquireTokenSilent
önbelleğe alınmış yenileme belirteci yoksa, MSAL Düğümü sessizce bir erişim belirteci alamaz. Benzer şekilde, erişmeye çalıştığınız web API'sinde de kullanıcının çok faktörlü kimlik doğrulaması (MFA) gerçekleştirmesini gerektiren bir Koşullu Erişim ilkesi olabilir. Bu gibi durumlarda, tetikleyerek acquireTokenByCode
hatanın işlenmesi interaction_required
kullanıcıdan MFA istemesine neden olur ve tam olarak sağlamasına olanak tanır.
Yine de, korumalı bir kaynak için erişim belirteci almak için gereken izinler kullanıcı tarafından onaylanmadığında oluşan bir diğer yaygın hatayla karşılaşabilirsiniz consent_required
. içinde interaction_required
olduğu gibi hatanın çözümü consent_required
genellikle yöntemini kullanarak etkileşimli bir belirteç alma istemi başlatır acquireTokenByCode
.
Uygulamayı çalıştırma
Değişiklikleriniz tamamlandıktan sonra uygulamayı çalıştırın ve kimlik doğrulama senaryonuzu test edin:
npm start
Örnek: ADAL Düğümü ve MSAL Düğümü ile belirteç alma
Aşağıdaki kod parçacığı, Express.js çerçevesinde gizli bir istemci web uygulamasını gösterir. Kullanıcı kimlik doğrulama yoluna ulaştığında oturum açma işlemi gerçekleştirir, yol /auth
üzerinden /redirect
Microsoft Graph için bir erişim belirteci alır ve ardından belirtilen belirtecin içeriğini görüntüler.
ADAL Düğümünü Kullanma | MSAL Düğümünü Kullanma |
|
|