REST API for Oracle Identity Cloud Service

Authenticating User Name and Password with TOU Consent

This use case provides a step-by-step example of using the Oracle Identity Cloud Service Authenticate API to authenticate with a user's credentials with TOU consent. When the user accepts the consent, then the user is re-directed to that application page.

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. Each step contains request and response examples:

Step 1: Begin the Authentication flow

Obtain the initial requestState to begin the authentication flow.

Request Example

The following example shows the request:

{{HOST}}/sso/v1/sdk/authenticate?appName={{appName}}

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": "EYmpU0u1000000000",
    "nextOp": [
        "credSubmit"
    ],
    "nextAuthFactors": [
        "USERNAME_PASSWORD"
    ],
    "USERNAME_PASSWORD": {
        "credentials": [
           "username",
           "password"
        ]
    },
 "requestState": "urB5fxRNb197M+iBgjMxv93e9r/P...~innaS6JOpHyoTP5EcOtfVSjFoASieodrxcjZwxUXhsY"

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(No MFA)

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

If the username and passwords are valid, the server responds with the TOU statement in the locale specified in the user's profile. The server also prompts the user to provide their consent credential in the next request. If the TOU statement is not present in the user's locale fr, then 401 response with the error message AUTH-3036 : Terms of Use Statement for locale fr is not added is displayed.

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}}"
}
}

Response Example

The following example shows the contents of the response in JSON format when the user's locale is added:

{
  "nextOp": [
   "acceptTOU"
  ],
  "TOU": {
    "statement": "This is a placeholder text. Customers must provide the actual Terms of Use.",
    "credentials": [
    "consent"
    ],
    "locale": "en"
  },
 "requestState": "q/tRS4BFAdaimSBhq"
}
}

Error Response Example

The following example shows the contents of the response in JSON format when the TOU for user's locale is not added:

{
    "status": "failed",
    "ecId": "Q0ApB1Y1000000000",
    "cause": [
        {
            "message": "Terms of Use Statement for locale fr is not added.",
            "code": "AUTH-3036"
        }
    ]
}
}

Step 3: Provide the TOU Consent

In this scenario, the user either accepts or rejects the Terms of Use for the application. If user agrees to Terms of Use, then the user is redirected to the application page.

If user rejects the Terms of Use, then 401 response with error message, AUTH-3035 : You must accept the Terms of Use to access this application, is displayed.

Request Example

The following example shows the contents of the request in JSON format when the user agrees to TOU.

{
 "op": "acceptTOU",
 "credentials": {
   "consent": true
 },
 "requestState": "{{requestState}}"
}

Request Example

The following example shows the contents of the request in JSON format when the user rejects the TOU.

{
 "op": "acceptTOU",
 "credentials": {
   "consent": false
 },
 "requestState": "{{requestState}}"
}

Response Example

The following example shows the content of the response in JSON format when the user agrees to TOU statement.

{
    "authnToken": "eyJ4NXQjUzI1NiI6Iks0R0hvZVdoUm...YUAvuEOrERXrQRnjybdOkA2Q",
    "status": "success",
    "ecId": "Q0ApB1Y1000000000"
}

Error Response Example

The following shows the contents of the response in JSON format when the TOU is rejected by the user.


{
    "status": "failed",
    "ecId": "Q0ApB1Y1000000000",
    "cause": [
        {
            "message": "You must accept the Terms of Use to access this application.",
            "code": "AUTH-3035"
        }
    ]
}