Iframed uygulamalarında MSAL kullanma

Varsayılan olarak, bir uygulama bir iframe içinde işlendiğinde MSAL Microsoft Entra ID kimlik doğrulama uç noktasına tam çerçeve yeniden yönlendirmelerini engeller; bu da IdP ile kullanıcı etkileşimi için yeniden yönlendirme API'lerini kullanamayacağınız anlamına gelir:

  • Bu kısıtlama, Microsoft Entra ID'nin clickjacking saldırılarını önlemek amacıyla alınmış bir önlem olarak, kullanıcı etkileşimi gerektiren herhangi bir istemi (ör. kimlik bilgisi girişi, onay, oturumu kapatma vb.) bir iframe içinde X-FRAME OPTIONS SET TO DENYhatasını vererek görüntülemeyi reddetmesi nedeniyle uygulanır.
  • Bunun yerine, kullanıcı etkileşimi gerekiyorsa MSAL'nin açılır API'lerine ve kullanıcı etkileşimi önlenebiliyorsa sessiz API'lere (ssoSilent(), acquireTokenSilent()) güvenmeniz gerekir.
  • Benzer şekilde, oturum kapatma işlemleri için logoutPopup() API'sini kullanmanız gerekir (:uyarı: Uygulamanız v2.13'ten eski bir sürüm msal-browser kullanıyorsa, api'yi yükseltip değiştirdiğinizden logout() emin olun çünkü Microsoft Entra ID'e tam çerçeve yeniden yönlendirmeyi deneyecektir).
  • Popup API'lerini kullanırken, üst uygulama tarafından uygulanan sandboxing kısıtlamalarını dikkate almanız gerekir. Özellikle, iframe korumalı alana alındığında üst uygulamanın allow-popups bayrağını ayarlaması gerekir.

Azure AD B2C, iframe'de özel oturum açma kullanıcı arabirimini işlemeye olanak tanıyan ekli oturum açma deneyimi sunar. MSAL varsayılan olarak iframe'lerde yeniden yönlendirmeyi önlediğinden, bu özelliği kullanmak için allowRedirectInIframe yapılandırma seçeneğini true olarak ayarlamanız gerekir. Yukarıdaki kısıtlama nedeniyle Microsoft Entra ID'da uygulamalar için bu seçeneği etkinleştirmenin önerilmediğini unutmayın.

Tarayıcı kısıtlamaları

Bir iframe içindeki Microsoft Entra oturum tanımlama bilgileri üçüncü taraf tanımlama bilgileri olarak kabul edildiğinden, bazı tarayıcılar (örneğin Gizli modda Safari veya Chrome) bu tanımlama bilgilerini varsayılan olarak engeller veya temizler. Bu, IdP'nin oturum tanımlama bilgilerine erişmeyecekleri için iframed uygulamaları için çoklu oturum açma deneyimini etkiler (bkz. Çoklu oturum açma).

Ayrıca, Chrome'da 3. taraf tanımlama bilgileri devre dışı bırakıldığında iframed MSAL uygulamalarının yerel veya oturum depolamaya erişimi olmaz. MSAL, bu durumda bellek içi depolamaya geri dönüş yapacaktır.

Tek oturum açma

Ana uygulamadan iframe içindeki uygulamaya bir hesap ipucu iletirseniz, iframe içindeki uygulama ile ana uygulama arasında tek oturum açmayı, aynı kaynakvefarklı kaynaklar arasında gerçekleştirebilirsiniz.

Aynı çıkış noktası olan uygulamalar

Aynı çıkış noktası olan Iframed ve üst uygulamalar aynı MSAL.js önbellek örneğine erişebilir ve her iki uygulamanın da MSAL'yi önbelleğe alma için yerel depolamayı kullanacak şekilde yapılandırması koşuluyla istem olmadan oturum açabilir. Daha fazla bilgi için bkz. MSAL.jsile çoklu oturum açma

Kaynaklar arası uygulamalar

Farklı origin’lere sahip iframe içine gömülü uygulamalar ile üst uygulamalar, tek oturum açmayı elde etmek için ssoSilent() API’sini kullanabilir. Bunu yapmak için üst uygulamanın iframed uygulamasına bir hesap, loginHint (kullanıcı adı) veya oturum kimliği (sid) geçirmesi gerekir.

