Initiate MFA Factor Enrollment With Verification or MFA Factor Enrollment Without Verification
/mfa/v1/users/{userGUID}/factors
Request
- application/json
-
userGUID: string
Unique identifier of a user who wants to enroll a factor.
-
Authorization: string
Provide a valid OAuth Access Token that has the 'MFA Client' scope.
object
-
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
- 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
-
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
-
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.
Response
200 Response
400 Response
401 Response
404 Response
500 Response
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 structurehttps://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
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 structurehttps://tenant-base-url/resource-path,
where
tenant-base-url
represents the Identity Service URL, and the resource path represents the Identity Service API.
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"
{
"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"}