MFA Policies

Production - MfaPolicyController - 7 endpoints at /api/v1/mfa-policies

MFA policies define per-tenant rules for when and how MFA is enforced. Policies can require MFA for all users, specific roles, or conditionally based on risk signals like new devices, unfamiliar IPs, or high-risk operations.

6.3.7Policy Types

Type	Description
`REQUIRE`	MFA is mandatory for all targeted users
`CONDITIONAL`	MFA is required only when risk conditions are met
`EXEMPT`	Targeted users are exempt from MFA requirements

Target Scopes

Scope	Description
`ALL_USERS`	Policy applies to all users in the tenant
`SPECIFIC_ROLES`	Policy applies to users with specific roles
`SPECIFIC_GROUPS`	Policy applies to users in specific groups
`SPECIFIC_USERS`	Policy applies to specific named users

6.3.8Policy Management

Create Policy

curl -X POST http://localhost:8081/api/v1/mfa-policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "name": "Admin MFA Required",
    "description": "Require MFA for all admin users",
    "policyType": "REQUIRE",
    "targetScope": "SPECIFIC_ROLES",
    "priority": 10,
    "enrollmentGraceDays": 3
  }'

List Policies

curl -X GET http://localhost:8081/api/v1/mfa-policies \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000"

Evaluate MFA Requirement

Check whether MFA is required for a specific context:

curl -X POST http://localhost:8081/api/v1/mfa-policies/evaluate \
  -H "Authorization: Bearer <admin-token>" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -d 'userId=42&ipAddress=203.0.113.50&riskScore=75&operation=admin_action'

6.3.9Conditional MFA Signals

Conditional policies evaluate these risk signals:

Signal	Request Parameter	Description
New Device	`deviceFingerprint`	Device not seen before
New IP Address	`ipAddress`	IP not in user's history
New Location	Derived from IP	Geographic location anomaly
High Risk Score	`riskScore`	Risk score exceeds threshold
Sensitive Operation	`operation`	Operation type requires elevation

Default Policies

The POST /api/v1/mfa-policies/templates/default endpoint creates two default policies for new tenants:

Admin MFA Required (priority 10): Requires MFA for all admin users with a 3-day enrollment grace period
Conditional MFA (priority 100): Requires MFA on new devices, new IPs, new locations, and high-risk operations (risk threshold: 50) with a 7-day enrollment grace period

Error Codes

Code	HTTP Status	Description
`RESOURCE_NOT_FOUND`	404	Policy not found
`ACCESS_DENIED`	403	Insufficient permissions

Backup Codes MFA Recovery