Configure Okta Workflows for an external telephony provider

This task explains how to create a flow in Okta Workflows to send the one-time passcode (OTP) to your end users through the telephony provider of your choice. The flow looks like this upon creation:

Before you begin

• Review Telephony documentation to understand regulatory requirements, toll fraud, and technical considerations.

• Set up Okta Workflows.
  • Set up a connection from the Okta org. See Authorize the Okta connector.
  • Set up a connection for the API Connector. See Authenticate with API Connector cards.
• Set up a telephony provider of your choice. Take note of this information:
  • Account SID
  • Auth token
  • Phone number
  • SMS message URL to send POST requests. For example, for Twilio it’s https://api.twilio.com/2010-04-01/Accounts/<yourtwilioaccountid>/Messages.json where <yourtwilioaccountid> is your Twilio account ID.

Create a flow

1. In the Admin Console, go to WorkflowWorkflows console.
2. In the Workflows console, click FlowsNew Flow.

You can now add cards to your new flow.

Create the API Endpoint event card

1. Click Add Event. Search for and select the Okta app for API Endpoint.
2. In the API Endpoint settings window, set the Security level to Secure with client token.
3. Leave the Client token field blank and click Close.
4. In the Body section, create the following fields. Click the dropdown menu for the field to change its type.

Field	Type
data	Object
> userProfile	Object
> > userId	Text
> messageProfile	Object
> > messageTemplate	Text
> > phoneNumber	Text
> > otp	Text
requestType	Text

Create a Compose function card

1. Click Add function. Search for and select the Compose function card.
2. In the card, enter the following text: To=phoneNumber&From=<yourphonenumber>&Body=messageTemplate
3. Map phoneNumber and messageTemplate. Drag and drop these fields from the API Endpoint event card.
4. Replace <yourphonenumber> with your phone number. This is the number that you got from your telephony provider, including the country code.

Create a Construct function card

1. Click Add function. Search for and select the Construct function card (Object type).
2. In the card, create input text fields: Accept and Content-type.
3. Enter values in the fields:
   • Accept: application/json
   • Content-type: application/x-www-form-urlencoded

Create an If Error function card

1. Click Add function. Search for and select the If Error function card.
2. Ensure the If Error function card is in the Try mode.

Inside this card, create the following cards.

Create an API Connector card

1. Inside the + menu, click the cloud icon. Search for and select the API Connector card.
2. Select the Post type.
3. In the Post card, enter the SMS message URL for your telephony provider.
4. Drag and drop the Output field from the Construct function card to the Request Headers field.
5. Drag and drop the Output field from the Compose function card to the Request Body field.
6. In Request Body, create the sid text field.

Create a Compose function card for success

1. Next to the Post card, inside the + menu, click the calculator icon. Search for and select the Compose function card.

2. In the card, enter the following code:

   Copy

   {
    "commands":[
      {
        "type":"requestType",
        "value":[
          {
            "status":"SUCCESSFUL",
            "provider":"<YOURPROVIDER>",
            "transactionId":"sid"
          }
        ]
      }
    ]
   }

3. Map requestType. Drag and drop this field from the API Endpoint event card.
4. Replace <YOURPROVIDER> with the name of your telephony provider.
5. Drag and drop the sid field from the Post card.
6. Click the dropdown menu for the Output field to rename it Success.
7. Click View outputs for the If Error card.
8. Create an output object field called Response.
9. Under the Response field, drag and drop the Success field from the Compose card.

Add error fields

1. In the If Error card, switch the Try mode to If Error mode.
2. In the Error output, create the following fields. Click the dropdown menu for the field to change its type.

Field	Type
body	Object
> code	Text
> status	Text
> message	Text

Create a Compose function card for error

1. Next to the Error output fields, inside the + menu, click the calculator icon. Search for and select the Compose function card.

2. In the card, enter the following code:

   Copy

   {
     "error":{
       "errorSummary":"Failed to deliver SMS to phoneNumber",
       "errorCauses":[
         {
           "errorSummary":"Couldn't deliver OTP",
           "reason":"message"
         }
       ]
     }
   }

3. Drag and drop the phoneNumber field from the API Endpoint event card.
4. Drag and drop the message field from the Error output.
5. Click the dropdown menu for the Output field to rename it Error.
6. Drag and drop the Error field under the Response section of the If Error card.

The card in the If Error mode looks like this:

The If Error function card is now complete.

Create a Return Raw card

1. In the flow, click Add function. Search for and select the Return Raw function card.

2. Drag and drop the Output field from the Construct card to the Headers field.

3. Drag and drop the Response field of the If Error card to the Body field.

4. Save the flow and turn it on.

The Workflow is now set.

Copy information for telephony inline hook

1. Go to the API Endpoint event card, and then click the </> icon. API Endpoint settings appear.
2. From the settings, copy the following information: Invoke URL, Alias, and Client Token.

You'll need this information in the next step when creating a telephony inline hook.

Next step

Connect to an external telephony service provider