Authenticating with User Name and Password and Enrolling in 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 in Multi-Factor Authentication (MFA).
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 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:
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.
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
-
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:
{
"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:
{
"status": "success",
"nextAuthFactors": [
"TOTP",
"SMS",
"EMAIL",
"SECURITY_QUESTIONS"
],
"TOTP": {
"credentials": [
"offlineTotp"
]
},
"SMS": {
"credentials": [
"phoneNumber"
]
},
"nextOp": [
"createToken",
"createSession",
"enrollment"
],
"mfaSettings": {
"enrollmentRequired": false
},
"requestState": "m3oIaGVOlHwA...../Fi+1RpmKmd4"
}
In this use case example, since MFA is set as optional in the Sign-on Policy (indicated by a value of false
for the enrollmentRequired
attribute), the user is given a choice to either enroll or skip enrollment. If MFA is required, the only nextOp
value would be enrollment.
In this use case example, enrollment
is sent in the next step to initiate MFA factor enrollment for the user. Note that BYPASSCODE is missing as a nextAuthFactors
value since the user can't enroll using a Bypass Code. The Bypass Code should be generated by the user using My Profile or by requesting that an administrator generate one for them.
Step 3: Initiate Second Factor Authentication Enrollment
-
op:
tells the server what kind of operation the client wants -
authFactor:
defines which authentication factor the user wants to enroll in -
requestState:
received in the Step 2 response
Step 3 Request Example
The following example shows the contents of the POST request in JSON format:
{
"op":"enrollment",
"authFactor":"TOTP",
"requestState":"{{requestState}}"
}
Step 3 Response Example
The following example shows the contents of the response in JSON format:
{
"status": "success",
"displayName": "Joe's Phone",
"TOTP": {
"credentials": [
"otpCode"
],
"qrCode": {
"content": "oraclemobileauthenticator://totp/user?issuer=example1&Period=30&algorithm=SHA1&digits=6&RSA=SHA256withRSA&Deviceid=22f38324e67f4e2bb8e9e24583924a31&RequestId=9b428c1a-abb3-40ee-bd24-5064a87b638e&LoginURL=https%3A%2F%2Fexampletenant.com%3A8943%2Fsso%2Fv1%2F&OTP=eyJraWQiOiJTSUdOSU5HX0tFWSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJkZXZpY2VfaWQiOiIyMmYzODMyNGU2N2Y0ZTJiYjhlOWUyNDU4MzkyNGEzMSIsImlzcyI6IkF1dGhTcnYiLCJleHAiOjE1MjcxODEwODEsImlhdCI6MTUyNzE4MDc4MSwidGVuYW50IjoidGVuYW50MSJ9.Of0Hv5H3aRpDqdsiFLO0YkK2gbzq78k3jaJFwoWwR5LKOEH-9qTt1zjSiXujPD1T__8fEZDi8iKDyxXtL5zjAlEKd5wI026JjekG58ROPjW8gADWcMrTGQ4Lgw4Q0UPjk8Fm8AloQ1vS6xpDre6S-Vv620z28EKWZK_yGhUVSfAJVzSUxaypLtQhOQJBCNAzCElUgqyav7Vpi2z5eVQBQRtXv-Z_sTgrFXaVmVU3uSNVcg6zVX2x0fMQFgeO5lyC3U2Yy9JgA7iMfAMpuNvBzW0GjyByPAYRVnHSLPuHL1qiNx9ygpoVEcFLQJcOPuDLW2bW9ZwbUcVdS0F4L_2NfA&ServiceType=TOTP&KeyPairLength=2048&SSE=Base32",
"imageType": "image/png",
"imageData": "iVBORw0KG.......5ErkJggg=="
}
},
"nextOp": [
"credSubmit",
"createToken",
"createSession",
"enrollment"
],
"mfaSettings": {
"enrollmentRequired": false
},
"requestState": "8A317/A1JiQe.....ce5/paoVOWw"
}
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.
Note:
The value forcontent
always begins with
oraclemobileauthenticator//.
Step 4: Submit Factor Credentials
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
Step 4 Request Example
The following example shows the contents of the POST request in JSON format to submit the factor credentials:
{
"op":"credSubmit",
"requestState":"{{requestState}}"
}
Step 4 Response Example
The success
status appears in the response when the OMA app to server back-channel communication is completed and the optCode
verification is successful. The following example shows the contents of the response in JSON format:
{
"status": "success",
"displayName": "Joe's iPhone",
"nextOp": [
"createToken",
"createSession",
"enrollment"
],
"requestState": "eyZa+10USFR7.....6I2vnfK82hnQ"
}
In the response, the nextOp
values indicate what can be sent as the op
value in the next request. In this use case example, createToken
is sent in the next step.
Step 4 Pending Response Example
The pending
status appears when the OMA app to server back-channel communication isn't completed. The client keeps polling every 10 seconds and continues to poll for two minutes. After two minutes, the server sends the failed status if the otpCode
verification isn't successful.
{
"status": "pending",
"cause": [
{
"code": "AUTH-1109",
"message": "Enrollment in the One-Time Passcode authentication method is pending verification."
}
],
"nextOp": [
"credSubmit",
"createToken",
"createSession",
"enrollment"
],
"mfaSettings": {
"enrollmentRequired": false
},
"requestState": "1bYZJeyi6bcp..........74RXYKmbdiZfVW8y7tNc"
}
Step 5: Create the Authentication Token
authnFactors
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 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 4 response
Step 5 Request Example
{
"op":"createToken",
"requestState":"{{requestState}}"
}
Step 5 Response Example
The following example shows the contents of the response in JSON format:
{
"authnToken": "eyJraWQiOiJT.....Wyhr1erJFLbA",
"status": "success"
}