scimgateway 6.2.3 → 6.2.4

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Change Log
 
+### v6.2.4
+- **[Improved]** `plugin-entra-id` now support reset users MFA capabilites and user will be forced to re-register MFA.
+
 ### v6.2.3
 - **[Improved]** `plugin-entra-id` now includes information on whether a user has registered for MFA (has an MFA-capable method registered).
 

package/README.md

@@ -81,7 +81,7 @@ SCIM Gateway is a user provisioning bridge built with [Bun](https://bun.sh/) and
 
 ## What's New
 
-- **`plugin-entra-id`** now supports Entra ID roles and access packages, in addition to reading MFA capabilities and licenses.
+- **`plugin-entra-id`** now supports Entra ID roles, access packages and MFA, in addition to reading licenses.
 - **`plugin-generic`** replaces `plugin-scim` — a flexible template using `endpointMapper` with the new `valueMap` option for allowlisting and name mapping e.g., groups
 - **`GET /Roles` and `GET /Entitlements`** endpoint support, with user management via SCIM `roles` and `entitlements` attributes; `plugin-entra-id` uses `entitlements` for Entra ID licenses (read-only) and `roles` for Permanent and Eligible PIM roles (full management)
 - **AI Agent ready** — `x-agent-schema` configuration in `endpointMapper` enables custom schema generation with MCP tool instructions for autonomous provisioning agents
@@ -1054,7 +1054,7 @@ The `baseEntity` parameter enables multi-tenant setups — create multiple endpo
    - `Organization.ReadWrite.All`
    - Additional for signInActivity, MFA, roles, and access packages:
      - `AuditLog.Read.All` *(sign-in activity; only if using `map.user.signInActivity`; requires Entra ID Premium)*
-     - `UserAuthenticationMethod.Read.All` *(MFA information; only if using `map.user.mfa`)*
+     - `UserAuthenticationMethod.ReadWrite.All` *(MFA information and reset; only if using `map.user.mfa`)*
      - `RoleEligibilitySchedule.ReadWrite.Directory` *(PIM Eligible roles; only if using `map.user.roles`)*
      - `RoleManagement.ReadWrite.Directory` *(PIM Permanent roles; only if using `map.user.roles`)*
      - `EntitlementManagement.ReadWrite.All` *(IGA Access Packages; only if using `map.user.entitlements`)*
@@ -1063,7 +1063,7 @@ The `baseEntity` parameter enables multi-tenant setups — create multiple endpo
 
 > For full access to admin users, assign the `Global Administrator` role. The `User Administrator` role has limitations on users with admin roles.
 
-> Note, if PIM and Access Package `management` is not required, `ReadWrite` can be replaced with `Read`. **Remove any mapping configuration whose conditions are not met** — The minimum `Read` permissions are validated at startup.
+> Note, if MFA, PIM, and Access Package `management` is not required, `ReadWrite` can be replaced with `Read`. **Remove any mapping configuration whose conditions are not met** — The minimum `Read` permissions are validated at startup.
 
 ### Plugin Configuration
 

package/config/plugin-entra-id.json

@@ -210,10 +210,16 @@
               "mutability": "readOnly",
               "description": "true/false - legacy per-user MFA is enabled ('perUserMfaState' is 'enabled' or 'enforced'); such users bypass/aren´t fully controlled by standard Conditional Access only design and therefore require special attention.",
               "type": "boolean"
+            },
+            {
+              "name": "reset",
+              "mutability": "writeOnly",
+              "description": "Set to 'true' will reset users MFA capabilites and user will be forced to re-register MFA.",
+              "type": "boolean"
             }
           ],
         "x-agent-schema": {
-            "description": "Read-only attribute object representing the user's MFA capabilities. Note: 'mfa.isMfaCapable' does not mean MFA is enabled for the user. Conditional Access policies or using Security Defaults must be verified separately.",
+            "description": "Read-only attribute object (except for 'mfa.reset') presenting the user's MFA capabilities. Note: 'mfa.isMfaCapable' does not mean MFA is enabled for the user. Conditional Access policies or using Security Defaults must be verified separately.",
             "readOnly": true
           }
         },

package/lib/helper-rest.ts

