Manage MFA

1. Get Tenant MFA Configuration

This GET method is used to retrieve the Step Up authentication configuration settings.

Request Example

curl --location '{{url}}/api/mfa/configuration' \
--header 'Accept: application/json'

Response Example

{
  "factorsUsableConfiguration" : [ {
    "factor" : "TOTP",
    "usable" : "ALLOWED"
  }, {
    "factor" : "WEB_AUTHN",
    "usable" : "ALLOWED"
  } ]
}

2. Configure MFA Settings

This POST method is used to configure MFA settings.

Request Example

curl --location '{{url}}/api/mfa/configuration' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ 
--data '{
  "factorsUsableConfiguration": [
    {
      "factor": "TOTP",
      "usable": "REQUIRED"
    }
  ]
}'

Response Example

{
  "factorsUsableConfiguration": [
    {
      "factor": "TOTP",
      "usable": "REQUIRED"
    }
  ]
}

3. Get all Current Authenticated users' MFA Factor Registrations

This GET method is used to retrieve all their MFA factor registrations.

Request Example

curl --location GET '{{url}}/api/mfa/registrations' \
--header 'Accept: application/json'

Response Example

Status: 200 OK

[ {
  "status" : "REGISTERED",
  "factor" : "TOTP"
}, {
  "status" : "REGISTERED",
  "factor" : "WEB_AUTHN",
  "additionalDetails" : {
    "registeredCredentials" : [ {
      "id" : "fYheZTyCK6-ayVKIJWCwng",
      "friendlyName" : "DocTest",
      "type" : "public-key",
      "transports" : [ "hybrid", "internal" ]
    }, {
      "id" : "arNlKJPswdRRBlsXHfwNQIe6vB3dx1l1ZUuldk6GBRk",
      "friendlyName" : "DocWebAuthn",
      "type" : "public-key",
      "transports" : [ "internal" ]
    } ]
  }
} ]

4. Register the Current Authenticated User for the MFA factor

This POST method registers the authenticated user for an MFA factor.

Request Parameter

Request Example for TOTP factor registration start

curl --location POST '{{url}}/api/mfa/register/TOTP' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ' {
    "action": "GENERATE_SECRET"
}'

Response Example of TOTP factor registration start

{
  "status" : "CHALLENGE",
  "factor" : "TOTP",
  "additionalDetails" : {
    "key" : "HBQC7H5JPIWDNU7LQ7ZM6M6N6CD5YRW4",
    "uri" : "<<uri>>"
  }
}

Request example of TOTP registration complete

curl --location POST '{{url}}/api/mfa/register/TOTP' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ' {
   action:"VALIDATE_OTP"
   otp:"061123"
}'

Response of TOTP registration complete

{
  "status" : "REGISTERED",
  "factor" : "TOTP"
}

Request Example for WebAuthn factor registration start

curl --location POST '{{url}}/api/mfa/register/WEB_AUTHN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ' {
    "action": "START_REGISTER"
}'

Response of registration start

{
  "status": "CHALLENGE",
  "factor": "WEB_AUTHN",
  "additionalDetails": {
    "creationOptionsId": "<unique identifier for the registration challenge>",
    "creationOptionsJson": "<registration challenge to create the WebAuthn credential>"
  }
}

Request example of the completion of registration

curl --location POST '{{url}}/api/mfa/register/WEB_AUTHN' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data ' {
  "action": "FINISH_REGISTER",
  "creationOptionsId": "<creation optons id from response to initial register call>",
  "publicKeyCredentialJson": "<web authn public credential as json string to register>",
  "friendlyName": "<Display name to use for registered credential/authenticator>"
}

Response of  completion of registration

{
  "status" : "REGISTERED",
  "factor" : "WEB_AUTHN",
  "additionalDetails" : {
    "registeredCredential" : {
      "id" : "fYheZTyCK6-ayVKIJWCwng",
      "friendlyName" : "DocTest",
      "description" : "",
      "type" : "public-key",
      "transports" : [ "internal", "hybrid" ]
    }
  }
}

