1. Oracle Identity Cloud Service REST APIREST API for Oracle Identity Cloud Service
  2. Use Cases
  3. Using the Authenticate API to Develop a Custom Sign-in Page
  4. Authenticating User Name and Password and Enrolling in Account Recovery and MFA

Authenticating User Name and Password and Enrolling in Account Recovery and MFA

This use case provides a step-by-step example of using the Oracle Identity Cloud Service Authentication API to authenticate with a user's credentials and then enroll for Account Recovery and Multi-Factor Authentication (MFA).

Note:

Use this Authenticate API only if you're building your own end-to-end login experience by developing a custom sign-in application to be used by Oracle Identity Cloud Servcice.

Note:

This Authenticate API can't be used to integrate your applications with Oracle Identity Cloud Service for single sign-on purposes.

Note:

See the Oracle Identity Cloud Service Authentication API Postman collection for extensive authentication use case examples. Download the collection and the global variables file from the idcs-authn-api-rest-clients folder within GitHub and then import them into Postman.
There are seven steps in this use case. Each step contains request and response examples:

Note:

These steps assume that Account Recovery and MFA is enabled and a sign-on policy is created for MFA. See Configure Account Recoveryand Configure Multi-Factor Authentication Settings.

Step 1: Begin the Authentication flow

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request in cURL format :

curl
-X GET
-H "Content-Type: application/json"
-H "Authorization: Bearer {{access_token_value}}"
https://tenant-base-url/sso/v1/sdk/authenticate?appName={{app_name}}

Note:

The appName is optional. The appName is the name of the App that the client wants to access. If an appName is provided, sign-on policies specific to the App are processed, and the client is challenged for the required factors based on that policy.

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1M0000000000",
    "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "password"
        ]
    },
    "requestState": "BgwRu6ASXCIDPiDbakhYsAgnLK77...W/Im6jfEF/YH0bA5j5E"
}

In the response, the nextOp value indicates what can be sent as the op value in the next request. In this use case example, credSubmit should be sent in the next step. The requestState contains contextual data needed to process the request.

Step 2: Submit the User's Credentials

Submit the user's credentials as the first factor, which are the user name and password. For this step, the client must include the following attributes:

  • credentials: user name and password

  • requestState: received in the Step 1 response

  • op: tells the server what kind of operation the client wants

Request Example

The following example shows the contents of the POST request in JSON format:

{
  "op": "credSubmit",
  
  "credentials": {
    "username": "{{username}}",
    "password": "{{password}}"
  },
  "requestState": "{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1M0000000000",
    "accRecEnrollmentRequired": true,
    "nextAuthFactors": [
        "SMS",
        "SECURITY_QUESTIONS",
        "EMAIL"
    ],
    "SMS": {
        "credentials": [
            "phoneNumber",
            "countryCode"
        ]
    },
    "EMAIL": {
        "userAllowedToSetRecoveryEmail": "true",
        "primaryEmailVerified": "true",
        "primaryEmail": "clarence.saladna@example.com",
        "credentials": [
            "recoveryEmail"
        ]
    },
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "wtyRQpBzFZnuGMQvLNRotKfRIlgliWNc8sxipU....41zjKQcvdzk2bmvWs"
}

In this use case example, the user must enroll in account recovery (indicated by a value of true for the accRecEnrollmentRequired:true attribute). The nextAuthFactors indicates the factors in which the user can enroll for Account Recovery.

In this use case example, enrollment is sent in the next step to initiate account recovery enrollment for the user.

Step 3: Initiate Account Recovery Enrollment

This step initiates SMS enrollment. The client must include the following attributes:

  • op: tells the server what kind of operation the client wants
  • authFactor: defines which authentication factor the user wants to enroll in
  • phoneNumber: defines the phone number where the SMS text will be sent
  • countryCode: defines the country code of the phone number where the SMS text will be sent
  • requestState: received in the Step 2 response

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"enrollment",
   "authFactor":"SMS",
   "credentials":{  
      "phoneNumber":"1122334455",
      "countryCode":"+44"
   },
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the request in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1N0000000000",
    "displayName": "+44XXXXXXXX213",
    "SMS": {
        "credentials": [
            "otpCode"
        ]
    },
    "nextOp": [
        "credSubmit",
        "resendCode",
        "enrollment"
    ],
    "requestState": "FnwYT23S0qo+RHXN3Sx80D3....8CsoT3QezVbynT3LfZY3+sXN5E8OtEdM"
}

In the response, the nextOp values indicate what can be sent as the op value in the next request. In this use case example, credSubmit is sent in the next step. The otpCode is sent via SMS to the user's device. Credentials tell the user what input he needs to pass in the next request.

Step 4: Submit Factor Credentials

This step submits the factor credentials along with the requestState that were received in the Step 3 response. Note that the request payload doesn't contain the authFactor attribute because the requestState contains it. The client must include the following attributes:
  • op: tells the server what kind of operation the client wants
  • requestState: received in the Step 3 response

Request Example

The following example shows the contents of the POST request in JSON format to submit the factor credentials:

