MSAL v1'den `@azure/msal-react` ve `@azure/msal-browser`'e Geçiş Kılavuzu

Bu makale, MSAL v1’den @azure/msal-react ve @azure/msal-browser’e geçişe genel bir bakış sunar. PKCE ve Koşullu Erişim ile yetkilendirme kodu akışıyla gelişmiş performans ve daha iyi güvenlik için geçişi öneririz. Ayrıca, tek sayfalı uygulama desteği daha iyidir.

Prerequisites

Aktif bir aboneliğe sahip bir Azure hesabı. Ücretsiz hesap oluşturma
Microsoft Entra kiracınızda kayıtlı mevcut bir uygulama.

Uygulama kaydınızı güncelleştirme

@azure/msal-react kitaplığı, PKCE ile Yetkilendirme Kodu Akışı'nı uygulayan @azure/msal-browser etrafında bir sarmalayıcıdır. Bu, Örtük Akışı uygulayan MSAL v1 kitaplığından önemli bir güncelleştirmedir.

Yeni "SPA" türünü kullanmak redirectUri için yeni bir uygulama kaydı oluşturmanız veya mevcut bir kaydı güncelleştirmeniz gerekir. Daha fazla bilgi için Tek sayfalı uygulama: Uygulama kaydı bölümüne bakın.

`@azure/msal-react` ve `@azure/msal-browser` yüklenmesi

Hem @azure/msal-react hem de eş bağımlılığı olan @azure/msal-browser npm'den yüklenebilir. Eski MSAL paketinizi kaldırmak önemlidir. Bir terminal açın ve aşağıdaki komutları çalıştırın.

npm uninstall msal
npm install @azure/msal-react @azure/msal-browser

`react-aad-msal` sürümünden yükseltme

Uygulamanız şu anda kimlik doğrulaması için React Microsoft Entra MSAL kullanıyorsa ve bu bölüme @azure/msal-react geçiş yapmak istiyorsanız, iki kitaplık arasındaki farklar ve yapmanız gereken bazı değişiklikler özetlenir. React Microsoft Entra MSAL bir 3. taraf kitaplığıdır ve MSAL React sıfırdan oluşturulmuş olup, MSAL React tarafından kapsanmayan veya desteklenmeyen bazı uç durumlar olabilir.

Aşağıdakiler, react-aad-msal içinde desteklenen ancak @azure/msal-react içinde desteklenmeyen özelliklerdir:

Korumalı bileşenleri işlemeden önce IdToken süre sonunu doğrulama ve süresi dolan IdTokens'in otomatik olarak yenilenmesi
Redux mağazası için kullanıma hazır destek (aşağıdaki alternatif)

react-aad-msal ile mümkün olan ancak @azure/msal-react ile artık mümkün olmayan diğer durumlar için, microsoft-authentication-library-for-js GitHub deposunda bir sorun kaydı açın.

Başlatma İşlemi

react-aad-msal içinde, daha sonra AzureAD bileşenine aktarılacak bir MsalAuthProvider nesnesi oluşturarak MSAL örneğinizi başlatırsınız.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);

@azure/msal-react içinde, @azure/msal-browser içinden dışa aktarılan PublicClientApplication öğesini kullanarak MSAL örneğinizi başlatırsınız; ardından bu örnek, @azure/msal-react içinden dışa aktarılan MsalProvider bileşenine aktarılır. Yapılandırma seçenekleri ile arasında msal@azure/msal-browserbüyük ölçüde benzerdir, ancak en güncel yapılandırma seçenekleri için Yapılandırma türü'ne başvurabilirsiniz.

react-aad-msal içinde kullanılan authenticationParameters ve options parametreleri, @azure/msal-react içinde kullanılmaz; ancak benzer işlevsellik tek tek bileşenlerde sağlanabilir. Bu, bu belgenin ilerleyen bölümlerinde açıklanacaktır.

