Oturum açmış kullanıcılar

Buradan başlamadan önce uygulama nesnesini nasıl başlatabileceğinizi anladığınızdan emin olun.

MSAL'deki oturum açma API'leri, oturum açmış bir kullanıcı için authorization code karşılığında alınabilen bir ID belirteci, ek bir kaynak için onay kapsamları ve uygulamanızın API'yi güvenli bir şekilde çağırabilmesini sağlamak üzere kullanıcının onayladığı kapsamları içeren bir erişim belirteci alır.

Etkileşim Türü Seçme

loginRedirect ile loginPopup arasındaki farklardan emin değilseniz buraya bakın.

Kullanıcının oturumunu açma

Oturum açma API'lerine bir istek nesnesi geçirmeniz gerekir. Bu nesne, istekte farklı parametreler kullanmanıza olanak tanır. İstek nesnesi parametreleri hakkında daha fazla bilgi için buraya bakın.

Oturum açma istekleri için tüm parametreler isteğe bağlıdır, bu nedenle boş bir nesne gönderebilirsiniz.

• Popup

try {
    const loginResponse = await msalInstance.loginPopup({});
} catch (err) {
    // handle error
}

• Redirect

try {
    msalInstance.loginRedirect({});
} catch (err) {
    // handle error
}

Alternatif olarak, aşağıdakilere önceden onay vermek için bir kapsam kümesi de gönderebilirsiniz:

• Popup

var loginRequest = {
    scopes: ["user.read", "mail.send"] // optional Array<string>
};

try {
    const loginResponse = await msalInstance.loginPopup(loginRequest);
} catch (err) {
    // handle error
}

• Redirect

var loginRequest = {
    scopes: ["user.read", "mail.send"] // optional Array<string>
};

try {
    msalInstance.loginRedirect(loginRequest);
} catch (err) {
    // handle error
}

Hesap API'leri

Oturum açma araması başarılı olduğunda, şu anda oturum açmış kullanıcılar hakkındaki bilgileri almak için işlevini kullanabilirsiniz getAllAccounts() .

const myAccounts: AccountInfo[] = msalInstance.getAllAccounts();

Hesap bilgilerini biliyorsanız, API'yi kullanarak getAccount() hesap bilgilerini de alabilirsiniz:

const username = "test@contoso.com";
const myAccount: AccountInfo = msalInstance.getAccount({ username });

const homeAccountId = "userid.hometenantid"; // Best to retrieve the homeAccountId from an account object previously obtained through msal
const myAccount: AccountInfo = msalInstance.getAccount({ homeAccountId });

B2C senaryolarında, getAccount() API’sinde username filtresini kullanabilmek için B2C kiracınızın idTokens üzerinde emails claim’ini döndürecek şekilde yapılandırılması gerekir.

Bu API'ler aşağıdaki imzaya sahip bir hesap nesnesi veya hesap nesneleri dizisi döndürür:

{
    // home account identifier for this account object
    homeAccountId: string;
    // Entity who issued the token represented as a full host of it (e.g. login.microsoftonline.com)
    environment: string;
    // Full tenant or organizational id that this account belongs to
    tenantId: string;
    // preferred_username claim of the id_token that represents this account.
    username: string;
};

ssoSilent() ile sessiz oturum açma

Kimlik doğrulama sunucusuyla zaten var olan bir oturum varsa, etkileşim olmadan belirteç isteklerinde bulunmak için ssoSilent() API'sini kullanabilirsiniz.

Kullanıcı İpucuyla

Kullanıcının oturum açma bilgilerine zaten sahipseniz, performansı artırmak ve yetkilendirme sunucusunun doğru hesap oturumunu aramasını sağlamak için bunu API'ye geçirebilirsiniz. Bir belirteci sessizce başarıyla almak için istek nesnesine aşağıdakilerden birini geçirebilirsiniz.

