@calvear/test-ui v0.0.9

React Azure MSAL Security

Azure Active Directory security module using MSAL

React library for application security (using MSAL) that eases application protection with Azure session JWT. Exposes multiples hooks for login, logout and secure components.

Structure 📋

├── README.md
├── LICENCE.md
├── CHANGELOG.md
├── .vscode/ # vscode shared development config
├── src/
│   ├── security/
│   │   ├── config/
│   │   │   ├── aad.config.js # MSAL config initialization
│   │   │   └── aad.types.js # AAD and Ms Graph constants
│   │   ├── services/
│   │   │   ├── aad-graph.service.js # basic graph service for user info and avatar
│   │   │   └── aad.service.js # service for handle login, sso and token acquisition
│   │   ├── auth.hook.js # module hooks
│   │   ├── cache.util.js # util for persist graph info
│   │   └── observer.util.js # observer pattern handler
│   └── index.js
├── package.json
├── jsconfig.js
├── .babelrc
├── .eslintrc.json
└── .prettierrc.json

Features 🎉

✅ Centralized and synchronized session state handling for any authentication event.

✅ Automatic and manual login hooks.

✅ Logout, state and token acquisition hooks.

✅ Refresh token route handler.

✅ User specific profile info and avatar hooks, using Microsoft Graph.

⚠️ Easy to use! but a little hard to customize, i.e. user graph info.

How To Configure 📖

First, you should register a new Azure Active Directory Application in Azure Portal.

In Authentication section add a new platform, selecting Single-Page Application (SPA) and setting up Redirect URIs only, with host (base URL) and token auth URL, for example, for dev:

• https://localhost:3000/
• https://localhost:3000/auth

Also, in this section, enable Access tokens and ID tokens in Implicit grant sub-section.

Finally, you should configure permissions in API permissions section, with the minimum permission User.Read, although ideally profile and openid for correct token acquisition.

How To Use 💡

This module, exposes many hooks for handle login, logout and secure React components.

App configuration

In your App.jsx or App.router.jsx you should initialize the authentication service.

import { AuthenticationService } from '@calvear/react-azure-msal-security';

// MSAL config.
const authConfig = {
    clientId: '2a85c521-02fc-4796-8ecc-eaa13eee2e7b', // registered app id from azure
    tenantId: 'ba3947ca-abb7-402e-b1d1-c9284608f497', // maybe common, organizations or consumers also
    loginActionRedirect: '/',
    logoutActionRedirect: null,
    tokenRefreshUri: '/auth', // should exists a blank route in your app
    tokenRenewalOffset: 120,
    navigateToRequestAfterLogin: true,
};

// initializes Microsoft Active Directory authentication service.
AuthenticationService.init(authConfig);

// main react component
export default () => {
    return (
        <div>
            <h1>Welcome to My App</h1>
        </div>
    );
};

For tenantId also see MSAL Client Config

Token acquisition and blank page/route

For a correct authentication and token renewal operation you should define a blank page or route in your application. This route will be used as iframe for retrieve or renew the token on authentication.

For example, if you're using react-spa-routerizer

// routes.js

export default [
    ...,
    // blank html page for load authentication iframe to refresh the token,
    // also, you should set tokenRefreshUri as '/auth' route.
    {
        key: 'auth-page',
        title: 'Authenticating',
        path: '/auth',
        Child: () => null
    },
    ...
];

☑️ Check Authentication State

import { useAuthenticationState } from '@calvear/react-azure-msal-security';

// react component
export default () => {
    const { authenticated, authenticating, error } = useAuthenticationState();

    return (
        <div>
            <h1>User is authenticated?: {authenticated ? 'yeah' : 'no'}</h1>
        </div>
    );
};

☑️ Automatic Login

import { useAuthentication } from '@calvear/react-azure-msal-security';

// react component
export default () => {
    const { authenticated, authenticating, error } = useAuthentication();

    if (authenticating) return <div>Authenticating...</div>;

    if (!authenticated) return <div>403: Not Authorized - {error.message}</div>;

    return (
        <div>
            <h1>Welcome to My App</h1>
        </div>
    );
};

☑️ Manual Login

import { Redirect } from 'react-router-dom';
import { useAuthenticationState, useLogin } from '@calvear/react-azure-msal-security';

// react component
export default () => {
    const login = useLogin();
    const { authenticated, authenticating, error } = useAuthenticationState();

    if(authenticating)
        return <div>Authenticating...</div>;

    if(!authenticated)
        return <div>403: Not Authorized - {error.message}</div>;

    if(authenticated)
        return <Redirect to='/home'>;

    return (
        <div>
            <button onClick={login}>Log In</button>
        </div>
    );
}

☑️ Logout

import { useLogout } from '@calvear/react-azure-msal-security';

// react component
export default () => {
    const logout = useLogout();

    return (
        <div>
            <button onClick={logout}>Log Out</button>
        </div>
    );
};

☑️ Acquire Token

You can acquire a JWT access token for API securing.

import { useState, useEffect } from 'react';
import { useAcquireToken } from '@calvear/react-azure-msal-security';

// react component
export default () => {
    const [token, setToken] = useState();
    const { authenticated } = useAuthentication();
    // use it only if authentication was succeeded
    const acquireToken = useAcquireToken();

    useEffect(() => {
        if (authenticated) {
            acquireToken().then((tkn) => setToken(tkn));
        }
    }, [authenticated]);

    return (
        <div>
            <h1>Welcome to My App</h1>
        </div>
    );
};

☑️ Graph Info

You can retrieves user account detailed info and profile avatar from Microsoft Graph api with hooks.

import { useAccountInfo } from '@calvear/react-azure-msal-security';

// react component
export default () => {
    const { loading, info, error } = useAccountInfo();

    if (loading) return <div>Loading User Info...</div>;

    if (error) return <div>User info cannot be loaded: {error.message}</div>;

    return (
        <div>
            <h1>User Info</h1>
            <h3>Name: {info.displayName}</h3>
        </div>
    );
};

import { useAccountAvatar } from '@calvear/react-azure-msal-security';

// react component
export default () => {
    const { loading, avatar, error } = useAccountAvatar();

    if (loading) return <div>Loading User Avatar...</div>;

    if (error) return <div>User avatar cannot be loaded: {error.message}</div>;

    return (
        <div>
            <img alt="user-avatar" src={avatar} />
        </div>
    );
};

Linting 🧿

Project uses ESLint, for code formatting and code styling normalizing.

• eslint: JavaScript and React linter with Airbnb React base config and some other additions.
• prettier: optional Prettier config.

For correct interpretation of linters, is recommended to use Visual Studio Code as IDE and install the plugins in .vscode folder at 'extensions.json', as well as use the config provided in 'settings.json'

Changelog 📄

For last changes see CHANGELOG.md file for details.

Built with 🛠️

• React - the most fabulous JavaScript framework.
• MSAL - Microsoft Authentication Library for JavaScript.
• axios - Promise based HTTP client.

License 📄

This project is licensed under the MIT License - see LICENSE.md file for details.

⌨ by Alvear Candia, Cristopher Alejandro