Configure One-Time Passcode Phone Calls

Configure settings for sending a one-time passcode (OTP) as a phone call to users in Oracle Identity Cloud Service.

Prerequisite: Enable the Phone Call as a factor feature. This is Standard License feature. To learn about these features, see Standard License Tier Features for Oracle Identity Cloud Service.

1. In the Oracle Identity Cloud Service console, expand the Navigation Drawer, click Security, Factors. and then the Phone Number tab.
2. Make any necessary changes to the settings for the one-time passcode phone call to the user's device.
   • Passcode Length: The number of characters in the passcode.
   • Passcode Validity Duration: The number of minutes for which the passcode will be valid, after it is sent.
3. Add an external notification provider using the REST API /admin/v1/ExternalNotificationProviders endpoint. See Create the External Notification Provider.
4. In the Oracle Identity Cloud Service console, on the Phone Number tab, enable the factor Phone Call.
5. Click Save.
6. Create a phone call template using the REST API. There is a default phone call template in Oracle Identity Cloud Service that must be modified. If you don’t modify the template, you’ll get unwanted results. For example, for OTPs, you want the passcode spoken as digits (one, two, three, four) and not as a cardinal number (one thousand two hundred and thirty-four). Use SSML tags to make changes such as these in your template. See the Nexmo developer site at Customizing Spoken Text. When creating your template, use the following variables.
   • ${tenantName} - The name of the identity domain (or tenant).
   • ${companyName} - The name of the company that will appear in the notification.
   • ${userName} - The user's user name.
   • ${maskedUserName} - The masked user name. For example, if the user name is Jhony, then maskedUserName is Jhoxxxx.
   • ${OTP} - The OTP that’s sent to a user for the user to complete 2–Step Verification.
   • ${validity} - The amount of time (in minutes), after which the OTP will no longer be valid. As a result, the user can’t use it to enroll in 2–Step Verification.
7. Base64 encode the phone call template.
8. Configure the OTP phone call template using the following REST API PATCH request.

   Note:

   The value for localizedBody must be base64 encoded.

   The value for externalNotificationProvider is the id attribute returned from POST /admin/v1/ExternalNotificationProviders.

   curl --location --request PATCH
    ' https://tenant-base-url.com/admin/v1/PhoneCallTemplates/AuthenticationPhonecallRequestNEXMO'
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <ADMIN_TOKEN' \
   --header 'X-RESOURCE-IDENTITY-DOMAIN-NAME: <TENANT NAME' \
   --data-raw '{
       "Operations": [
           {
               "op": "replace",
               "path": "localizedBody[locale eq \"en\"]",
               "value": [
                   {
                       "value": "PHNwZWFrPlRoZSA8cHJvc29keSByYXRlPSJzbG93Ij50ZW5hbnQxPC9wcm9zb2R5PiBsb2dpbiBwYXNzY29kZSBmb3IgdGhlIGFjY291bnQgJHt1c2VyLnVzZXJOYW1lfSBpcyA8cHJvc29keSByYXRlPSJ4LXNsb3ciPjxzYXktYXMgaW50ZXJwcmV0LWFzPSJkaWdpdHMiPiR7T1RQfTwvc2F5LWFzPjwvcHJvc29keT4gVGhpcyBwYXNzY29kZSBpcyB2YWxpZCBmb3IgJHt2YWxpZGl0eX0gbWludXRlcy48L3NwZWFrPg==",
                       "locale": "en"
                   }
               ]
           },
           {
               "op": "add",
               "path": "externalNotificationProvider",
               "value": {
                   "value": "24e8b100b1b2461bada230541f3ac535"
               }
           },
           {
               "op": "add",
               "path": "eventId",
               "value": "authentication.phonecall.notification"
           }
       ],
       "schemas": [
           "urn:ietf:params:scim:api:messages:2.0:PatchOp"
       ]
   }