@@ -794,13 +794,13 @@ export class HelperRest {
           const ret = await this.doRequestHandler(baseEntity, method, path, body, ctx, opt, retryCount) // retry
           return ret // problem fixed
         } else {
-          if (statusCode === 404 || ctx.skipLogAsError) {
+          if (statusCode === 404 || ctx?.skipLogAsError) {
             this.scimgateway.logDebug(baseEntity, `doRequest ${method} ${path} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
           } else this.scimgateway.logError(baseEntity, `doRequest ${method} ${path} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
           throw err
         }
       } else {
-        if (statusCode === 404 || ctx.skipLogAsError) { // 404 not logged as error e.g. getUser-manager
+        if (statusCode === 404 || ctx?.skipLogAsError) { // 404 not logged as error e.g. getUser-manager
           this.scimgateway.logDebug(baseEntity, `doRequest ${method} ${options.url} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
         } else this.scimgateway.logError(baseEntity, `doRequest ${method} ${options.url} Body = ${JSON.stringify(body)} Error Response = ${err.message}`)
         if (statusCode === 401) delete this._serviceClient[baseEntity]

package/lib/plugin-entra-id.ts

@@ -637,6 +637,18 @@ scimgateway.modifyUser = async (baseEntity, id, attrObj, ctx) => {
     return undefined
   }
 
+  // MFA Reset
+  if (Object.hasOwn(parsedAttrObj, 'mfa')) {
+    if (parsedAttrObj.mfa.reset === true) {
+      if (!permission[baseEntity]?.mfa || !permission[baseEntity]?.eligible) throw new Error(`${action} error: MFA reset is not supported by the endpoint - missing permissions.`)
+      const currentRoles = await getUserRoles(baseEntity, id, [], true, ctx)
+      const isPrivileged = currentRoles.some(r => isPrivilegedRole(r.value))
+      if (isPrivileged) throw new Error(`${action} error: MFA reset is not allowed for users with high-privilege roles for security reasons.`)
+      await resetUserMfa(baseEntity, id, ctx)
+    }
+    delete parsedAttrObj.mfa
+  }
+
   // Roles
   if (Object.hasOwn(parsedAttrObj, 'roles') && Array.isArray(parsedAttrObj.roles)) {
     const r: Record<string, any>[] = []
@@ -655,7 +667,7 @@ scimgateway.modifyUser = async (baseEntity, id, attrObj, ctx) => {
       const res: Record<string, any> = { value: el.value, type: el.type }
       if (el.display) res.display = el.display
       if (el.operation === 'delete') {
-        if (el.value === '62e90394-69f5-4237-9190-012177145e10') throw new Error(`${action} error: Removal of the 'Global Administrator' role is not allowed for security reasons.`)
+        if (isPrivilegedRole(el.value)) throw new Error(`${action} error: Removal of high-privilege roles is not allowed for security reasons.`)
         res.operation = el.operation
       }
       r.push(res)
@@ -1719,6 +1731,15 @@ const getUserAccessPackages = async (baseEntity: string, userId: string, include
   return result
 }
 
+const isPrivilegedRole = (roleId: string): boolean => {
+  return [
+    '62e90394-69f5-4237-9190-012177145e10', // Global Administrator
+    'e8611ab8-c189-46e8-94e1-60213ab1f814', // Privileged Role Administrator
+    '7be44c8a-adaf-4e2a-84d6-ab2649e08a13', // Privileged Authentication Administrator
+    'c4e39bd9-1100-46d3-8c65-fb160da0071f', // Authentication Administrator
+  ].includes(roleId)
+}
+
 const isMethodMfaCapable = (odataType: string): boolean => {
   return [
     '#microsoft.graph.microsoftAuthenticatorAuthenticationMethod',
@@ -1729,8 +1750,24 @@ const isMethodMfaCapable = (odataType: string): boolean => {
   ].includes(odataType)
 }
 
+const getAuthMethodCollectionFromODataType = (odataType: string): string => {
+  const map: Record<string, string> = {
+    '#microsoft.graph.microsoftAuthenticatorAuthenticationMethod': 'microsoftAuthenticatorMethods',
+    '#microsoft.graph.passwordlessMicrosoftAuthenticatorAuthenticationMethod': 'microsoftAuthenticatorMethods',
+    '#microsoft.graph.phoneAuthenticationMethod': 'phoneMethods',
+    '#microsoft.graph.softwareOathAuthenticationMethod': 'softwareOathMethods',
+    '#microsoft.graph.fido2AuthenticationMethod': 'fido2Methods',
+    '#microsoft.graph.emailAuthenticationMethod': 'emailMethods',
+    '#microsoft.graph.temporaryAccessPassAuthenticationMethod': 'temporaryAccessPassMethods',
+    '#microsoft.graph.windowsHelloForBusinessAuthenticationMethod': 'windowsHelloForBusinessMethods',
+    '#microsoft.graph.passwordAuthenticationMethod': 'passwordMethods',
+  }
+  const collection = map[odataType]
+  return collection
+}
+
 const getUserisMfaCapable = async (baseEntity: string, userId: string, ctx?: undefined | Record<string, any>): Promise<boolean> => {
-  const action = 'getUserAccessPackages'
+  const action = 'getUserisMfaCapable'
   const method = 'GET'
   const body = null
   const path = `/users/${userId}/authentication/methods`
@@ -1744,6 +1781,35 @@ const getUserisMfaCapable = async (baseEntity: string, userId: string, ctx?: und
   return methodTypes.some(isMethodMfaCapable)
 }
 
+const resetUserMfa = async (baseEntity: string, userId: string, ctx?: undefined | Record<string, any>): Promise<boolean> => {
+  const action = 'resetUserMfa'
+  const method = 'GET'
+  const body = null
+  const path = `/users/${userId}/authentication/methods`
+  const r = await helper.doRequest(baseEntity, method, path, body, ctx?.headers ? { headers: ctx?.headers } : undefined)
+  if (!r.body?.value) {
+    if (r.body?.id) r.body.value = [r.body]
+    else throw new Error(`${action} error: invalid response: ${JSON.stringify(r)}`)
+  }
+  const methods = r.body.value.map((m: any) => { return { 'id': m.id, '@odata.type': m['@odata.type'] } })
+  if (methods.length < 1) return false
+  const fnArr: { fn: () => Promise<any>, index?: number, objArr?: any, key?: string }[] = []
+  for (const m of methods) {
+    if (!isMethodMfaCapable(m['@odata.type'])) continue
+    const methodName = getAuthMethodCollectionFromODataType(m['@odata.type'])
+    if (!methodName) continue
+    const path = `/users/${userId}/authentication/${methodName}/${m.id}`
+    const fn = () => helper.doRequest(baseEntity, 'DELETE', path, null, ctx?.headers ? { headers: ctx?.headers } : undefined)
+    fnArr.push({ fn })
+  }
+  if (fnArr.length === 0) return false
+  // include revoke sessions
+  const fn = () => helper.doRequest(baseEntity, 'POST', `/users/${userId}/invalidateAllRefreshTokens`, null, ctx?.headers ? { headers: ctx?.headers } : undefined)
+  fnArr.push({ fn })
+  await fnCunckExecute(fnArr)
+  return true
+}
+
 /**
 * getUsersByRole returns an array of user IDs having a specific role assigned
 * @param baseEntity 

package/lib/scimgateway.ts

@@ -2261,6 +2261,7 @@ export class ScimGateway {
           if (res?.Resources && Array.isArray(res.Resources) && res.Resources.length === 1) {
             // we might have endpoint like Entra ID that hasn’t caught up yet due to internal sync
             // ensure returned object reflects changes by doing a merge with patch payload (convertedScim) 
+            if (finalScimdata?.mfa) delete finalScimdata.mfa // writeOnly mfa.reset
             res.Resources[0] = this.patchObj(res.Resources[0], finalScimdata) // merge
             if (res.Resources[0].password) delete res.Resources[0].password
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scimgateway",
-  "version": "6.2.3",
+  "version": "6.2.4",
   "type": "module",
   "description": "Using SCIM protocol as a gateway for user provisioning to other endpoints",
   "author": "Jarle Elshaug <jarle.elshaug@gmail.com> (https://elshaug.xyz)",