MSAL React'teki kancalar

MSAL React'teki kancalar, işlevsel bileşenler içinde MSAL özelliklerini ve React durumu ve yaşam döngüsü yöntemlerini kullanmanıza olanak sağlayan işlevlerdir. Ana kancalar , , useAccountuseIsAuthenticatedve useMsalşeklindediruseMsalAuthentication. Bu makale, bu hook’ların her birini nasıl kullanacağınızı adım adım açıklar.

useAccount hook

useAccount kancası, bir accountIdentifier parametresini kabul eder ve hesapta oturum açılmışsa bu hesaba ait AccountInfo nesnesini, açılmamışsa null değerini döndürür. Hesap tanımlayıcısı sağlanmazsa geçerli etkin hesap döndürülür. MSAL'de AccountInfo@azure/msal-browser bölümündeki belgelerde döndürülen nesne hakkında daha fazla bilgi edinebilirsiniz.

const accountIdentifier = {
    localAccountId: "example-local-account-identifier",
    homeAccountId: "example-home-account-identifier"
    username: "example-username" // We do not recommend relying only on username
}

const accountInfo = useAccount(accountIdentifier);

useIsAuthenticated kanca

useIsAuthenticated hook’u, bir hesabın oturum açmış olup olmadığını belirten bir Boole değeri döndürür. İsteğe bağlı olarak, belirli bir accountIdentifier hesabın oturum açıp açmadığını bilmeniz gerekiyorsa sağlayabileceğiniz bir nesneyi kabul eder.

Herhangi bir hesabın şu anda oturum açmış olup olmadığını belirleme

Aşağıdaki kod parçacığı, @azure/msal-react paketindeki useIsAuthenticated kancasını kullanır. Bileşen daha sonra kullanıcının oturum açıp açmadığına bağlı olarak bir iletiyi koşullu olarak işler.

import React from 'react';
import { useIsAuthenticated } from "@azure/msal-react";

export function App() {
    const isAuthenticated = useIsAuthenticated();

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            {isAuthenticated && (
                <p>At least one account is signed in!</p>
            )}
            {!isAuthenticated && (
                <p>No users are signed in!</p>
            )}
        </React.Fragment>
    );
}

Belirli bir kullanıcının oturum açmış olup olmadığını belirleme

Aşağıdaki kod parçacığı, belirli bir kullanıcının oturum açmış olup olmadığını belirlemek için paketteki useIsAuthenticated kancayı kullanır@azure/msal-react.

import React from 'react';
import { useIsAuthenticated } from "@azure/msal-react";

export function App() {
    const accountIdentifiers = {
        localAccountId: "example-local-account-identifier",
        homeAccountId: "example-home-account-identifier",
        username: "example-username"
    }

    const isAuthenticated = useIsAuthenticated(accountIdentifiers);

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            {isAuthenticated && (
                <p>User with specified localAccountId is signed in!</p>
            )}
            {!isAuthenticated && (
                <p>User with specified localAccountId is not signed in!</p>
            )}
        </React.Fragment>
    );
}

useMsal hook

useMsal hook’u bağlamı döndürür. PublicClientApplication örneğine, şu anda oturum açmış hesapların listesine erişmeniz veya bir oturum açma işleminin ya da başka bir etkileşimin şu anda devam edip etmediğini bilmeniz gerekiyorsa bu kullanılabilir.

Not: accounts tarafından useMsal döndürülen değer yalnızca hesaplar eklendiğinde veya kaldırıldığında güncelleştirilir ve talepler güncelleştirildiğinde güncelleştirilmez. Geçerli kullanıcı için güncellenmiş claim'lere erişmeniz gerekiyorsa, bunun yerine useAccount hook'unu kullanın veya acquireTokenSilent öğesini çağırın.

import { useState, useEffect } from "react";
import { useMsal } from "@azure/msal-react";
import { InteractionStatus } from "@azure/msal-browser";

const { instance, accounts, inProgress } = useMsal();
const [loading, setLoading] = useState(false);
const [apiData, setApiData] = useState(null);

useEffect(() => {
    if (!loading && inProgress === InteractionStatus.None && accounts.length > 0) {
        if (apiData) {
            // Skip data refresh if already set - adjust logic for your specific use case
            return;
        }

        const tokenRequest = {
            account: accounts[0], // This is an example - Select account based on your app's requirements
            scopes: ["User.Read"]
        }

        // Acquire an access token
        instance.acquireTokenSilent(tokenRequest).then((response) => {
            // Call your API with the access token and return the data you need to save in state
            callApi(response.accessToken).then((data) => {
                setApiData(data);
                setLoading(false);
            });
        }).catch(async (e) => {
            // Catch interaction_required errors and call interactive method to resolve
            if (e instanceof InteractionRequiredAuthError) {
                await instance.acquireTokenRedirect(tokenRequest);
            }

            throw e;
        });
    }
}, [inProgress, accounts, instance, loading, apiData]);

if (loading || inProgress === InteractionStatus.Login) {
    // Render loading component
} else if (apiData) {
    // Render content that depends on data from your API
}

