Skip to content

Latest commit

 

History

History
405 lines (302 loc) · 21.8 KB

README-incremental.md

File metadata and controls

405 lines (302 loc) · 21.8 KB

React single-page application using MSAL React to sign-in users against Azure Active Directory

Overview

In the previous chapter, you learnt how a React single-page application (SPA) authenticating users against Azure Active Directory (Azure AD), using the Microsoft Authentication Library for React (MSAL React).

In this chapter we will extend our React single-page application (SPA) by making it also call Microsoft Graph.

Scenario

  1. The client React SPA uses MSAL React to sign-in a user and obtain a JWT access token from Azure AD.
  2. The access token is used as a bearer token to authorize the user to call the Microsoft Graph API.
  3. The Microsoft Graph API responds with the payload if user is authorized.

Overview

Contents

File/folder Description
App.jsx Main application logic resides here.
graph.jsx Instantiates Graph SDK client using MSAL as authentication provider.
authConfig.js Contains authentication configuration parameters.
pages/Home.jsx Contains a table with ID token claims and description
pages/Profile.jsx Calls Microsoft Graph /me by executing useGraphWithMsal custom hook.
pages/Contacts.jsx Calls Microsoft Graph /me/contacts by executing useGraphWithMsal custom hook.
components/AccountPicker.jsx Contains logic to handle multiple account selection with MSAL.js
hooks/useGraphWithMsal.jsx Contains token acquisition logic to call Microsoft Graph endpoints with Graph SDK.

Setup the sample

    cd ms-identity-javascript-react-tutorial
    cd 2-Authorization-I/1-call-graph/SPA
    npm install

Developers who wish to increase their familiarity with programming for Microsoft Graph are advised to go through the An introduction to Microsoft Graph for developers recorded session.

Registration

We'd make the following changes to our app registration

Update the app registration (msal-react-spa)

  1. Navigate to the Azure portal and select the Azure AD service.
  2. Select the App Registrations blade on the left, then find and select the application that you have registered in the previous tutorial (msal-react-spa).
  3. In the app's registration screen, select the API permissions blade in the left to open the page where we add access to the APIs that your application needs.
    • Select the Add a permission button and then,
    • Ensure that the Microsoft APIs tab is selected.
    • In the Commonly used Microsoft APIs section, select Microsoft Graph
    • In the Delegated permissions section, select the User.Read and Contacts.Read in the list. Use the search box if necessary.
    • Select the Add permissions button at the bottom.

Configure the app (msal-react-spa) to use your app registration

No changes are required in the configuration files.

Running the sample

From your shell or command line, execute the following commands:

    cd  2-Authorization-I/1-call-graph/SPA
    npm start

Explore the sample

  1. Open your browser and navigate to http://localhost:3000.
  2. Select the # button on the top right corner.
  3. Select the Profile button on the navigation bar. This will make a call to the Graph API.
  4. Select the Contacts button on the navigation bar. This will make a call to the Graph API (:warning: you need to have an Office subscription for this call to work).

Screenshot

ℹ️ Did the sample not work for you as expected? Then please reach out to us using the GitHub Issues page.

We'd love your feedback!

Were we successful in addressing your learning objective? Consider taking a moment to share your experience with us.

Troubleshooting

Expand for troubleshooting info

Use Stack Overflow to get support from the community. Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before. Make sure that your questions or comments are tagged with [azure-active-directory react ms-identity adal msal].

If you find a bug in the sample, raise the issue on GitHub Issues.

About the code

Protected resources and scopes

In order to access a protected resource on behalf of a signed-in user, the app needs to present a valid Access Token to that resource owner (in this case, Microsoft Graph). Access Token requests in MSAL are meant to be per-resource-per-scope(s). This means that an Access Token requested for resource A with scope scp1:

  • cannot be used for accessing resource A with scope scp2, and,
  • cannot be used for accessing resource B of any scope.

