Authenticating with User Name and Password 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 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 three steps in this use case:

• Step 1: Begin the Authentication Flow

• Step 2: Submit the User's Credentials

• Step 3: Authenticate Using the Preferred Factor

Note:

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

Step 1: Begin the Authentication Flow

Obtain the initial requestState to begin the authentication flow.

Step 1 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.

Step 1 Response Example

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

{
    "requestState": "ZThJpG52InI1.....mNB3tRgFpl",
    "nextOp": [
        "credSubmit"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
            "username",
            "password"
        ]
    },
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "status": "success"
}

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 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 the next 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

Step 2 Request Example

The following example shows the contents of the POST request in JSON format to the /sso/v1/sdk/authenticate endpoint:

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

Step 2 Response Example

The following example shows the contents of the response in JSON format since PUSH Notifications is the preferred factor:

{
    "status": "pending",
    "displayName": "Joe's iPhone",
    "nextAuthFactors": [
        "PUSH"
    ],
    "cause": [
        {
            "code": "AUTH-1108",
            "message": "Push Notification approval is pending."
        }
    ],
    "nextOp": [
        "credSubmit",
        "getBackupFactors"
    ],
    "requestState": "rATagRibc//b.....xrKh7fJtIuWo",
    "trustedDeviceSettings": {
        "trustDurationInDays": 15
    }
}

In the response, the status is pending since the user is required to Allow or Deny the PUSH Notification on their device. The nextOp values in the response 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.

Step 3: Authenticate Using the Preferred Factor

Authenticate using the preferred factor, which in this use case example is PUSH Notifications. The client must include the following attributes in this request:

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

• requestState: received in the Step 2 response

Step 3 Request Example

The following example shows the contents of the POST request in JSON format to complete authentication using the preferred method:

{  
   "op":"credSubmit",
   "requestState":"{{requestState}}"
}

Step 3 Response Example

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

{
    "authnToken": "eyJraWQiOiJT.....kLbxxL97U_0Q",
    "status": "success"
}