useMsalAuthentication hook

useMsalAuthentication kancası, kullanıcı henüz oturum açmamışsa oturum açma işlemi başlatır; aksi takdirde bir belirteç edinmeye çalışır.

Giriş Parametreleri

useMsalAuthentication kancasına geçirebileceğiniz birkaç farklı girdi parametresi vardır:

  • interactionType - (Yok, Açılan Pencere, Yeniden Yönlendirme veya Sessiz), etkileşim gerektiğinde belirteçleri nasıl almak veya oturum açmak istediğinizi belirtir (Sessiz seçeneğinin aşağıda açıklanan bazı ek konuları olduğuna dikkat edin).
  • request nesnesi - (isteğe bağlı) oturum açma veya belirteç alma çağrısı tarafından kullanılacak ek parametreleri belirtir
  • accountIdentifiers - nesne, hook’a hangi kullanıcı adına oturum açacağını veya belirteç edineceğini belirtmek için kullanılır

Dönüş Özellikleri

  • result - Son başarılı oturum açma veya belirteç alma işleminin sonucu. Bu kancanın yalnızca bir kez oturum açmayı veya belirteçleri otomatik olarak almayı denediğini unutmayın. Bu değeri güncellemek için gerektiğinde login veya acquireToken işlevini çağırmak uygulamanın sorumluluğundadır.
  • error - Oturum açma veya belirteç alma sırasında bir hata oluşursa bu özellik hata hakkında bilgi içerir. Yeniden denemek için bu hook tarafından döndürülen login veya acquireToken işlevlerini kullanabilirsiniz. error özelliği, bir sonraki başarılı oturum açma veya belirteç alma işleminde temizlenecektir.
  • login - başarısız bir oturum açmayı yeniden denemek için kullanılabilecek işlev. result ve error özellikleri güncelleştirilir.
  • acquireToken - korumalı BIR API çağırmadan önce yeni bir erişim belirteci almak için kullanılabilecek işlev. result ve error özellikleri güncelleştirilir.

"Silent" etkileşim türü geçirildiğinde, gizli bir iframe açmayı ve Microsoft Entra ID ile mevcut bir oturumu yeniden kullanmayı deneyen ssoSilent çağrılır. Bu, Safari gibi üçüncü taraf tanımlama bilgilerini engelleyen tarayıcılarda çalışmaz. Ayrıca, "Sessiz" türü kullanılırken istek nesnesi gereklidir. Kullanıcının oturum açma bilgilerine zaten sahipseniz, belirli bir hesapla oturum açmak için isteğe bağlı loginHint veya sid parametrelerinden birini iletebilirsiniz. Not: Kullanıcının oturumuna ilişkin herhangi bir bilgi sağlamadan ssoSilent kullanıldığında ek hususlar vardır.

ssoSilent örnek

Sessiz modu kullanıyorsanız, hataları yakalamalı ve yedek seçenek olarak etkileşimli oturum açmayı denemelisiniz.

import React, { useEffect } from 'react';

import { AuthenticatedTemplate, UnauthenticatedTemplate, useMsal, useMsalAuthentication } from "@azure/msal-react";
import { InteractionType, InteractionRequiredAuthError } from '@azure/msal-browser';

function App() {
    const request = {
        loginHint: "name@example.com",
        scopes: ["User.Read"]
    }
    const { login, result, error } = useMsalAuthentication(InteractionType.Silent, request);

    useEffect(() => {
        if (error instanceof InteractionRequiredAuthError) {
            login(InteractionType.Popup, request);
        }
    }, [error]);

    const { accounts } = useMsal();

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            <AuthenticatedTemplate>
                <p>Signed in as: {accounts[0]?.username}</p>
            </AuthenticatedTemplate>
            <UnauthenticatedTemplate>
                <p>No users are signed in!</p>
            </UnauthenticatedTemplate>
        </React.Fragment>
    );
}

export default App;

Belirli kullanıcı örneği

Belirli bir kullanıcının oturum açmış olduğundan emin olmak istiyorsanız bir accountIdentifiers nesne sağlayın.

import React from 'react';
import { useMsalAuthentication } from "@azure/msal-react";
import { InteractionType } from '@azure/msal-browser';

export function App() {
    const accountIdentifiers = {
        username: "example-username"
    }
    const request = {
        loginHint: "example-username",
        scopes: ["User.Read"]
    }
    const { login, result, error } = useMsalAuthentication(InteractionType.Popup, request, accountIdentifiers);

    return (
        <React.Fragment>
            <p>Anyone can see this paragraph.</p>
            <AuthenticatedTemplate username="example-username">
                <p>Example user is signed in!</p>
            </AuthenticatedTemplate>
            <UnauthenticatedTemplate username="example-username">
                <p>Example user is not signed in!</p>
            </UnauthenticatedTemplate>
        </React.Fragment>
    );
}

Ayrıca bakınız

MSAL Browser'ın PublicClientApplication kullanıma sunduğu API'lere ilişkin belgelere ulaşabilirsiniz:

  • Last updated on