Events

Msal-Browser (@azure/msal-browser) starting at version 2.4 now provides event APIs that are available to users of our core library and wrapper libraries. These events are related to auth and what MSAL is doing, and can be used in applications to update UI, show error messages, and so on.

What events look like

export type EventMessage = {
    eventType: EventType;
    interactionType: InteractionType | null;
    payload: EventPayload;
    error: EventError;
    timestamp: number;
};

The payload and error in EventMessage are defined as follows:

export type EventPayload = PopupRequest | RedirectRequest | SilentRequest | SsoSilentRequest | EndSessionRequest | AuthenticationResult | PopupEvent | null;

export type EventError = AuthError | Error | null;

How events are emitted in msal-browser

Msal-browser has a protected function emitEvent, and emits events in major APIs. For the list of currently emitted events, see the table below.

Here is an example of how msal-browser emits an event with a payload, or with an error:

this.emitEvent(EventType.LOGIN_SUCCESS, InteractionType.Redirect, result);

this.emitEvent(EventType.LOGIN_FAILURE, InteractionType.Redirect, null, e);

How to use the event API

Msal-browser exports the addEventCallback function which takes in a callback function and can be used to process emitted events.

Here is an example of how you could consume the emitted events in your application:

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    // Update UI or interact with EventMessage here
    if (message.eventType === EventType.LOGIN_SUCCESS) {
        console.log(message.payload);
     }
});

Adding an event callback will return an id. This id can be used to remove the callback if necessary, using the removeEventCallback function exported by msal-browser:

msalInstance.removeEventCallback(callbackId);

Handling errors

Due to the way EventError is defined, handling errors emitted with an event may require validating that the error is of the correct type before accessing specific properties on the emitted error. The error can be cast to AuthError or checked that it is an instance of AuthError.

Here is an example of consuming an emitted event and casting the error:

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    // Update UI or interact with EventMessage here
    if (message.eventType === EventType.LOGIN_FAILURE) {
        if (message.error instanceof AuthError) {
            // Do something with the error
        }
     }
});

Getting interaction status from events

You can get the current interaction status from events by using the getInteractionStatusFromEvent API:

Here is an example of displaying a message when there are no interactions in progress:

const callbackId = msalInstance.addEventCallback((message: EventMessage) => {
    const status = EventMessageUtils.getInteractionStatusFromEvent(message);

    // Update UI or interact with EventMessage here
    if (status === InteractionStatus.None) {
        console.log(message.payload);
    }
});

Syncing logged in state across tabs and windows

If you would like to update your UI when a user logs in or out of your app in a different tab or window you can subscribe to the ACCOUNT_ADDED and ACCOUNT_REMOVED events. The payload will be the AccountInfo object that was added or removed.

These events will not be emitted by default. In order to enable these events you must call the enableAccountStorageEvents API before registering your event callbacks:

msalInstance.enableAccountStorageEvents();
msalInstance.addEventCallback((message: EventMessage) => {
    if (message.eventType === EventType.ACCOUNT_ADDED) {
        // Update UI with new account
    } else if (message.eventType === EventType.ACCOUNT_REMOVED) {
        // Update UI with account logged out
    }
});

You can also disable these events if no longer needed by calling disableAccountStorageEvents:

msalInstance.disableAccountStorageEvents();

Table of events

These are the events currently emitted by msal-browser.