JavaScript uygulamasını ADAL.js'den MSAL.js geçirme
JavaScript için Microsoft Kimlik Doğrulama Kitaplığı (MSAL.js, olarak da bilinirmsal-browser
) 2.x, Microsoft kimlik platformu JavaScript uygulamalarıyla kullanmanızı önerdiğimiz kimlik doğrulama kitaplığıdır. Bu makalede, MSAL.js 2.x kullanmak için ADAL.js kullanan bir uygulamayı geçirmek için yapmanız gereken değişiklikler vurgulanır
Not
MSAL.js 1.x üzerinde MSAL.js 2.x'i kesinlikle öneririz. Kimlik doğrulama kodu verme akışı daha güvenlidir ve Safari gibi tarayıcıların 3. taraf tanımlama bilgilerini engellemek için uyguladığı gizlilik önlemlerine rağmen tek sayfalı uygulamaların iyi bir kullanıcı deneyimini korumasını sağlar.
Önkoşullar
- Platform / Yanıtı URL Türü'nü Uygulama Kaydı portalında Tek sayfalı uygulama olarak ayarlamanız gerekir (Uygulama kaydınıza Web gibi başka platformlar eklendiyse, yeniden yönlendirme URI'lerinin çakışmadığından emin olmanız gerekir. Bkz. Yeniden yönlendirme URI'leri kısıtlamaları)
- Uygulamalarınızı Internet Explorer'da çalıştırmak için MSAL.js bağlı olan ES6 özellikleri için çoklu doldurmalar sağlamanız gerekir (örneğin, vaatler).
- Henüz yapmadıysanız Microsoft Entra uygulamalarınızı v2 uç noktasına geçirme
MSAL'yi yükleme ve içeri aktarma
MSAL.js 2.x kitaplığını yüklemenin iki yolu vardır:
Npm aracılığıyla:
npm install @azure/msal-browser
Ardından modül sisteminize bağlı olarak aşağıda gösterildiği gibi içeri aktarın:
import * as msal from "@azure/msal-browser"; // ESM
const msal = require('@azure/msal-browser'); // CommonJS
CDN aracılığıyla:
Betiği HTML belgenizin üst bilgi bölümüne yükleyin:
<!DOCTYPE html>
<html>
<head>
<script type="text/javascript" src="https://alcdn.msauth.net/browser/2.14.2/js/msal-browser.min.js"></script>
</head>
</html>
CDN kullanırken alternatif CDN bağlantıları ve en iyi yöntemler için bkz. CDN Kullanımı
MSAL'ı başlatma
ADAL.js'de AuthenticationContext sınıfının örneğini oluşturursunuz. Bu sınıf, kimlik doğrulaması (login
, acquireTokenPopup
vb.) elde etmek için kullanabileceğiniz yöntemleri kullanıma sunar. Bu nesne, uygulamanızın yetkilendirme sunucusuna veya kimlik sağlayıcısına olan bağlantısını temsil eder. Başlatılırken tek zorunlu parametre clientId değeridir:
window.config = {
clientId: "YOUR_CLIENT_ID"
};
var authContext = new AuthenticationContext(config);
MSAL.js içinde, bunun yerine PublicClientApplication sınıfını başlatırsınız. ADAL.js gibi oluşturucu da en azından parametresini clientId
içeren bir yapılandırma nesnesi bekler. Daha fazla bilgi için bkz: MSAL.js başlatma
const msalConfig = {
auth: {
clientId: 'YOUR_CLIENT_ID'
}
};
const msalInstance = new msal.PublicClientApplication(msalConfig);
Hem ADAL.js hem de MSAL.js, belirtmezseniz yetkili URI'sinin varsayılan değeri https://login.microsoftonline.com/common
olur.
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.js'da, herhangi bir Microsoft Entra hesabıyla oturum açmayı kısıtlamak istiyorsanız (ADAL.js ile aynı davranış), bunun yerine kullanın https://login.microsoftonline.com/organizations
.
MSAL'yi yapılandırma
AuthenticationContext başlatılırken kullanılan ADAL.js yapılandırma seçeneklerinden bazıları MSAL.js'de kullanım dışı bırakılırken, bazı yeni seçenekler kullanıma sunulmuştur. Kullanılabilir seçeneklerin tam listesine bakın. Daha da önemlisi, clientId
belirteç alma sırasında bu seçeneklerin çoğu geçersiz kılınabilir ve bunları istek temelinde ayarlamanıza olanak sağlar. Örneğin, belirteçleri alırken başlatma sırasında ayarladığınızdan farklı bir yetkili URI'sini veya yeniden yönlendirme URI'sini kullanabilirsiniz.
Ayrıca, yapılandırma seçenekleri aracılığıyla oturum açma deneyimini (yani açılır pencereleri kullanma veya sayfayı yeniden yönlendirme) belirtmeniz gerekmez. Bunun yerine, MSAL.js
örnek aracılığıyla PublicClientApplication
ve loginRedirect
yöntemlerini kullanıma sunarloginPopup
.
Günlü kaydını etkinleştir
ADAL.js'da, günlüğü kodunuzun herhangi bir yerinde ayrı olarak yapılandırabilirsiniz:
window.config = {
clientId: "YOUR_CLIENT_ID"
};
var authContext = new AuthenticationContext(config);
var Logging = {
level: 3,
log: function (message) {
console.log(message);
},
piiLoggingEnabled: false
};
authContext.log(Logging)
MSAL.js günlük, yapılandırma seçeneklerinin bir parçasıdır ve başlatılırken PublicClientApplication
oluşturulur:
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 msalInstance = new msal.PublicClientApplication(msalConfig);
MSAL API'sine geçiş yapma
ADAL.js'daki bazı genel yöntemlerin MSAL.js eşdeğerleri vardır:
ADAL | MSAL | Notlar |
---|---|---|
acquireToken |
acquireTokenSilent |
Yeniden adlandırıldı ve şimdi bir hesap nesnesi bekliyor |
acquireTokenPopup |
acquireTokenPopup |
Şimdi zaman uyumsuz ve bir söz döndürür |
acquireTokenRedirect |
acquireTokenRedirect |
Şimdi zaman uyumsuz ve bir söz döndürür |
handleWindowCallback |
handleRedirectPromise |
Yeniden yönlendirme deneyimi kullanılıyorsa gereklidir |
getCachedUser |
getAllAccounts |
Yeniden adlandırıldı ve şimdi bir hesap dizisi döndürür. |
Diğerleri kullanım dışı bırakılmıştır ancak MSAL.js yeni yöntemler sunar:
ADAL | MSAL | Notlar |
---|---|---|
login |
Yok | Kullanımdan kaldırıldı. veya kullanın loginPopup loginRedirect |
logOut |
Yok | Kullanımdan kaldırıldı. veya kullanın logoutPopup logoutRedirect |
Yok | loginPopup |
|
Yok | loginRedirect |
|
Yok | logoutPopup |
|
Yok | logoutRedirect |
|
Yok | getAccountByHomeId |
Hesapları ev kimliğine (oid + kiracı kimliği) göre filtreler |
Yok | getAccountLocalId |
Hesapları yerel kimlikle filtreler (ADFS için kullanışlıdır) |
Yok | getAccountUsername |
Hesapları kullanıcı adına göre filtreler (varsa) |
Ayrıca, MSAL.js ADAL.js aksine TypeScript'te uygulandığından, projelerinizde kullanabileceğiniz çeşitli türleri ve arabirimleri kullanıma sunar. Daha fazla bilgi için bkz. MSAL.js API başvurusu.
Kaynaklar yerine kapsamları kullanma
Azure Active Directory v1.0 ile 2.0 uç noktaları arasındaki önemli bir fark, kaynaklara nasıl erişildiğinden farklıdır. v1.0 uç noktasıyla ADAL.js kullanırken, ö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:
authContext.acquireTokenRedirect("https://graph.microsoft.com", function (error, token) {
// do something with the access token
});
MSAL.js 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:
msalInstance.acquireTokenRedirect({
scopes: ["https://graph.microsoft.com/User.Read"]
});
Kapsam odaklı modelin avantajlarından biri dinamik kapsamları kullanabilmektir. v1.0 uç noktasını 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.js 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:
authContext.acquireTokenPopup(resource, extraQueryParameter, claims, function (error, token) {
// do something with the access token
});
MSAL.js yerine promises kullanılır:
msalInstance.acquireTokenPopup({
scopes: ["User.Read"] // shorthand for https://graph.microsoft.com/User.Read
}).then((response) => {
// do something with the auth response
}).catch((error) => {
// handle errors
});
ES8 ile birlikte gelen zaman uyumsuz/await söz dizimini de kullanabilirsiniz:
const getAccessToken = async() => {
try {
const authResponse = await msalInstance.acquireTokenPopup({
scopes: ["User.Read"]
});
} catch (error) {
// handle errors
}
}
Belirteçleri önbelleğe alma ve alma
ADAL.js gibi MSAL.js de Web Depolama API'sini kullanarak belirteçleri ve diğer kimlik doğrulama yapıtlarını tarayıcı depolamasında önbelleğe alır. Kullanıcılarınız tarafından alınan belirteçleri depolamada daha güvenli olduğundan, ancak localStorage
sekmeler ve kullanıcı oturumlarında size Çoklu Oturum Açma sağladığından seçeneği kullanmanız sessionStorage
önerilir (bkz. yapılandırma).
Daha da önemlisi, önbelleğe doğrudan erişmeniz gerekmez. Bunun yerine, erişim belirteçleri veya kullanıcı hesapları gibi kimlik doğrulama yapıtlarını almak için uygun bir MSAL.js API'sini kullanmanız gerekir.
Belirteçleri yenileme belirteçleriyle yenileme
ADAL.js, güvenlik nedeniyle yenileme belirteçleri döndürmeyen OAuth 2.0 örtük akışını kullanır (yenileme belirteçlerinin ömrü erişim belirteçlerinden daha uzun olur ve bu nedenle kötü amaçlı aktörlerin elinde daha tehlikelidir). Bu nedenle ADAL.js, kullanıcının tekrar tekrar kimlik doğrulamasından istenmesi için gizli bir IFrame kullanarak belirteç yenileme gerçekleştirir.
PKCE desteğine sahip kimlik doğrulama kodu akışıyla, MSAL.js 2.x kullanan uygulamalar kimlik ve erişim belirteçleriyle birlikte yenileme belirteçleri alır ve bunları yenilemek için kullanılabilir. Yenileme belirteçlerinin kullanımı soyutlanır ve geliştiricilerin bunların etrafında mantık oluşturmaması gerekir. Bunun yerine MSAL, yenileme belirteçlerini kullanarak belirteç yenilemeyi tek başına yönetir. Belirteç önbelleği şeması değiştiğinden ve ADAL.js kullanılan şemayla uyumsuz olduğundan ADAL.js içeren önceki belirteç önbelleğiniz MSAL.js aktarılamaz.
Hataları ve özel durumları işleme
MSAL.js kullanırken karşılaşabileceğiniz en yaygın hata türü hatadır interaction_in_progress
. Bu hata, başka bir etkileşimli API devam ederken etkileşimli bir API (loginPopup
, loginRedirect
, acquireTokenPopup
, acquireTokenRedirect
) çağrıldığında oluşur. ve API'leri login*
zaman uyumsuz olduğundan, başka bir söz çağırmadan önce elde edilen vaatlerin çözümlenmiş olduğundan emin olmanız gerekir.acquireToken*
Bir diğer yaygın hata ise şeklindedir interaction_required
. Bu hata genellikle etkileşimli bir belirteç alma istemi başlatılarak çözülür. Örneğin, erişmeye çalıştığınız web API'sinde kullanıcının çok faktörlü kimlik doğrulaması (MFA) gerçekleştirmesini gerektiren bir Koşullu Erişim ilkesi olabilir. Bu durumda, hatanın işlenmesi interaction_required
için tetiklenir acquireTokenPopup
veya acquireTokenRedirect
kullanıcıdan MFA istenir ve tam olarak dosyalanması istenir.
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 consent_required
çözümü genellikle veya acquireTokenRedirect
kullanarak acquireTokenPopup
etkileşimli bir belirteç alma istemi başlatır.
Daha fazla bilgi için bkz. Yaygın MSAL.js hataları ve bunların nasıl işleneceğini
Olaylar API'sini kullanma
MSAL.js (>=v2.4), uygulamalarınızda kullanabileceğiniz bir olay API'sini tanıtır. Bu olaylar, kimlik doğrulama işlemiyle ve MSAL'nin her an ne yaptığıyla ilgilidir ve kullanıcı arabirimini güncelleştirmek, hata iletilerini göstermek, devam eden bir etkileşim olup olmadığını denetlemek vb. için kullanılabilir. Örneğin, aşağıda herhangi bir nedenle oturum açma işlemi başarısız olduğunda çağrılacak bir olay geri çağırması yer alır:
const callbackId = msalInstance.addEventCallback((message) => {
// Update UI or interact with EventMessage here
if (message.eventType === EventType.LOGIN_FAILURE) {
if (message.error instanceof AuthError) {
// Do something with the error
}
}
});
Performans için, artık gerekli olmadığında olay geri çağırmalarının kaydını kaldırmak önemlidir. Daha fazla bilgi için bkz: MSAL.js Olayları API'si
Birden çok hesabı işleme
ADAL.js, şu anda kimliği doğrulanmış varlığı temsil eden bir kullanıcı kavramına sahiptir. MSAL.js, bir kullanıcının kendileriyle ilişkili birden fazla hesabı olabileceği göz önünde bulundurulduğunda, kullanıcıları hesaplarla değiştirir. Bu, artık birden çok hesabı denetlemeniz ve çalışmak için uygun hesabı seçmeniz gerektiği anlamına da gelir. Aşağıdaki kod parçacığında bu işlem gösterilmektedir:
let homeAccountId = null; // Initialize global accountId (can also be localAccountId or username) used for account lookup later, ideally stored in app state
// This callback is passed into `acquireTokenPopup` and `acquireTokenRedirect` to handle the interactive auth response
function handleResponse(resp) {
if (resp !== null) {
homeAccountId = resp.account.homeAccountId; // alternatively: resp.account.homeAccountId or resp.account.username
} else {
const currentAccounts = myMSALObj.getAllAccounts();
if (currentAccounts.length < 1) { // No cached accounts
return;
} else if (currentAccounts.length > 1) { // Multiple account scenario
// Add account selection logic here
} else if (currentAccounts.length === 1) {
homeAccountId = currentAccounts[0].homeAccountId; // Single account scenario
}
}
}
Daha fazla bilgi için bkz. MSAL.js'deki hesaplar
Sarmalayıcı kitaplıklarını kullanma
Angular ve React çerçeveleri için geliştiriyorsanız, sırasıyla MSAL Angular v2 ve MSAL React'i kullanabilirsiniz. Bu sarmalayıcılar MSAL.js ile aynı genel API'yi kullanıma sunarken, kimlik doğrulama ve belirteç alma işlemlerini kolaylaştırabilecek çerçeveye özgü yöntemler ve bileşenler sunar.
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: spayı ADAL.js ve MSAL.js ile güvenli hale getirme
Aşağıdaki kod parçacıkları, kullanıcıların kimliklerini Microsoft kimlik platformu ve microsoft graph için ilk ADAL.js ve ardından MSAL.js kullanarak erişim belirteci alan tek sayfalı bir uygulama için gereken en düşük kodu gösterir:
ADAL.js kullanma | MSAL.js kullanma |
|
|