Return Policy details when MFA is required

gistfile1.md

Requirements

https://oktawiki.atlassian.net/wiki/pages/viewpage.action?pageId=123044714

Background

Currently Okta enduser UI shows "Remember Device" whenever the policy that requires MFA is either time based or device based. The requirement is to show a meaningful message instead of a generic "Remember Device" message along with the checkbox.

Please refer to the requirements document mentioned above for details.

Proposal

In order for the Okta API caller to show the meaningful message (or to hide the checkbox altogether), the policy evaluation details need to be populated in the response whenever MFA is required.

The proposal is to add policy evaluation related data (policyEvaluation) to the _embedded object in response when the authentication state is MFA_ENROLL or MFA_REQUIRED:

Request

POST /api/v1/authn
{
  "username" : "test-user",
  "password" : "password"
}

Response

{
  "stateToken" : "007ucIX7PATyn94hsHfOLVaXAmOBkKHWnOOLG43bsb",
  "expiresAt" : "2015-11-03T10:15:57.000Z",
  "status" : "MFA_ENROLL | MFA_REQUIRED",
  "_embedded" : {
    "user" : {
      "id" : "00ub0oNGTSWTBKOLGLNR",
      .... Omitted for brevity
    },
    "policyEvaluation" : {
      "policyType" : "OKTA_SIGN_ON | MFA_ENROLL | APP_SIGN_ON",
      "factorPromptMode" : "SESSION | ALWAYS | DEVICE",
      "factorLifeTime" : "<value>",
      "factorLifeTimeUnit" : "MINUTES | HOURS | DAYS",
      "rememberDeviceByDefault" : "true | false"
    },
    "factors": [
      {
        "factorType": "token",
        .... Omitted for brevity
      },
      {
        "factorType": "sms",
        .... Omitted for brevity
      }
    ]
  },
  "_links": {
    .... Omitted for brevity
  }
}

Implementation Details

The above mentioned API changes are required to implement this feature in "New Sign On Flows" as it uses the Authentication APIs.

Since the existing/legacy login UI doesn't use these APIs, the controller classes would be enhanced to pass similar data to JSP layer via the traditional spring model.

Open Questions

1. Do we need to populate policy evaluation data in the response during MFA enroll?
2. Currently FactorLifeTime implicitly uses minutes as the time unit in the policy API. Whereas in this proposal I wanted to express that with an explicit time unit so that the client doesn't need to compute/convert that value to hours/days.