Uygulamalar yukarıdaki parametrelerden herhangi biri olmadan kullanmayı ssoSilent deneyebilir. Ancak, kullanıcının oturumu hakkında herhangi bir bilgi sağlamadan kullanırken ssoSilent olduğunu unutmayın.

Iframe içindeki uygulamalar ile ana uygulamalar arasında farklı kaynaklar arası iletişim için değerlendirebileceğiniz birkaç alternatif vardır:

  • Üst uygulamada iframe'in kaynağına sorgu parametreleri ekleyebilir ve bunları daha sonra alt uygulamada alabilirsiniz:
// Create the main myMSALObj instance
// configuration parameters are located at authConfig.js
const myMSALObj = new msal.PublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
        redirectUri: "/redirect", // set to a blank page for handling auth code response via popups
    },
    cache: {
        cacheLocation: "localStorage", // set your cache location to local storage
    },
});

window.onload = () => {
    
    const urlParams = new URLSearchParams(window.location.search);
    const sid = urlParams.get("sid");

    // attempt SSO
    myMSALObj.ssoSilent({
        sid: sid
    }).then((response) => {
        // do something with response
    }).catch(error => {
        // handle errors
    });
}
  • postMessage() API’sini üst uygulamada kullanabilir ve alt uygulamada ileti olaylarını dinleyebilirsiniz:
// Create the main myMSALObj instance
// configuration parameters are located at authConfig.js
const myMSALObj = new msal.PublicClientApplication({
    auth: {
        clientId: "ENTER_CLIENT_ID",
        authority: "https://login.microsoftonline.com/ENTER_TENANT_ID",
        redirectUri: "/redirect", // set to a blank page for handling auth code response via popups
    },
    cache: {
        cacheLocation: "localStorage", // set your cache location to local storage
    },
});

const parentDomain = "http://localhost:3001";

window.addEventListener("message", (event) => {
    // check the origin of the data
    if (event.origin === parentDomain) {
        const sid = event.data;

        // attempt SSO
        myMSALObj.ssoSilent({
            sid: sid
        }).then((response) => {
            // do something with response
        }).catch(error => {
            // handle errors
        });
    }
});

Hata yönetimi

ssoSilent() başarısız olursa, hataları yakalayıp işlemelisiniz. Özellikle:

  • InteractionRequiredError: izin gerekiyorsa, kullanıcının MFA gibi ek doğrulama adımlarını tamamlaması gerekiyorsa vb. durumlarda fırlatılır. Bu hata çoğu zaman basitçe etkileşimli bir API çağrısı başlatılarak ele alınabilir.
  • BrowserAuthError: hiç hesap ipucu sağlanmazsa ya da geçersiz bir hesap ipucu sağlanırsa, açılır pencereler engellenirse vb. durumlarda fırlatılır. errorCode öğesini incelemeniz ve bunları uygun şekilde ele almanız gerekir.
    myMSALObj.ssoSilent({
        sid: sid
    }).then((response) => {
            // do something with response
        }).catch(error => {
            if (error instanceof msal.InteractionRequiredAuthError) {
                myMSALObj.loginPopup()
                    .then((response) => {
                        // do something with response
                    });
            } else if (error instanceof msal.BrowserAuthError) {
                if (error.errorCode === "silent_sso_error") {
                    // e.g. username is null
                }
                if (error.errorCode === "popup_window_error") {
                    // e.g. popups are blocked
                }
            } else {
                console.log(error);
            }
        });

Kullanıcı etkileşimi

IdP ile kullanıcı etkileşimi gerektiren iletişimi en aza indirmek istiyorsanız veya herhangi bir nedenle açılır pencerelerle ilgili sorun yaşıyorsanız, göz önünde bulundurabileceğiniz bazı seçenekler vardır:

Tek oturum kapatma

MSAL.js'yi, iframe içindeki ve üst uygulama arasında tek oturum kapatma etkisi elde etmek için ön kanal oturum kapatma URI'si ile kullanabilirsiniz. Örneğin, kullanıcıların ana uygulamada oturumu kapattıklarında iframe içindeki uygulamalarda da oturumlarının otomatik olarak kapatılmasını istiyorsanız, iframe içindeki uygulamalar için ön kanal oturum kapatmayı etkinleştirmeniz gerekir. Bunu yapmak için lütfen şu konuya bakın: Ön kanal oturum kapatma URI’sini yapılandırma.

  • Last updated on