The intended recipient of an Access Token is represented by the aud claim (in this case, it should be the Microsoft Graph API's App ID); in case the value for the aud claim does not mach the resource APP ID URI, the token will be considered invalid by the API. Likewise, the permissions that an Access Token grants are provided in the scp claim. See Access Token claims for more information.

Working with multiple resources

When you have to access multiple resources, initiate a separate token request for each:

    // "User.Read" stands as shorthand for "graph.microsoft.com/User.Read"
    const graphToken = await msalInstance.acquireTokenSilent({
         scopes: [ "User.Read" ]
    });
    const customApiToken = await msalInstance.acquireTokenSilent({
         scopes: [ "api://<myCustomApiClientId>/My.Scope" ]
    });

Bear in mind that you can request multiple scopes for the same resource (e.g. User.Read, User.Write and Calendar.Read for MS Graph API).

    const graphToken = await msalInstance.acquireTokenSilent({
         scopes: [ "User.Read", "User.Write", "Calendar.Read"] // all MS Graph API scopes
    });

In case you erroneously pass multiple resources in your token request, Azure AD will throw an exception, and your request will fail.

    // your request will fail for both resources
    const myToken = await msalInstance.acquireTokenSilent({
         scopes: [ "User.Read", "api://<myCustomApiClientId>/My.Scope" ]
    });

Dynamic scopes and incremental consent

In Azure AD, the scopes (permissions) set directly on the application registration are called static scopes. Other scopes that are only defined within the code are called dynamic scopes. This has implications on the login (i.e. loginPopup, loginRedirect) and acquireToken (i.e. acquireTokenPopup, acquireTokenRedirect, acquireTokenSilent) methods of MSAL.js. Consider:

     const loginRequest = {
          scopes: [ "openid", "profile", "User.Read" ]
     };

     const tokenRequest = {
          scopes: [ "Contacts.Read" ]
     };

     // will return an ID Token and an Access Token with scopes: "openid", "profile" and "User.Read"
     msalInstance.loginPopup(loginRequest);

     // will fail and fallback to an interactive method prompting a consent screen
     // after consent, the received token will be issued for "openid", "profile", "User.Read" and "Contacts.Read" combined
     msalInstance.acquireTokenPopup(tokenRequest);

In the code snippet above, the user will be prompted for consent once they authenticate and receive an ID Token and an Access Token with scope User.Read. Later, if they request an Access Token for User.Read, they will not be asked for consent again (in other words, they can acquire a token silently). On the other hand, the user did not consented to Contacts.Read at the authentication stage. As such, they will be asked for consent when requesting an Access Token for that scope. The token received will contain all the previously consented scopes, hence the term incremental consent. Read more on this topic at Scopes, permissions and consent in the Microsoft identity platform.

Acquire a Token

MSAL.js exposes 3 APIs for acquiring a token: acquireTokenPopup(), acquireTokenRedirect() and acquireTokenSilent(). MSAL React uses these APIs underneath, while offering developers higher level hooks and templates to simplify the token acquisition process:

    const { result, error, login } = useMsalAuthentication(InteractionType.Silent, {
        account: account,
        scopes: ["user.read"]
    });

    const [graphData, setGraphData] = useState(null);

    useEffect(() => {
        if (!!graphData) {
            return
        }

        if (!!error) {
            if (error instanceof InteractionRequiredAuthError) {
                login(InteractionType.Redirect, {
                    scopes: ["user.read"]
                });
            }
            console.log(error);
        }

        if (result) {
            const { accessToken } = result;

            // do something with the access token
        }
    }, [error, result, graphData]);

    return (
        <>
            {graphData ? <ProfileData graphData={graphData} /> : null}
        </>
    )

ℹ️ Please see the documentation on acquiring an access token to learn more about various methods available in MSAL.js to acquire tokens. For MSAL React in particular, see the useIsAuthenticated hook to learn more about useMsalAuthentication hook to acquire tokens.

Handle Continuous Access Evaluation (CAE) challenge from Microsoft Graph

Continuous access evaluation (CAE) enables applications to do just-in time token validation, for instance enforcing user session revocation in the case of password change/reset but there are other benefits. For details, see Continuous access evaluation.

Microsoft Graph is now CAE-enabled in Preview. This means that it can ask its client apps for more claims when conditional access policies require it. Your can enable your application to be ready to consume CAE-enabled APIs by:

  1. Declaring that the client app is capable of handling claims challenges.
  2. Processing these challenges when they are thrown by the web API

Declare the CAE capability in the configuration

This sample app declares that it's CAE-capable by adding the clientCapabilities property in the configuration in authConfig.js:

    const msalConfig = {
        auth: {
            clientId: 'Enter_the_Application_Id_Here', 
            authority: 'https://#.microsoftonline.com/Enter_the_Tenant_Info_Here',
            redirectUri: "/", 
            postLogoutRedirectUri: "/",
            navigateToLoginRequestUrl: true, 
            clientCapabilities: ["CP1"] // this lets the resource owner know that this client is capable of handling claims challenge.
        }
    }

    const msalInstance = new PublicClientApplication(msalConfig);

Processing the CAE challenge from Microsoft Graph

Once the client app receives the CAE claims challenge from Microsoft Graph, it needs to present the user with a prompt for satisfying the challenge via Azure AD authorization endpoint. To do so, we use MSAL's useMsalAuthentication hook and provide the claims challenge as a parameter in the token request. This is shown in the useGraphWithMsal custom hook:

const useGraphWithMsal = (request, endpoint) => {
    const [error, setError] = useState(null);
    const { instance } = useMsal();

    const account = instance.getActiveAccount();
    const resource = new URL(endpoint).hostname;

    const claims =
        account && getClaimsFromStorage(`cc.${msalConfig.auth.clientId}.${account.idTokenClaims.oid}.${resource}`)
            ?
            window.atob(getClaimsFromStorage(`cc.${msalConfig.auth.clientId}.${account.idTokenClaims.oid}.${resource}`))
            :
            undefined; // e.g {"access_token":{"xms_cc":{"values":["cp1"]}}}

    const { result, login, error: msalError } = useMsalAuthentication(InteractionType.Popup, {
        ...request,
        redirectUri: '/redirect',
        account: account,
        claims: claims,
    });

    /**
     * Execute a fetch request with Graph SDK
     * @param {String} endpoint
     * @returns JSON response
     */
    const execute = async (endpoint) => {
        if (msalError) {
            setError(msalError);
            return;
        }

        if (result) {
            let accessToken = result.accessToken;

            try {
                const graphResponse = await getGraphClient(accessToken)
                    .api(endpoint)
                    .responseType(ResponseType.RAW)
                    .get();

                const responseHasClaimsChallenge = await handleClaimsChallenge(graphResponse, endpoint, account);
                return responseHasClaimsChallenge;

            } catch (error) {
                if (error.name === 'ClaimsChallengeAuthError') {
                    login(InteractionType.Redirect, request);
                } else {
                    setError(error);
                }
            }
        }
    };

    return {
        error,
        result: result,
        execute: useCallback(execute, [result, msalError]),
    };
};

Access token validation

Clients should treat access tokens as opaque strings, as the contents of the token are intended for the resource only (such as a web API or Microsoft Graph). For validation and debugging purposes, developers can decode JWTs (JSON Web Tokens) using a site like jwt.ms.

For more details on what's inside the access token, clients should use the token response data that's returned with the access token to your client. When your client requests an access token, the Microsoft identity platform also returns some metadata about the access token for your app's consumption. This information includes the expiry time of the access token and the scopes for which it's valid. For more details about access tokens, please see Microsoft identity platform access tokens

Calling the Microsoft Graph API

Microsoft Graph JavaScript SDK provides various utility methods to query the Graph API. While the SDK has a default authentication provider that can be used in basic scenarios, it can also be extended to use with a custom authentication provider such as MSAL. To do so, we will initialize the Graph SDK client with an authProvider function. In this case, user has to provide their own implementation for getting and refreshing access tokens.

    export const getGraphClient = (accessToken) => {
    // Initialize Graph client
    const graphClient = Client.init({
        // Use the provided access token to authenticate requests
        authProvider: (done) => {
            done(null, accessToken);
        },
    });

    return graphClient;
};

The Graph client then can be used in your application as shown in the useGraphWithMsal custom hook.

Working with React routes

You can use React Router component in conjunction with MSAL React. Simply wrap the MsalProvider component between the Router component, passing the PublicClientApplication instance you have created earlier as props:

    const msalInstance = new PublicClientApplication(msalConfig);

    root.render(
        <React.StrictMode>
            <BrowserRouter>
                <App instance={msalInstance} />
            </BrowserRouter>
        </React.StrictMode>
    );

    export const App = ({ instance }) => {
        return (
            <MsalProvider instance={msalInstance}>
                <PageLayout>
                    <Pages />
                </PageLayout>
            </MsalProvider>
        );
    };

    const Pages = () => {
        return (
            <Routes>
                <Route path="/profile" element={<Profile />} />
                <Route path="/contacts" element={<Contacts />} />
                <Route path="/" element={<Home />} />
            </Routes>
        );
    };

MSAL logging

The Microsoft Authentication Library (MSAL) apps generate log messages to help diagnose issues. An app can configure logging with a few lines of code and have custom control over the level of detail and whether or not personal and organizational data is logged. Please check the authConfig.js file to see an example of configuring the logger with MSAL.js. For more information about using the logger with MSAL.js, see the following Logging in MSAL.js.

Next Steps

Continue with the next tutorial: Protect and call a web API.

Contributing

If you'd like to contribute to this sample, see CONTRIBUTING.MD.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Learn More