REST API for Oracle Identity Cloud Service

Initiate MFA Factor Enrollment With Verification or MFA Factor Enrollment Without Verification

post

/mfa/v1/users/{userGUID}/factors

Request

Supported Media Types

application/json

Path Parameters

userGUID: string

Unique identifier of a user who wants to enroll a factor.

Header Parameters

Authorization: string

Provide a valid OAuth Access Token that has the 'MFA Client' scope.

Initiate MFA Enrollment Schema

Root Schema : InitiateEnrollment

Type: object

Use this schema to initiate enrollment of MFA factors with or without factor verification. The enrollment is a 2-step process if verification is required. In case of enrollment without verification, it is a single step process.

Show Source

countryCode(optional): string

This attribute is considered only if the method is set to SMS or PHONE_CALL.
This is the international country code that should be prefixed to the mobile number, to be enrolled for SMS or PHONE_CALL.
method: string
It indicates the factor or method that the user wants to enroll for MFA. Supported values for this attribute are:
- SMS
- PHONE_CALL
- TOTP
- PUSH
- EMAIL
- SECURITY_QUESTIONS
Depending on the method being enrolled for, additional attributes of this schema may need to be provided.
mobileNumber(optional): string

This attribute is considered only if the method is set to SMS or PHONE_CALL.
This is the mobile number that the user wants to enroll for the SMS or PHONE_CALL factor.
offlineTOTP(optional): string
This attribute is considered only if the method is set to TOTP.
Supported values for this attribute are:
- true
- false
A value of 'true' indicates that the user wants to enroll for the offline TOTP factor. By default, the user is enrolled for the online TOTP method if this value is false or is missing.
otpCode(optional): string

This attribute is considered only for offline TOTP method and if skipFactorVerification is set to true. If otpCode is provided, the sharedSecret passed is used to generate an otpCode and is validated with the passed otpCode value, before enrolling the TOTP factor.
sharedSecret(optional): string

Shared Secret of the hardware device or third party provider which has to be enrolled for offline TOTP. This attribute is considered only if skipFactorVerification is set to true.
skipFactorVerification(optional): string
This attribute indicates that factor verification should be skipped during enrollment.Supported values for this attribute are:
- true
- false
This attribute is applicable only for SMS, PHONE_CALL, EMAIL and offline TOTP factors.

{
    "type":"object",
    "description":"Use this schema to initiate enrollment of MFA factors with or without factor verification. The enrollment is a 2-step process if verification is required. In case of enrollment without verification, it is a single step process.",
    "required":[
        "method"
    ],
    "properties":{
        "method":{
            "type":"string",
            "description":"It indicates the factor or method that the user wants to enroll for MFA. Supported values for this attribute are:<ul><li>SMS</li><li>PHONE_CALL</li><li>TOTP</li><li>PUSH</li><li>EMAIL</li><li>SECURITY_QUESTIONS</li></ul><br>Depending on the method being enrolled for, additional attributes of this schema may need to be provided."
        },
        "skipFactorVerification":{
            "type":"string",
            "description":"This attribute indicates that factor verification should be skipped during enrollment.Supported values for this attribute are:<br><ul><li>true</li><li>false</li> </ul><br>This attribute is applicable only for SMS, PHONE_CALL, EMAIL and offline TOTP factors."
        },
        "offlineTOTP":{
            "type":"string",
            "description":"This attribute is considered only if the method is set to TOTP.<br>Supported values for this attribute are:<br/><ul><li>true</li><li>false</li></ul>A value of 'true' indicates that the user wants to enroll for the offline TOTP factor. By default, the user is enrolled for the online TOTP method if this value is false or is missing."
        },
        "sharedSecret":{
            "type":"string",
            "description":"Shared Secret of the hardware device or third party provider which has to be enrolled for offline TOTP. This attribute is considered only if skipFactorVerification is set to true.<br>"
        },
        "otpCode":{
            "type":"string",
            "description":"This attribute is considered only for offline TOTP method and if skipFactorVerification is set to true. If otpCode is provided, the sharedSecret passed is used to generate an otpCode and is validated with the passed otpCode value, before enrolling the TOTP factor.<br>"
        },
        "countryCode":{
            "type":"string",
            "description":"This attribute is considered only if the method is set to SMS or PHONE_CALL.<br>This is the international country code that should be prefixed to the mobile number, to be enrolled for SMS or PHONE_CALL."
        },
        "mobileNumber":{
            "type":"string",
            "description":"This attribute is considered only if the method is set to SMS or PHONE_CALL.<br>This is the mobile number that the user wants to enroll for the SMS or PHONE_CALL factor."
        }
    }
}