{  
   "op":"credSubmit",
   "credentials":{  
      "otpCode":"974311"
   },
   "requestState":"{{requestState}}"
}

Response Example

The success status appears in the response when the optCode verification is successful. The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1P0000000000",
    "accRecEnrollmentRequired": false,
    "displayName": "+44XXXXXXXX455",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "Z+ysro8gFyPPT5bI9C/RykLfRrq5rBXCOO68/wZcgkllw765qd7SNvhRN6ZHp0Xiw2FIN9nOeio7SpsEAlYxO2xQ/1fF5lAjo0jwJEzIgSRt8xj/vAQeSLhX+PRm2a1rRYHwSa9uFcUBkNA.....KP7CPh2/yrdZF4WpbI"
}

In the response, the accRecEnrollmentRequired value is set to false as account enrollment is successful. The nextOp values indicate what can be sent as the op value in the next request. The nextOp value "enrollment" allows the user to switch to another factor to enroll in account recovery. In this use case example, createToken is sent in the next step.

Step 5: Create the Authentication Token

This step indicates that the client is done with account recovery enrollment and needs a session created. The server validates that no other factor evaluation (depending on what is defined for the policy) is needed and responds with the token or responds accordingly. The client must include the following attributes:
  • op: tells the server what kind of operation the client wants requestState received in the Step 4 response
  • requestState: received in the Step 4 response

Request Example

The following example shows the contents of the POST request in JSON format:

{  
   "op":"createToken",
   "requestState":"{{requestState}}"
}

Response Example

The following example shows the contents of the response in JSON format:

{
    "status": "success",
    "ecId": "HI^kd1Q0000000000",
    "nextAuthFactors": [
        "TOTP",
        "SECURITY_QUESTIONS",
        "SMS",
        "EMAIL",
        "PUSH"
    ],
    "EnrolledAccountRecoveryFactorsDetails": {
        "SMS": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "deviceId": "3ed9b2ed366441fb91c9277abd694348",
                    "displayName": "+44XXXXXXXX455"
                }
            ]
        },
        "EMAIL": {
            "credentials": [
                "accountRecoveryFactor"
            ],
            "enrolledDevices": [
                {
                    "displayName": "clarence.saladna@example.com"
                }
            ]
        },
        "enrolledAccRecFactorsList": [
            "SMS",
            "EMAIL"
        ]
    },
    "nextOp": [
        "enrollment"
    ],
    "mfaSettings": {
        "enrollmentRequired": true
    },
    "requestState": "YN9sdSJiNtD5lOEKt33paDa9Ezs5ZZhZhF3C1BsDCuMdVVNqt1RmA3d3SppmnVOIP3uYrErQNYADHCIQLrXgmxpxReUzdcFDArlejaaph3qWctYvLQiIsBwixsHgTOfQiDkzyjN8JZiX/gqbkTEmHi1S3EtjYXuw7qCcwi...G8ZnyfTrcZtKEpaDDj7CtWF/+LIwAEQLvFaXvkOK4P4"
}

In the response, as MFA is required, enrollmentRequired has a value of true under mfaSettings. As a result, no token is issued. The EnrolledAccountRecoveryFactorsDetails shows the account recovery factors the user has enrolled in. The nextOp values indicate what can be sent as the op value in the next request. In this example, the nextOp value "enrollment" indicates the user is to enroll in MFA.

Step 6: Set SMS as Default MFA Factor in Overlap

This step indicates that the client should enroll in MFA.

The client must include the following attributes:

  • authFactor: indicates which factor to enroll in for MFA
  • accountRecoveryFactor: when set to true, indicates that the user want to reuse already enrolled account recovery factor for MFA.

Request Example

The following example shows the contents of the POST request in JSON format:

{ 
 "op":"enrollment",
 "authFactor": "SMS",
 "credentials":{ 
  "accountRecoveryFactor" : true 
 },
 "requestState": "{{requestState}}"
}

Response Example


{
    "status": "success",
    "ecId": "HI^kd1R0000000000",
    "nextOp": [
        "createToken",
        "createSession",
        "enrollment"
    ],
    "requestState": "7J6m/Z1PxXQZp4pigzt1F0CXp0kotX.....WXP2knQa16MNj5E8"
}

In the response the nextOp values indicate what can be sent as the op value in the next request. The nextOp value "enrollment" allows the user to enroll additional factor for MFA. In this use case example, createToken is sent in the next step.

Step 7: Create the Authentication Token

This step indicates that the client is done with all the authnFactors and needs a session created. Depending on what is defined for the policy, the server validates that no other factor evaluation is needed and responds with the token or denies access. The client must include the following attributes:
  • op: tells the server what kind of operation the client wants
  • requestState: received in the Step 6 response

Request Example

The following example shows the contents of the POST request in JSON format:

{ "op":"createToken", "requestState":"{{requestState}}" }

Response Example

The following example shows the contents of the response in JSON format: 
{
    "authnToken": "eyJ4NXQjUzI1NiI6Iks0R0hvZVdo...ZMhfYXMvbFIvs-WQFMBw",
    "status": "success",
    "ecId": "HI^kd1W0000000000"
}