@azure/msal-react, React Context API'sini kullanarak PublicClientApplication ve kimlik doğrulama durumunu bileşen ağacınızın tamamında kullanılabilir hale getirir.

import { PublicClientApplication } from "@azure/msal-browser";
import { MsalProvider } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <YourAppComponents />
        </MsalProvider>
    );
}

Bileşen hakkında genel notlar MsalProvider :

Kimlik doğrulama durumuna veya @azure/msal-react tarafından kullanıma sunulan kancalara/bileşenlere erişmesi gereken tüm bileşenlerin, bileşen ağacında daha yukarıda bir MsalProvider bulunması gerekir; bu nedenle MsalProvider öğesinin mümkün olduğunca köke yakın oluşturulması önerilir.
Uygulamanız belirli bir sayfada 1'den MsalProvider fazla bileşen işlememelidir.
PublicClientApplication öğesini, yeniden işleme olasılığı nedeniyle bir bileşenin içinde başlatmanızı önermiyoruz

Bileşenlerinizi koruma

react-aad-msal içinde bileşenler, bileşeninizi arka planda AzureAD ile saran AzureAD bileşeni veya withAuthentication HOC kullanılarak korunur. Bileşen AzureAD yalnızca kullanıcının kimliği doğrulanırsa alt bileşenleri işler ve kullanıcının kimliği doğrulanmamışsa isteğe bağlı olarak oturum açma işlemi başlatır. Oturum açmak için kullanılan seçenekler (örn. kapsamlar, açılır pencerenin mi yoksa yeniden yönlendirmenin mi kullanılacağı gibi) daha önce, authProvider prop’u oluşturulurken belirtilir.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);

function App() {
    return (
        <AzureAD provider={authProvider} forceLogin={true}>
            <span>Only authenticated users can see me.</span>
        </AzureAD>
    );
}

@azure/msal-reactdiğer yandan, geliştiricilere kime göstermek istedikleri üzerinde daha fazla denetim sağlar.

AuthenticatedTemplate bileşeni, kullanıcı kimliği doğrulanmışsa alt öğeleri görüntüler
Kullanıcının kimliği doğrulanmamışsa UnauthenticatedTemplate bileşeni alt öğeleri oluşturur
MsalAuthenticationTemplate bileşeni, kullanıcının kimliği doğrulanmamışsa otomatik olarak oturum açma işlemi başlatır ve kullanıcının kimliği doğrulandıktan sonra alt öğeleri görüntüler.

import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalProvider, AuthenticatedTemplate, UnauthenticatedTemplate, MsalAuthenticationTemplate } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <AuthenticatedTemplate>
                <span>Only authenticated users can see me.</span>
            </AuthenticatedTemplate>
            <UnauthenticatedTemplate>
                <span>Only unauthenticated users can see me.</span>
            </UnauthenticatedTemplate>
            <MsalAuthenticationTemplate interactionType={InteractionType.Popup} authenticationRequest={request}>
                <span>Only authenticated users can see me. Unauthenticated users will get a popup asking them to login first.</span>
            </MsalAuthenticationTemplate>
        </MsalProvider>
    );
}

Ayrıca, kanca tabanlı bir yaklaşım @azure/msal-react kullanmayı tercih ederseniz benzer sonuçlar elde etmek için kullanabileceğiniz çeşitli kancalar sağlar. Bunlar yalnızca bazı temel örneklerdir ve daha fazla bilgi için MSAL React kancalarına başvurabilirsiniz.

import { PublicClientApplication, InteractionType } from "@azure/msal-browser";
import { MsalProvider, useIsAuthenticated, useMsalAuthentication } from "@azure/msal-react";

const pca = new PublicClientApplication(config);

function App() {
    return (
        <MsalProvider instance={pca}>
            <ExampleComponent />
        </MsalProvider>
    );
}