5. Get the Current Authenticated User's MFA Factor Registration Details

This GET method is used by the authenticated user to retrieve their MFA factor registration details.

Request Parameter

Request Example of TOTP

curl --location GET '{{url}}/api/mfa/register/TOTP' \
--header 'Accept: application/json'

Response Example for TOTP

{
    "status": "REGISTERED",
    "factor": "TOTP"
}

Request Example of WEB_AUTHN

curl --location GET '{{url}}/api/mfa/register/WEB_AUTHN' \
--header 'Accept: application/json'

Response Example of WEB_AUTHN

{
  "status": "REGISTERED",
  "factor": "WEBAUTHN",
  "additionalDetails": {
    "registeredCredentials": [
      {
        "id": "<webauthn credential id>",
        "friendlyName": "name of the WebAuthn credential registration",
        "description": "descripton of the WebAuthn credential registration",
        "type": "PUBLIC_KEY",
        "transports": ["internal"]
      }
    ]
  }
}

Manage User MFA Registration

1. Get MFA factor Registration Details for a User

This GET endpoint allows administrators with view identity permission to retrieve a user's registered MFA factors.

Note: Only administrators can execute this API.

Request Parameters

The request parameter used in this method is shown in the following table:

Request Example for TOTP

curl --location GET '{{url}}/api/mfa/admin/registrations/TOTP/users/<targetUserId>' \
--header 'Accept: application/json'

Response Example

{
 "status": "REGISTERED",
 "factor": "TOTP",
}

Request Example of WEB_AUTHN

curl --location GET '{{url}}/api/mfa/admin/registrations/WEB_AUTHN/users/<targetUserId>' \
--header 'Accept: application/json'

Response Example of WEB_AUTHN

{
 "status": "REGISTERED",
 "factor": "WEB_AUTHN",
 "additionalDetails": {
  "registeredCredentials": [
   {
    "id": "f_KTpBFXV4rJ3eu3FOKhTdAFLslu7v958v0zEKWJXj4",
    "friendlyName": "Test-WebAuthN",
    "type": "public-key",
    "transports": [
     "internal"
    ]
   },
   {
    "id": "fv3quJO8JJX6klVVHEamwA",
    "friendlyName": "TestName",
    "type": "public-key",
    "transports": [
     "hybrid",
     "internal"
    ]
   }
  ]
 }
}

2. Delete MFA factor registration details

This DELETE method deletes all MFA factor registrations for the given target user.

Note: Only administrators can execute this API.

{{url}}/api/mfa/admin/registrations/users/{targetUserId}

The request parameter used in this method is shown in the following table:

Request Example

curl --location --request DELETE '{{url}}/api/mfa/admin/registrations/users/<targetUserId>'

Status: 204 No Content

3. Delete MFA factor registered credentials

This DELETE method allows administrators with manage identity permission to delete a specific MFA factor credential as specified by the credentialId.  Note that this endpoint is currently useful for the WebAuthn MFA factor, as there can be only one registered TOTP factor.   Please correct the URL in the example. It is missing the credentialId path parameter.

Note: Only administrators can execute this API.

The request parameter used in this method is shown in the following table:

Request Example

curl --location --request DELETE '{{url}}/api/mfa/admin/registrations/{factor}/users/{targetUserId}/credentials/{credentialId}'

Status: 204 No Content

4. Users with Manage Access to Identities can delete/unregister another user’s registration

This DELETE method is used by users who have managed access to delete or unregister another user's registration. 

Request Parameter

Request Example

curl --location --request DELETE '{{url}}/api/mfa/admin/registrations/{factor}/users/{targetUserId}'

Response Example

{
    "status": "REGISTERED",
    "factor": "TOTP"
}

Status: 204 No Content