Mulai menggunakan MSAL React

Artikel ini akan memandu Anda memulai penggunaan @azure/msal-react. Kami akan membahas inisialisasi, menentukan apakah pengguna diautentikasi, melindungi komponen, memasukkan pengguna, dan memperoleh token akses.

Prasyarat

Inisialisasi

@azure/msal-react dibangun menggunakan API konteks React, dan semua bagian aplikasi Anda yang memerlukan autentikasi harus dibungkus dengan komponen MsalProvider. Pertama, Anda perlu menginisialisasi instance PublicClientApplication lalu meneruskannya ke MsalProvider sebagai prop.

import React from "react";
import { createRoot } from "react-dom/client";

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

import App from "./app.jsx";

// MSAL configuration
const configuration: Configuration = {
    auth: {
        clientId: "client-id"
    }
};

const pca = new PublicClientApplication(configuration);

// Component
const AppProvider = () => (
    <MsalProvider instance={pca}>
        <App />
    </MsalProvider>
);

const root = createRoot(document.getElementById("root"));
root.render(<AppProvider />);

Semua komponen di bawah MsalProvider akan memiliki akses ke instans PublicClientApplication melalui konteks serta semua kait dan komponen yang disediakan oleh @azure/msal-react.

Menentukan apakah pengguna diautentikasi

Sebagian besar aplikasi harus merender komponen tertentu secara kondisional berdasarkan apakah pengguna masuk atau tidak. @azure/msal-react menyediakan 2 cara mudah untuk melakukan ini.

AuthenticatedTemplate dan UnauthenticatedTemplate

Komponen AuthenticatedTemplate dan UnauthenticatedTemplate hanya akan menampilkan elemen turunannya jika pengguna masing-masing terautentikasi atau tidak terautentikasi.

import React from 'react';
import { AuthenticatedTemplate, UnauthenticatedTemplate } from "@azure/msal-react";

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

useIsAuthenticated Hook

Sebagai alternatif dari komponen wrapper di atas, aplikasi Anda dapat menggunakan hook useIsAuthenticated. Anda dapat membaca lebih lanjut mengenai hal ini dalam Hooks di MSAL React.

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>
    );
}

Melindungi Komponen

Jika Anda memiliki komponen yang hanya ingin ditampilkan kepada pengguna terautentikasi, Anda dapat menggunakan salah satu metode di atas. Tetapi bagaimana jika Anda ingin secara otomatis memanggil login jika pengguna belum diautentikasi? @azure/msal-react menyediakan 2 cara untuk melakukannya dengan MsalAuthenticationTemplate atau hook useMsalAuthentication.

MsalAuthenticationTemplate komponen

Komponen MsalAuthenticationTemplate akan menampilkan elemen turunannya jika pengguna terautentikasi atau mencoba memasukkan pengguna ke sistem. Cukup berikan dengan jenis interaksi yang ingin Anda gunakan (pengalihan atau popup) dan secara opsional objek permintaan untuk diteruskan ke API login, komponen yang akan ditampilkan saat autentikasi sedang berlangsung atau komponen untuk ditampilkan jika terjadi kesalahan.

Anda dapat menemukan contoh yang berfungsi dari ini di salah satu sampel kami di /profile halaman.

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

function ErrorComponent({error}) {
    return <p>An Error Occurred: {error}</p>;
}

function LoadingComponent() {
    return <p>Authentication in progress...</p>;
}

export function Example() {
    const authRequest = {
        scopes: ["openid", "profile"]
    };

    return (
        // authenticationRequest, errorComponent and loadingComponent props are optional
        <MsalAuthenticationTemplate 
            interactionType={InteractionType.Popup} 
            authenticationRequest={authRequest} 
            errorComponent={ErrorComponent} 
            loadingComponent={LoadingComponent}
        >
            <p>At least one account is signed in!</p>
        </MsalAuthenticationTemplate>
      )
};

useMsalAuthentication Hook

Hook useMsalAuthentication pertama-tama akan memeriksa apakah pengguna masuk, lalu mencoba memasukkan pengguna jika tidak ada pengguna yang masuk. Anda harus menyediakan jenis interaksi yang ingin Anda gunakan (pengalihan atau popup). Ini akan mengembalikan hasil operasi masuk, kesalahan apa pun yang terjadi dan fungsi login yang dapat Anda gunakan jika Anda perlu mencoba kembali.

Anda dapat membaca lebih lanjut tentang hook ini di dokumentasi hook.

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