login_hintisteğe bağlı kimlik belirteci talep değerinden (ssoSilent'ye loginHint olarak sağlanan) yararlanmanız önerilir; çünkü bu, sessiz (ve etkileşimli) istekler için en güvenilir hesap ipucudur.

• account ( hesap API'lerinden biri kullanılarak alınabilir)
• sid (bir account nesnesinin idTokenClaims öğesinden alınabilen)
• login_hint (aşağıdaki yollarla alınabilir)
  • Hesap nesnesinin loginHint özelliği olarak (önerilir)
  • Hesap nesnesinin login_hint kimlik belirteci talebi olarak (önerilir)
  • Hesap nesnesinin username özelliği olarak (önerilmez)
  • Hesap nesnesinin upn kimlik belirteci talebi olarak (önerilmez)

Bir hesap iletildiğinde, önce login_hint isteğe bağlı ID belirteci talebi (tercih edilir), ardından sid isteğe bağlı id belirteci talebi aranır; bunlar bulunamazsa loginHint (sağlanmışsa) ya da hesap kullanıcı adına geri dönülür.

const account = msalInstance.getAllAccounts()[0];

const silentRequest = {
    scopes: ["User.Read", "Mail.Read"],
    loginHint: account.loginHint, // alternatively, account.idTokenClaims.login_hint
};

try {
    const loginResponse = await msalInstance.ssoSilent(silentRequest);
} catch (err) {
    if (err instanceof InteractionRequiredAuthError) {
        const loginResponse = await msalInstance.loginPopup(silentRequest).catch(error => {
            // handle error
        });
    } else {
        // handle error
    }
}

Kullanıcı İpucu Olmadan

Kullanıcı hakkında yeterli bilgi yoksa, ssoSilent API’yi göndermeden bir account, sid veya login_hint kullanmayı deneyebilirsiniz.

const silentRequest = {
    scopes: ["User.Read", "Mail.Read"]
};

Ancak, uygulamanızın tek bir tarayıcı oturumunda birden çok kullanıcı için kod yolları varsa veya kullanıcının bu tek tarayıcı oturumu için birden çok hesabı varsa, sessiz oturum açma hataları olasılığı daha yüksektir. Yetkilendirme sunucusu birden fazla hesap oturumu algıladığında aşağıdaki hata görüntülenebilir:

InteractionRequiredAuthError: interaction_required: AADSTS16000: Either multiple user identities are available for the current request or selected account is not supported for the scenario.

Bu, sunucunun hangi hesapta oturum açacağını belirleyemediğini ve hesabı seçmek için yukarıdaki parametrelerden birini (account, login_hint, sid) veya etkileşimli bir oturum açmayı gerektirdiğini gösterir.

RedirectUri Ile İlgili Dikkat Edilmesi Gerekenler

Tüm kimlik doğrulama akışları artık MSAL yeniden yönlendirme köprüsünü uygulayan ayrılmış bir yeniden yönlendirme sayfası gerektirir . Bu, COOP (Cross-Origin-Opener-Policy) başlıklarını desteklemek ve açılır pencereler/iframe’ler ile ana uygulama arasında güvenli iletişimi etkinleştirmek için gereklidir.

Yeniden yönlendirme sayfasını ayarlama

redirectUri öğeniz, yeniden yönlendirme köprüsü komut dosyasını yükleyen özel bir sayfayı işaret etmelidir. Bu sayfa şu şekilde olmalıdır:

1. Yeniden yönlendirme köprüsü betiğini yükleme - Bu betik ana pencereyle iletişimi işler
2. Köprü betiği dışında javascript içermez - Yeniden yönlendirme sayfası yalnızca köprü betiğini çalıştırmalıdır
3. Yönlendirme mantığını içermez - Karma işlemeyi engelleyebilecek yönlendirici kitaplıklarından kaçının
4. Uygulama Kaydınıza kayıtlı olun - URI'nin Azure portalında kayıtlı olanlarla tam olarak eşleşmesi gerekir

Örnek yeniden yönlendirme sayfası (Vite veya Webpack gibi bir paketleyici kullanırken):

<!DOCTYPE html>
<html>
<head>
    <title>Redirect</title>
</head>
<body>
    <p>Processing authentication...</p>
    <script type="module">
        import { broadcastResponseToMainFrame } from "@azure/msal-browser/redirect-bridge";

        broadcastResponseToMainFrame();
    </script>
</body>
</html>

Configuration

redirectUri öğesini MSAL yapılandırmanızın genelinde veya her istek için ayrı ayrı ayarlayabilirsiniz:

Genel yapılandırma:

const msalConfig = {
    auth: {
        clientId: "your-client-id",
        authority: "https://login.microsoftonline.com/common",
        redirectUri: "http://localhost:3000/redirect"
    }
};

const msalInstance = new PublicClientApplication(msalConfig);

İstek başına yapılandırma:

msalInstance.loginPopup({
    scopes: ["user.read"],
    redirectUri: "http://localhost:3000/redirect"
});

Daha fazla bilgi edinmek ve örnek uygulamaları tamamlamak için bkz:

• React Router Örneği
• Hızlı Örnek

Açılır pencere interaction_in_progress hatalarının işlenmesi

Açılır pencere akışlarında, bekleyen bir etkileşimi iptal etmek ve yeni bir etkileşim başlatmak için overrideInteractionInProgress işaretini kullanabilirsiniz. Bu, kullanıcının bir açılır pencere iptal ettiği veya etkileşimin başarısız olduğu kurtarma senaryoları için kullanışlıdır.

olarak trueayarlandığında:

• Şu anda devam eden başka bir açılır pencere etkileşimi varsa, zorla iptal edilir ancak açık olan açılır pencereler kapatılamaz
• Bekleyen etkileşim, interaction_in_progress_cancelled hatasıyla reddedilir
• Yeni açılır pencere akışı hemen başlar.

Geçerli kullanım örnekleri:

• Kullanıcının açılır pencereyi iptal ettiği durumlarda oluşan hatalardan kurtarma (açılır pencere, kimlik doğrulama tamamlanmadan kapatıldı)
• Özel hata kurtarma akışları uygulama
• Başarısız bir açılır pencere etkileşiminden sonra "yeniden deneme" mekanizması sunma

Varsayılan:false

Önemli: Yalnızca düğme tıklamada kullan

Hata yakalarken interaction_in_progress. Geçersiz kılma yalnızca açık bir kullanıcı eylemi (bir "Yeniden Dene" düğmesine tıklama gibi) tarafından tetiklenmelidir. Etkileşimlerin otomatik olarak geçersiz kılınmış olması şu nedenlere yol açabilir:

• Birden çok kimlik doğrulama akışı arasındaki yarış koşulları
• Meşru kimlik doğrulama girişimlerinin beklenmeyen iptalleri
• Kimlik doğrulama akışlarının beklenmedik bir şekilde başlatılması ve durdurulmasıyla ilgili kötü kullanıcı deneyimi
• Başarılı kimlik doğrulama yanıtlarıyla sonuçlanmayan çok sayıda açık açılır pencere

Örnek: Kullanıcı tarafından tetiklenen yeniden deneme ile düzgün hata işleme

Görsel geri bildirim içeren eksiksiz uygulamalar için bkz:

• Express Sample — Özel CSS ile JavaScript uygulamasını gösterir
• React Router Örneği — Material-UI bileşenleriyle React uygulamasını gösterir

Her iki örnek de şu şekildedir:

• Açılır pencere kimlik doğrulaması sırasında görüntülenen uyarı iletisi
• interaction_in_progress hatası oluştuğunda net açıklamalı yeniden deneme modali/iletişim kutusu
• Kullanıcı tarafından tetiklenen yeniden deneme için uygun durum yönetimi
• Üretime hazır kullanıcı arabirimi bileşenleri

// State to track if user wants to retry
let userWantsRetry = false;

// Button click handler
async function handleLoginClick() {
    try {
        const loginRequest = {
            scopes: ["user.read"]
        };

        // If user explicitly clicked retry, override the existing interaction
        if (userWantsRetry) {
            loginRequest.overrideInteractionInProgress = true;
            userWantsRetry = false; // Reset flag
        }

        const response = await msalInstance.loginPopup(loginRequest);
        // Handle successful login
    } catch (error) {
        if (error.errorCode === 'interaction_in_progress') {
            // Show retry button to user - DO NOT automatically retry
            showRetryButton();
        } else {
            // Handle other errors
            console.error(error);
        }
    }
}

// Retry button click handler
function handleRetryClick() {
    userWantsRetry = true; // Set flag for next login attempt
    handleLoginClick(); // User explicitly requested retry
}

Örnek: Kullanıcı tarafından tetiklenen yeniden deneme ile React bileşeni

function LoginButton() {
    const { instance } = useMsal();
    const [showRetry, setShowRetry] = useState(false);
    const [retryRequested, setRetryRequested] = useState(false);

    const handleLogin = async () => {
        try {
            const loginRequest = {
                scopes: ["user.read"],
                // Only override if user clicked the retry button
                overrideInteractionInProgress: retryRequested
            };

            setRetryRequested(false); // Reset retry flag

            const response = await instance.loginPopup(loginRequest);
            setShowRetry(false);
        } catch (error) {
            if (error.errorCode === 'interaction_in_progress') {
                // Show retry button - let user decide whether to retry
                setShowRetry(true);
            } else {
                console.error(error);
            }
        }
    };

    const handleRetry = () => {
        setRetryRequested(true); // User explicitly requested retry
        handleLogin();
    };

    return (
        <div>
            <button onClick={handleLogin}>Login</button>
            {showRetry && (
                <button onClick={handleRetry}>
                    Retry Login (Cancel Pending)
                </button>
            )}
        </div>
    );
}

Sonraki Adımlar

Erişim belirtecini nasıl edineceğinizi ve kullanacağınızı öğrenin!