function ExampleComponent() {
    const isAuthenticated = useIsAuthenticated();
    const { error } = useMsalAuthentication(InteractionType.Popup, request); // Will initiate a popup login if user is unauthenticated

    if (isAuthenticated) {
        return <span>Only authenticated users can see me.</span>
    } else if (error) {
        return <span>An error occurred during login!</span>
    } else {
        return <span>Only unauthenticated users can see me.</span>
    }
}

Erişim belirteci alma

react-aad-msal API'yi getAccessToken çağırmadan önce erişim belirteci almak için kullanabileceğiniz bir yöntemi kullanıma sunar.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);
const accessToken = authProvider.getAccessToken();

@azure/msal-react ve @azure/msal-browser kullanırken, PublicClientApplication örneği üzerinde acquireTokenSilent çağrısı yapacaksınız.

MsalProvider altında yer alan bir bileşen veya hook içinde bir erişim belirteci edinmeniz gerekiyorsa, ihtiyaç duyduğunuz nesneleri almak için useMsal hook’unu kullanabilirsiniz.

import { useState } from "react";
import { useMsal } from "@azure/msal-react";
import { InteractionRequiredAuthError } from "@azure/msal-browser";

function useAccessToken() {
    const { instance, accounts } = useMsal();
    const [accessToken, setAccessToken] = useState(null);

    if (accounts.length > 0) {
        const request = {
            scopes: ["User.Read"],
            account: accounts[0]
        };
        instance.acquireTokenSilent(request).then(response => {
            setAccessToken(response.accessToken);
        }).catch(error => {
            // acquireTokenSilent can fail for a number of reasons, fallback to interaction
            if (error instanceof InteractionRequiredAuthError) {
                instance.acquireTokenPopup(request).then(response => {
                    setAccessToken(response.accessToken);
                });
            }
        });
    }

    return accessToken;
}

MsalProvider bağlamı dışında bir erişim belirteci almanız gerekiyorsa, PublicClientApplication örneğini doğrudan kullanabilir ve hesap nesnesini almak için getAllAccounts() çağrısını yapabilirsiniz.

Important

Yalnızca MsalProvider bağlamı dışında sessiz belirteç alımını deneyin. bağlamının MsalProviderdışında etkileşimli bir yöntem (yeniden yönlendirme veya açılır pencere) çağırmamalısınız.

Aşağıdaki örnek, gösterim amacıyla PublicClientApplication başlatılmasını göstermektedir. PublicClientApplication sayfa başına yalnızca bir kez başlatılmalıdır ve burada da MsalProvider bileşenine sağladığınız örneğin aynısını kullanmalısınız.

import { PublicClientApplication } from "@azure/msal-browser";

const pca = new PublicClientApplication(config);
const accounts = pca.getAllAccounts();

async function getAccessToken() {
    if (accounts.length > 0) {
        const request = {
            scopes: ["User.Read"],
            account: accounts[0]
        }
        const accessToken = await pca.acquireTokenSilent(request).then((response) => {
            return response.accessToken;
        }).catch(error => {
            // Do not fallback to interaction when running outside the context of MsalProvider. Interaction should always be done inside context.
            console.log(error);
            return null;
        });

        return accessToken;
    }

    return null;
}

Kimlik belirteci alma

react-aad-msal, idToken almak veya yenilemek için bir getIdToken işlevini kullanıma açtı.

import { MsalAuthProvider } from "react-aad-msal";

const authProvider = new MsalAuthProvider(config, authenticationParameters, options);
const token = await authProvider.getIdToken();
const idToken = token.idToken.rawIdToken;

Ayrıca, bir idToken almak için yalnızca clientId kapsamını isteme yaklaşımına da aşina olabilirsiniz. Bu, @azure/msal-browser içinde artık desteklenen bir kullanım biçimi değildir.

ve @azure/msal-react@azure/msal-browser tüm belirteç çağrıları hem erişim belirteci hem de kimlik belirteci döndürür ve tüm erişim belirteci yenilemeleri de kimlik belirtecini yeniler.