Response

200 Response

Indicates that the enrollment request was accepted and initiated successfully.

400 Response

Indicates that the request payload is invalid.

401 Response

Indicates that the enrollment request failed due to an invalid token or an inactive or locked user.

404 Response

Indicates that the userGUID provided is invalid.

500 Response

Internal Server error

Examples

The following examples show how to initiate MFA factor enrollment by providing the userId when submitting a POST request on the REST resource using cURL. For more information about cURL, see Use cURL

There are two types of enrollments. For eg:

Initiate Enrollment With Verification

The enrollment of some factor methods is a 2-step process. You first need to ask Oracle Identity Cloud Service to "initiate" the factor enrollment (for example, send an SMS with a time-based one-time passcode (TOTP) or send an email with a TOTP code). See Complete Factor Enrollment or Resend OTP or Update Security Questions to know about the complete factor enrollment.

After initiating enrollment, the client needs to "activate" the enrollment. Use the PATCH method for this endpoint to activate factors.

Note:

There is an Oracle Identity Cloud Service Factor Verification Postman collection available. Download the collection and example environment with variables from the idcs-factor-enrollment-api folder within GitHub and import them into a REST client.

cURL Command

Note:

The command in this example uses the URL structure https://tenant-base-url/resource-path, where tenant-base-url represents the Identity Service URL, and the resource path represents the Identity Service API. See SendRequests for the appropriate URL structure to use.

The following request and response examples are included for this API:

Example of a Request Body When Initiating Enrollment of a Factor
Example of a Response Body When Initiating Enrollment of a Factor
Error Response Examples

cURL Command

curl
-X PATCH
-H "Content-Type:application/scim+json"
-H "Authorization: Bearer <Access Token Value>"
https://tenant-base-url/mfa/v1/users/{userGUID}/factors/{factorId}

Example of a Request Body When Initiating Enrollment of a Factor

The following examples show the contents of the request body in JSON format when initiating enrollment a factor.

SMS Factor

{
    "method": "SMS",
    "countryCode": "+1",
    "mobileNumber": "55...12"
}

EMAIL Factor

{
 "method":"EMAIL"
}

Offline TOTP

{
 "method":"TOTP",
 "offlineTOTP":true
}

Online TOTP

{
 "method":"TOTP",
 "offlineTOTP":"false"
}

PUSH Notification

{
 "method":"PUSH"
 }

Example of a Response Body When Initiating Enrollment of a Factor

The following examples show the contents of the response body in JSON format when initiating enrollment for the various factor methods. The response contains the factorId and the requestState needed for the next request (which for some factors is to activate the factor using the PATCH method):

SMS Factor

{
    "status": "success",
    "factorId": "88178d80636a428393a5674ba46dc867",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "SMS"
    ],
    "displayName": "+155XXXXXX212",
    "requestState": "QK1.....y+OFP//0"
}

EMAIL Factor

{
    "status": "success",
    "factorId": "30db2274140043918edb033d9fe29ff3",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "EMAIL"
    ],
    "displayName": "user1@example.com",
    "requestState": "Vxar...bWTTA"
}

Offline TOTP

