Authenticating User Name and Password and Enrolling in Account Recovery
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.
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.Note:
These steps assume multiple factors are enabled for Account Recovery, but MFA enrollment is not configured. See Configure Account Recovery.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:
TheappName
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": "R^iCq16G000000000",
"nextOp": [
"credSubmit"
],
"nextAuthFactors": [
"USERNAME_PASSWORD"
],
"USERNAME_PASSWORD": {
"credentials": [
"username",
"password"
]
},
"requestState": "A4wd5efadWw5PD5LKgzKC+Sfds0W...+7TSfR+22d2D3gGnN4VvGg0Y"
}
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
-
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": "R^iCq18G000000000",
"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": "IjhvZPILfadhlnih+4uTJ83CHf....0SDELTO0mTRqC+nNU"
}
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 wantsauthFactor
: defines which authentication factor the user wants to enroll inphoneNumber
: defines the phone number where the SMS text will be sentcountryCode
: defines the country code of the phone number where the SMS text will be sentrequestState
: 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": "R^iCq19G000000000",
"displayName": "+44XXXXXXXX455",
"SMS": {
"credentials": [
"otpCode"
]
},
"nextOp": [
"credSubmit",
"resendCode",
"enrollment"
],
"requestState": "Y4sMHf7izgxcspF6zr...Y3GXLjjudeRMM2ZNty4E"
}
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.
Step 4: Submit Factor Credentials
op
: tells the server what kind of operation the client wantsrequestState
: 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": "R^iCq1BG000000000",
"accRecEnrollmentRequired": false,
"displayName": "+44XXXXXXXX455",
"nextOp": [
"createToken",
"createSession",
"enrollment"
],
"requestState": "BKbGp43pwZad3zMSePWu7R47Va6myZdNY...vRVFN2FFQKIoDto"
}
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
op
: tells the server what kind of operation the client wants requestState: received in the Step 4 responserequestState
: 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:
{
"authnToken": "eyJ4NXQjUzI1NiI6Iks0R0hvZVdoUmFhOTd6Um0xeDIzM0pwd.....arCzBNfUVvWVA",
"status": "success",
"ecId": "R^iCq1FG000000000"
}