How to protect elevated functions with multifactor authentication

Some functions of a module are more sensitive than regular operations, e.g. upload macros, deleting data, exporting large amounts of data or changing security-relevant settings. For those "elevated functions", you additionally want to make sure that the user has proven his identity more strongly, e.g. via a step-up multifactor authentication (MFA).

Microsoft Entra ID supports this with the Conditional Access authentication context feature. Bosch has defined a set of authentication contexts to be reused across applications, see the internal Authentication Context documentation. Starting with MACMA version 1.41, MACMA supports this kind of multifactor authentication by using the Conditional Access authentication context from Entra ID.

It is the Nexeed module’s own responsibility to perform the authorization check based on the additional authentication context information. MACMA only surfaces the information needed to perform that check. It does not know which of a module’s functions are "elevated" and does not enforce anything on the module’s behalf.

Prerequisites

This functionality is only available for login via Entra ID identity providers of type microsoft-entra-id-oidc.

Concept

An Entra ID Conditional Access policy is configured (by the identity/tenant administrators) to require an authentication context, identified by an ACR (Authentication Context Class Reference) value, e.g. C1 for "Require MFA" or`C6` for "Require MFA everytime" for the application registration in question.
When protecting an elevated function, the module defines which additional authentication context is necessary for that function, e.g. C1 or C6.

The authentication context C1 implemented at Bosch matches the default Microsoft Entra ID configuration, which has a user sign-in frequency of a rolling window of 90 days. This can lead to a situation where a user has already performed MFA in the last 90 days and is not prompted for MFA again when calling the elevated function. If you want to enforce MFA every time, use C6 instead.

MACMA introspects the token and maps the authentication context information into the claim idp_acrs of the introspection result. The module performs its authorization check for the elevated function based on this claim of the introspection result.
If the claim is missing, or does not contain the needed authentication context (e.g. C1 or C6 ), the module must decline the operation. It does so by responding with 401 Unauthorized and a WWW-Authenticate header of the following form (the claims value is URL-encoded):
```
WWW-Authenticate: Bearer error="insufficient_claims", claims="%7B%22access_token%22%3A%7B%22acrs%22%3A%7B%22essential%22%3Atrue%2C%22value%22%3A%22C6%22%7D%7D%7D"
```
Decoded, the claims value requests the authentication context C6 in this example:
```
{"access_token":{"acrs":{"essential":true,"value":"C6"}}}
```
This response should trigger a reauthentication on the client, requesting the missing authentication context (C6 in the example). Entra ID then evaluates the Conditional Access policy tied to that authentication context and prompts the user to step up (e.g. do MFA).
After the user has reauthenticated using MFA (C6), this information becomes available in the idp_acrs claim of the introspection result from then on. Subsequent calls will pass the module’s check without requiring MFA again, until a relogin happens with a different authentication context.

The idp_acrs claim from the elevated session remains in the tokens and introspection result until the user’s next authentication. After the elevated operation is complete, consider having the user authenticate again without requesting an authentication context. This returns the session to its baseline authentication level.

Setting things up

Module should determine which authentication context (ACR value, e.g. C6 for MFA) fits your elevated function, following the Bosch-wide catalogue in Authentication Context.
Implement authorization check for your elevated function(s), returning a 401 with the matching claims challenge when the claim is missing in the introspection result and optionally with preflight checks in the frontend.
Implement a frontend interceptor that reacts to the insufficient_claims error by requesting a new token with the claims parameter and retrying the request.