Using Self Service to Enroll in MFA with Duo Security
This use case provides a step-by-step example of using the REST API for Oracle Identity Cloud Service for self-service enrollment in Multi-Factor Authentication (MFA) using Duo Security.
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-rest-clients folder within GitHub and then import them into Postman.As a prerequisite step, you must obtain a ME token before following these steps. See Generating Access Token Using Authentication API for information on obtaining a ME token.
Note:
These steps assume that relevant factors of MFA are enabled using Configure Multi-Factor Authentication Settings.Step1: Enroll a User with Duo Factor
/admin/v1/MyAuthenticationFactorEnroller
endpoint. The client must include the following attribute:
value
: defines the user id. You can make a GET call to{{HOST}}/admin/v1/Me
to get the "id" value.
Request Example
The following example shows the contents of the POST request body in JSON format :
{
"authnFactors":["THIRDPARTY"],
"thirdPartyFactor": {
"thirdPartyVendorName" : "DUO_SECURITY",
"thirdPartyFactorType" : "None"
},
"user": {
"value" : "012832e2e63d4bfda5bc512f2b52ccbe"
},
"schemas": [
"urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
]
}
Response Example
The following example shows the contents of the response body in JSON format:
{
"authnFactors": [
"THIRDPARTY"
],
"thirdPartyFactor": {
"thirdPartyFactorId": "1c3a069c240b4a9d9e6e90b9a2be8bed",
"thirdPartyFactorType": "None",
"thirdPartyVendorName": "DUO_SECURITY"
},
"user": {
"value": "6852e4e2bc864b3b912d7bd48f9f4879",
"$ref": "https://tenant-base-url/admin/v1/Users/6852e4e2bc864b3b912d7bd48f9f4879"
},
"schemas": [
"urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorEnroller"
],
"meta": {
"resourceType": "MyAuthenticationFactorEnroller",
"location": "https://tenant-base-url/admin/v1/MyAuthenticationFactorEnroller"
},
"displayName": "test's Phone",
"requestId": "fe520538-0da6-45a3-b23f-1256091e3f0c",
"deviceId": "ca0ba497327c45d2a4a408301c78682b"
}
In the response, the deviceId
and the requestId
should be passed in the next step.
Step 2: Initiate Duo Authentication for the User
This step initiates the authentication on the third party side by submitting a POST request to the /admin/v1/MyAuthenticationFactorInitiator
endpoint. The client must include the following attributes:
requestId:
received in the Step 1 response
deviceId:
received in the Step 1 response
userName:
user name of the user
Request Example
The following example shows the contents of the POST request body in JSON format:
{
"requestId": "1e513691-9a41-4418-a0f0-f96e6f4c5735",
"deviceId": "14a2a6f2f41b4c10acc9a6d4b54ffe4a",
"authFactor": "THIRDPARTY",
"thirdPartyFactor": {
"thirdPartyFactorId": "7ed55e203ac7435eb6b4847dcfca28e0",
"thirdPartyFactorType": "None",
"thirdPartyVendorName": "DUO_SECURITY"
},
"userName": "testuser1",
"schemas": [
"urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
]
}
Response Example
The following example shows the contents of the response in JSON format:
{
"requestId": "fe520538-0da6-45a3-b23f-1256091e3f0c",
"deviceId": "ca0ba497327c45d2a4a408301c78682b",
"authFactor": "THIRDPARTY",
"thirdPartyFactor": {
"thirdPartyFactorId": "1c3a069c240b4a9d9e6e90b9a2be8bed",
"thirdPartyFactorType": "None",
"thirdPartyVendorName": "DUO_SECURITY"
},
"userName": "testuser1",
"schemas": [
"urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorInitiator"
],
"meta": {
"resourceType": "MyAuthenticationFactorInitiator",
"location": "https://tenant-base-url/admin/v1/MyAuthenticationFactorInitiator"
},
"additionalAttributes": [
{
"name": "duoHost",
"value": "api-0095dc4a.duosecurity.com"
},
{
"name": "duoChallenge",
"value": "TX
|Njg1MmU0ZTJiYzg2NGIzYjkxMmQ3YmQ0OGY5ZjQ4Nzl8RElFWldUV0VMVUJYSEQ2RExKM1V8MTU0MDMyMDkz==
|8a0b6f0472b1c03357e9d6b3348d0a341c96e6a0:APP
|Njg1MmU0ZTJiYzg2NGIzYjkxMmQ3YmQ0OGY5ZjQ 4Nzl8RElFWldUV0VMVUJYSEQ2RExKM1V8MTU0MDMyNDIzNA==
|5d45c215e6e5af7d866df480087d825aa1cf4279"
}
]
}
In the response deviceId
and requestId
should be passed in the next step.
Step 3: Validate Duo Factor for Enrollment Scenario
This step calls the third-party factor API with collected credentials to validate the enrollment of a user in a POST request to the /admin/v1/MyAuthenticationFactorValidator
endpoint.
The client must include the following attributes:
-
requestId:
received in the Step 2 response deviceId:
received in the Step 2 response
Request Example
The following example shows the contents of the POST request in JSON format:
{
"requestId": "1e513691-9a41-4418-a0f0-f96e6f4c5735",
"deviceId": "14a2a6f2f41b4c10acc9a6d4b54ffe4a",
"authFactor": "THIRDPARTY",
"thirdPartyFactor": {
"thirdPartyFactorId": "7ed55e203ac7435eb6b4847dcfca28e0",
"thirdPartyFactorType": "None",
"thirdPartyVendorName": "DUO_SECURITY"
},
"scenario": "ENROLLMENT",
"username": "testuser1",
"schemas": [
"urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
],
"additionalAttributes": [
{
"name": "duoResponse",
"value": "AUTH|YWJoaXNoZWsuanVsa2FAb3JhY2xlLmNvbXxESUVaV1RXRUxVQlhIRDZETEozVXwxNTM5ODMwNDc2|9439adbea1b90a90c9169f366cc028aabde8ac51:APP|YWJoaXNoZWsuanVsa2FAb3JhY2xlLmNvbXxESUVaV1RXRUxVQlhIRDZETEozVXwxNTM5ODMzODYx|94bcc9a0c4ab6da617827432d021171d3b393fd3"
}
]
}
Response Example
The following example shows the contents of the response in JSON format:
{
"requestId": "fe520538-0da6-45a3-b23f-1256091e3f0c",
"deviceId": "ca0ba497327c45d2a4a408301c78682b",
"authFactor": "THIRDPARTY",
"thirdPartyFactor": {
"thirdPartyFactorId": "1c3a069c240b4a9d9e6e90b9a2be8bed",
"thirdPartyFactorType": "None",
"thirdPartyVendorName": "DUO_SECURITY"
},
"scenario": "ENROLLMENT",
"userName": "testuser1",
"schemas": [
"urn:ietf:params:scim:schemas:oracle:idcs:AuthenticationFactorValidator"
],
"meta": {
"resourceType": "MyAuthenticationFactorValidator",
"location": "https://tenant-base-url/admin/v1/MyAuthenticationFactorValidator"
},
"status": "SUCCESS",
"displayName": "test's Phone",
"mfaStatus": "ENROLLED",
"mfaPreferredDevice": "0d37a1334bdf4c9ca80474dcadba8d10",
"mfaPreferredAuthenticationFactor": "THIRDPARTY",
"mfaPreferredThirdPartyFactorType": "None",
"securityQuestionsPresent": false,
"devicesCount": 1,
"emailFactorEnrolled": false
}
In the response, the attribute mfaStatus:"ENROLLED"
indicates that user has enrolled for MFA. The mfaPreferredAuthenticationFactor
attribute indicates the factor set as the preferred method. In this case, it is THIRDPARTY
.