export function App() {
    const {login, result, error} = useMsalAuthentication(InteractionType.Popup);

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

Memasukkan pengguna menggunakan API masuk yang disediakan oleh @azure/msal-browser

Cara lain untuk memicu proses masuk adalah dengan menggunakan @azure/msal-browser API secara langsung dari instans PublicClientApplication dalam konteks. Ada 3 cara untuk mengakses instans melalui konteks.

useMsal Hook

hook yang mengembalikan instans PublicClientApplication, array semua akun yang saat ini masuk, serta nilai inProgress yang memberi tahu Anda apa yang sedang dilakukan oleh msal.

Anda dapat membaca lebih lanjut tentang hook ini di dokumentasi hook.

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

export function App() {
    const { instance, accounts, inProgress } = useMsal();

    if (accounts.length > 0) {
        return <span>There are currently {accounts.length} users signed in!</span>
    } else if (inProgress === "login") {
        return <span>Login is currently in progress!</span>
    } else {
        return (
            <>
                <span>There are currently no users signed in!</span>
                <button onClick={() => instance.loginPopup()}>Login</button>
            </>
        );
    }
}

Menggunakan konteks mentah

Jika Anda menggunakan komponen kelas dan tidak dapat menggunakan hook, Anda dapat mengakses konteks MSAL mentah melalui MsalContext. Anda dapat membaca selengkapnya tentang menggunakan @azure/msal-react komponen kelas di sini.

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

class App extends React.Component {
    static contextType = MsalContext;

    render() {
        if (this.context.accounts.length > 0) {
            return <span>There are currently {this.context.accounts.length} users signed in!</span>
        } else if (this.context.inProgress === "login") {
            return <span>Login is currently in progress!</span>
        } else {
            return (
                <>
                    <span>There are currently no users signed in!</span>
                    <button onClick={() => this.context.instance.loginPopup()}>Login</button>
                </>
            );
        }
    }
}

Membungkus komponen Anda dengan withMsalOrder-Component Yang Lebih Tinggi

Cara lain untuk mengakses konteks MSAL baik dalam komponen class maupun function adalah dengan membungkus komponen Anda menggunakan HOC withMsal, yang akan menyisipkan konteks tersebut ke dalam props komponen Anda.

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

class LoginButton extends React.Component {
    render() {
        const isAuthenticated = this.props.msalContext.accounts.length > 0;
        const msalInstance = this.props.msalContext.instance;
        if (isAuthenticated) {
            return <button onClick={() => msalInstance.logout()}>Logout</button>    
        } else {
            return <button onClick={() => msalInstance.loginPopup()}>Login</button>
        }
    }
}

export default YourWrappedComponent = withMsal(LoginButton);

Memperoleh token akses

Sebaiknya aplikasi Anda memanggil acquireTokenSilent API pada objek Anda PublicClientApplication setiap kali Anda memerlukan token akses untuk mengakses API. Hal ini dapat dilakukan dengan cara yang serupa dengan yang diuraikan pada bagian sebelumnya.

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

export function App() {
    const { instance, accounts, inProgress } = useMsal();
    const account = useAccount(accounts[0] || {});
    const [apiData, setApiData] = useState(null);

    useEffect(() => {
        if (account) {
            instance.acquireTokenSilent({
                scopes: ["User.Read"],
                account: account
            }).then((response) => {
                if(response) {
                    callMsGraph(response.accessToken).then((result) => setApiData(result));
                }
            });
        }
    }, [account, instance]);

    if (accounts.length > 0) {
        return (
            <>
                <span>There are currently {accounts.length} users signed in!</span>
                {apiData && (<span>Data retreived from API: {JSON.stringify(apiData)}</span>)}
            </>
        );
    } else if (inProgress === "login") {
        return <span>Login is currently in progress!</span>
    } else {
        return <span>There are currently no users signed in!</span>
    }
}

Memperoleh token akses di luar komponen React

Jika Anda memerlukan token akses di luar komponen React, Anda dapat langsung memanggil acquireTokenSilent fungsi pada PublicClientApplication. Kami tidak menyarankan fungsi panggilan yang mengubah status terautentikasi pengguna (masuk, keluar) di luar konteks react yang disediakan oleh MsalProvider karena komponen di dalam konteks mungkin tidak diperbarui dengan benar.

Perlu diingat bahwa pengguna harus masuk sebelum Anda dapat memperoleh token.

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

// This should be the same instance you pass to MsalProvider
const msalInstance = new PublicClientApplication(config);

const acquireAccessToken = async (msalInstance) => {
    const activeAccount = msalInstance.getActiveAccount(); // This will only return a non-null value if you have logic somewhere else that calls the setActiveAccount API
    const accounts = msalInstance.getAllAccounts();

    if (!activeAccount && accounts.length === 0) {
        /*
        * User is not signed in. Throw error or wait for user to login.
        * Do not attempt to log a user in outside of the context of MsalProvider
        */   
    }
    const request = {
        scopes: ["User.Read"],
        account: activeAccount || accounts[0]
    };

    const authResult = await msalInstance.acquireTokenSilent(request);

    return authResult.accessToken
};

Baca juga

  • Last updated on