MsalProvider altında yer alan bir bileşen veya kanca içinde bir ID belirteci edinmeniz gerekiyorsa, ihtiyacınız olan nesneleri elde etmek için useMsal kancasını kullanabilirsiniz.

import { useState } from "react";
import { useMsal } from "@azure/msal-react";

function useIdToken() {
    const { instance, accounts } = useMsal();
    const [idToken, setIdToken] = useState(null);

    if (accounts.length > 0) {
        const request = {
            scopes: ["openid"],
            account: accounts[0]
        };
        instance.acquireTokenSilent(request).then(response => {
            setIdToken(response.idToken);
        }).catch(error => {
            // acquireTokenSilent can fail for a number of reasons, fallback to interaction
            if (error instanceof InteractionRequiredAuthError) {
                instance.acquireTokenPopup(request).then(response => {
                    setIdToken(response.idToken);
                });
            }
        });
    }

    return idToken;
}

MsalProvider bağlamı dışında bir kimlik belirteci almanız gerekiyorsa, PublicClientApplication örneğini doğrudan kullanabilir ve hesap nesnesini almak için getAllAccounts() çağrısını yapabilirsiniz.

Important

Yalnızca MsalProvider bağlamı dışında sessiz belirteç alma girişiminde bulunun. bağlamının MsalProviderdışında etkileşimli bir yöntem (yeniden yönlendirme veya açılır pencere) çağırmamalısınız.

Aşağıdaki örnek, gösterim amacıyla PublicClientApplication öğesinin başlatılmasını göstermektedir. PublicClientApplication, sayfa başına yalnızca bir kez başlatılmalıdır ve burada MsalProvider için sağladığınız aynı örneği kullanmalısınız.

import { PublicClientApplication } from "@azure/msal-browser";

const pca = new PublicClientApplication(config);
const accounts = pca.getAllAccounts();

async function getIdToken() {
    if (accounts.length > 0) {
        const request = {
            scopes: ["openid"],
            account: accounts[0]
        }
        const idToken = await pca.acquireTokenSilent(request).then((response) => {
            return response.idToken;
        }).catch (error => {
            // Do not fallback to interaction when running outside the context of MsalProvider. Interaction should always be done inside context.
            console.log(error);
            return null;
        });

        return idToken
    }

    return null;
}

Redux mağazası tümleştirmesini güncelleştirme / olaylara tepki verme

react-aad-msal oturum açma veya oturumu kapatma gibi olaylar gerçekleştiğinde aksiyonları dispatch ederek bir Redux deposuyla kutudan çıktığı gibi entegrasyon sağladı. @azure/msal-reactbu özelliği sağlamaz, ancak tarafından kullanıma sunulan @azure/msal-browser kullanarak benzer işlevler elde edilebilir.

Bir olay her yayımlandığında çağrılacak bir olay geri çağırma işlevi kaydedebilirsiniz (ör. LOGIN_SUCCESS). Geri çağırma fonksiyonunuz olayı inceleyebilir ve yük üzerinde bir işlem yapabilir. Mevcut redux mağazanızı kullanmaya devam etmek isterseniz, mağazanıza eylemler dağıtan bir olay geri çağırması kaydedebilirsiniz.

import { PublicClientApplication, EventType } from "@azure/msal-browser";
import { store } from "your-redux-store-implementation";

const msalInstance = new PublicClientApplication(config);

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    if (message.eventType === EventType.LOGIN_SUCCESS) {
        store.dispatchAction({type: "AAD_LOGIN_SUCCESS", payload: message.payload});
    }
});

msal v1 ile @azure/msal-browser arasındaki yükler farklılık gösterebilir; bu nedenle uygulamanız belirli alanlara veya nesnenin yapısına bağlıysa bazı ayarlamalar yapmanız gerekebilir. Typedocs'larımız olay türlerinin ve yük türlerinin en güncel listesini içerir ve ikisi arasındaki eşlemeyi olay belgesinde bulabilirsiniz.

Ayrıca bakınız

MSAL React Tür Takma Adları

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-02