fb-ms-approles v0.2.0

README

This project has the basic logic needed to sync the application roles assigned to a user in Microsoft Azure AD to the roles in the Firebase token upon login on that user using Firebase Authentication.

What is this repository for?

• Quick summary

When using Firebase Authentication using Microsoft, it is convenient to be able to use the Application Roles defined in Azure AD in the Firebase token. Natively, these roles are not present in the Firebase JWT token. This project includes the logic for a Firebase function defined as an Auth trigger to transfer these roles to the Firebase token and keep it updated.

Note that this requires the Blocking Functions functionality of Firebase, which is not included in the Free plan. However, given if you use Microsoft Azure AD, you probably have an Enterprise license anyway, so this shouldn't be an issue.

• Version

This is version 0.1.1

How do I get set up?

• Summary of set up:

To set up this library you need to include it as a dependency and expose a Firebase function created by this library using one of the two ways provided. You can either use the default setup of this hook, using the beforeSignIn function exposed by this library. Alternatively, in case you need more flexibility in configuring the hook, you can use the firebaseMsAppRoleHook method which has an options object as parameter (see Configuration below).

A full example:

import {beforeSignIn} from "fb-ms-approles";
exports.beforeSignIn = beforeSignIn;

• Configuration

To configure the authentication hook (using firebaseMsAppRoleHook), you can pass an options object into this function:

type CustomHook<TokenType extends AccessTokenWithRole = AccessTokenWithRole> = (token: TokenType) => object;

interface HookOptions<TokenType extends AccessTokenWithRole = AccessTokenWithRole> {
    /**
     * Instructs the hook to log sensitive data (i.e. the full event context including the users' JWT token
     * provided by Microsoft. This can be used for debugging purposes, but should not be used in production.
     */
    includeSensitive: boolean,
    /**
     * Configure the field to store the application roles from the MS Token in, in the Firebase JWT token.
     */
    rolesField: string
    /**
     * Additional hook function to perform custom transformation of the Firebase JWT token based on the MS Token.
     */
    customHook?: CustomHook<TokenType>;
}

If you only want to specify the customHook and use the otherwise configured defaults, use beforeSignInWithHook.

• Dependencies

This function depends on Firebase Functions

• Deployment instructions:

During deployment, you need to manually select this function as the blocking function for the beforeSignIn() event. Also note that you need to include the ID Token in the "Additional provider token credentials" section. This allows the hook to access the original users' JWT token provided from MicroSoft, from which the app roles will be read. Failing to enable this will result in the function logging an error upon each invocation.

Note that we noticed during usage of this function, the ID Token setting may be deselected in case the function itself is redeployed. In this case, you will see the errors mentioned in the logging, even thought THE SETTING IS STILL SELECTED IN THE FIREBASE UI. This can be resolved by deselecting the setting, saving, reselecting the setting and saving again.

Contribution guidelines

• Writing tests: TODO: Not yet provided by Firebase yet.
• Code review
• Other guidelines

Who do I talk to?

• Repo owner or admin

The owner of this repo is Jeroen Benckhuijsen (jeroen.benckhuijsen at group9 dot nl)

• Other community or team contact