{
    "status": "success",
    "factorId": "559e64eee54b4b738ee341ca01c4b8ac",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "TOTP"
    ],
    "displayName": "Joe's Phone-1",
    "requestState": "dkCIfOV......gRj0Rn4",
    "qrCode": {
        "content": "otpauth://totp/user1%40example.com?issuer=tenant1.=30&algorithm=SHA1&digits=6&RSA=SHA256withRSA&Deviceid=559e64eee54b4b738ee341ca01c4b8ac&RequestId=e688914e-7e24-41ca-9967-bcbb72954b58&secret=UUXLTNHWLI2OGZZ6IZMSY2333Q&ServiceType=TOTP&KeyPairLength=2048&SSE=Base32",
        "imageData": "iVBORw0KGg.........K5CYII=",
        "imageType": "image/png"
    },
    "sharedSecret": "UUXLTNHWLI2OGZZ6IZMSY2333Q",
    "offlineTOTP": "true"
}

Online TOTP

{
    "status": "success",
    "factorId": "a5286a1014a34043b4cce16eca806029",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "TOTP"
    ],
    "displayName": "Joe's Phone",
    "requestState": "3zBT19+Kq9HV....dj7sObxU",
    "qrCode": {
        "content": "oraclemobileauthenticator://totp/user1%40example.com?issuer=tenant1.=30&algorithm=SHA1&digits=6&RSA=SHA256withRSA&Deviceid=a5286a1014a34043b4cce16eca806029&RequestId=fe9d6fbc-f2c7-425d-bf58-55566b2a26c4&LoginURL=https%3A%2F%2Ftenant-base-url%3A8943%2Fsso%2Fv1%2F&OTP=eyJraWQiOiJTSUdOSU5HX0tFWSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJkZXZpY2VfaWQiOiJhNTI4NmExMDE0YTM0MDQzYjRjY2UxNmVjYTgwNjAyOSIsImlzcyI6IkF1dGhTcnYiLCJleHAiOjE1MzY4ODE5NzYsImlhdCI6MTUzNjg4MTY3NiwidGVuYW50IjoiamFzc2kxIn0.NZUWkzi2Ci_f_nj2S1XBPLaRTBDQoJxisTRYNrs9ZRB1bF1KKDjoV6kwLrFELb8yrRNIkkKYxaKJn8ambjkysrCUS3RN3YsdAS5C6xD39zK6SzR-iHx0ElYES1TWPRwFd_Wh6sK0QaMRNu8b_E-QbM4BOXPpMIO9tG27AMJMaHYOrsFlGEvbqnwwaZDsGxWYO-9ORdS72hA1MYCp3mj9slXM1pY2AtuegEaV5Dr4s8jTCeR5LjdbvMZ2vNR64AklrhxpTk4SCyZhqR6fAb8OoNbGxT6-4X9ZgsJcRZWw547VxzrbWq9Q8hm3-xTSe-GlnUDecYQbk1V4uwkdB3ifMw&ServiceType=TOTP&KeyPairLength=2048&SSE=Base32",
        "imageType": "image/png",
        "imageData": "iVBORo.....RK5CYII="
    }
}

PUSH Notification

{
    "status": "success",
    "factorId": "6b6bb140859f4b98bf8de23090fb2eeb",
    "factorStatus": "ENROLLMENT_INITIATED",
    "methods": [
        "PUSH",
        "TOTP"
    ],
    "displayName": "Joe's Phone",
    "requestState": "RkVaKa....9EUeQdpA",
    "qrCode": {
        "content": "oraclemobileauthenticator://totp/user1%40example.com?issuer=tenant1.=30&algorithm=SHA1&digits=6&RSA=SHA256withRSA&Deviceid=6b6bb140859f4b98bf8de23090fb2eeb&RequestId=39419f7f-8788-4a69-a5ff-92e58bdb5b20&LoginURL=https%3A%2F%2Ftenant-base-url%3A8943%2Fsso%2Fv1%2F&OTP=eyJraWQiOiJTSUdOSU5HX0tFWSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJkZXZpY2VfaWQiOiI2YjZiYjE0MDg1OWY0Yjk4YmY4ZGUyMzA5MGZiMmVlYiIsImlzcyI6IkF1dGhTcnYiLCJleHAiOjE1MzY4ODE3MDcsImlhdCI6MTUzNjg4MTQwNywidGVuYW50IjoiamFzc2kxIn0.k00pS861JTCT345YlA38SqJc4FApw7HJxci44Ii6m_Zk1p5rEgm65Z40RnT6_bOL4A9gcAHZWV7TcgDSre6DhjHfCaIypPZcHdxAOjwHRuF1T1sOEFDOuEPQO5vs56hanBxlt5MPCwgIikdO9Hv-xpAtz2XWP_JJqeKAuSXdcdtDmA5WAs4SkInQhmFQ_AZsWPJkOzfndbKXvVp1TPIG_NEy5mGSTCYFIGU8Jev_C3b8mclOKVfQz6TnOOsYQ40A4yY0mU0YcDDQm_TwaARAt3MQ6CJGboBGXnZud--d56p2k3ecxZSDQ9CfXdYMeWD_RWB_Mn2bCr8sy0ILrSTx2A&ServiceType=TOTP%2BPUSH&KeyPairLength=2048&SSE=Base32",
        "imageType": "image/png",
        "imageData": "iVBORw0KGgo.....lFTkSuQmCC"
    }
}

