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

post

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

Request

Supported Media Types
Path Parameters
Header Parameters
Body ()
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
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
Back to Top

Response

Supported Media Types

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
Back to Top

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:

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:

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 Send Requests for the appropriate URL structure to use.

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"}
Back to Top