Error Response Examples

The following example shows the contents of the response body in JSON format when the user name or userGUID provided is invalid:

{
    "status": "failed",
    "ecId": "0d1QwglU0000Fy",
    "cause": [
        {
            "code": "AUTH-3018",
            "message": "User not found."
        }
    ]
}

The following example shows the contents of the response body in JSON format when the factor is disabled:

{
    "status": "failed",
    "ecId": "0000M00000A",
    "cause": [
        {
            "code": "AUTH-1125",
            "message": "The SMS/EMAIL/TOTP/PUSH factor has been disabled."
        }
    ]
}

The following example shows the contents of the response body in JSON format when the user is account is locked:

{
    "status": "failed",
    "ecId": "0ISDCif1Qy6wg0000A8",
    "cause": [
        {
            "code": "AUTH-1010",
            "message": "Your account is locked. Contact your system administrator."
        }
    ]
}

Enrollment Without Verifcation

This allows a user to enroll for MFA factors without factor verification. The enrollment of some factor method is a single step process.The factors supported are SMS, EMAIL and OFFLINE TOTP.

Note:

cURL Command

Note:

The following request and response examples are included for this API:

Example of a Request Body When Enrolling of a factor Without Verification

The following examples show the contents of the request body in JSON format when completing enrollment for various factor methods.

SMS Factor

{
    "method": "SMS",
    "countryCode": "+1",
    "mobileNumber": "+44XXXXXXXX213"
    "skipFactorVerification":"true"
}

EMAIL Factor

{
 "method":"EMAIL"
 "skipFactorVerification":"true"
}

Offline TOTP

For offline TOTP, otpCode is optional. If provided, the server uses the shared secret and generates an OTP and matches it with the OTP provided. If OTP and shared secret dont match, enrollmeet fails. However, users can also enroll by just providing only the shared secret without giving OTP where in no OTP validation occurs.

{
 "method":"TOTP",
  "sharedSecret":"QYV81R", 
  "skipFactorVerification":"true",  
  "offlineTOTP":"true"
}

Example of a Response Body When Enrolling a Factor Without Verification

The following examples show the contents of the response body in JSON format when completing enrollment for the various factor methods.

SMS factor Enrollment Without Verification

{  
   "status": "success",
   "factorId": "b0a587f8962f42259c34f64ea3e8935c",
   "factorStatus": "ENROLLED",
   "methods": [
       "SMS"
   ],
   "displayName": "+44XXXXXXXX213"

Email Factor Enrollment Without Verification

{  
  "status": "success",
   "factorId": "aeecf9d47166470bb3c98504e8171ce6",
   "factorStatus": "ENROLLED",
   "methods": [
       "EMAIL"
   ],
   "displayName": "joe.john@oracle.com"
}

Offline TOTP Without Verification

{ 
"status": "success",
   "factorId": "9cce673a9b8e45d99fa8fc74a74057fb",
   "factorStatus": "ENROLLED",
   "methods": [
       "TOTP"
   ], 
"displayName": "Joe John's Phone"}