Configure Okta Workflows for an external telephony provider
This Okta Workflows use case falls under Yellow Zone. It requires careful attention to architecture and best practices because it has a higher risk of running into system limits or other caveats. Learn more at Workflows system limits.
Okta recommends using the Okta API instead. See the developer documentation: Telephony inline hook reference.
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
- In the Admin Console, go to .
- In the Workflows console, click .
You can now add cards to your new flow.
Create the API Endpoint event card
- Click Add Event. Search for and select the Okta app for API Endpoint.
- In the API Endpoint settings window, set the Security level to Secure with client token.
- Leave the Client token field blank and click Close.
- 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
- Click Add function. Search for and select the Compose function card.
- In the card, enter the following text: To=phoneNumber&From=<yourphonenumber>&Body=messageTemplate
- Map phoneNumber and messageTemplate. Drag and drop these fields from the API Endpoint event card.
- 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
- Click Add function. Search for and select the Construct function card (Object type).
- In the card, create input text fields: Accept and Content-type.
- Enter values in the fields:
- Accept: application/json
- Content-type: application/x-www-form-urlencoded
Create an If Error function card
- Click Add function. Search for and select the If Error function card.
- Ensure the If Error function card is in the Try mode.
Inside this card, create the following cards.
Create an API Connector card
- Inside the + menu, click the cloud icon. Search for and select the API Connector card.
- Select the Post type.
- In the Post card, enter the SMS message URL for your telephony provider.
- Drag and drop the Output field from the Construct function card to the field.
- Drag and drop the Output field from the Compose function card to the field.
- In sid text field. , create the
Create a Compose function card for success
- Next to the Post card, inside the + menu, click the calculator icon. Search for and select the Compose function card.
-
In the card, enter the following code:
Copy{
"commands":[
{
"type":"requestType",
"value":[
{
"status":"SUCCESSFUL",
"provider":"<YOURPROVIDER>",
"transactionId":"sid"
}
]
}
]
} - Map requestType. Drag and drop this field from the API Endpoint event card.
- Replace <YOURPROVIDER> with the name of your telephony provider.
- Drag and drop the sid field from the Post card.
- Click the dropdown menu for the Output field to rename it Success.
- Click View outputs for the If Error card.
- Create an output object field called Response.
- Under the Response field, drag and drop the Success field from the Compose card.
Add error fields
- In the If Error card, switch the Try mode to If Error mode.
- 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
- Next to the Error output fields, inside the + menu, click the calculator icon. Search for and select the Compose function card.
-
In the card, enter the following code:
Copy{
"error":{
"errorSummary":"Failed to deliver SMS to phoneNumber",
"errorCauses":[
{
"errorSummary":"Couldn't deliver OTP",
"reason":"message"
}
]
}
} - Drag and drop the phoneNumber field from the API Endpoint event card.
- Drag and drop the message field from the Error output.
- Click the dropdown menu for the Output field to rename it Error.
- 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
-
In the flow, click Add function. Search for and select the Return Raw function card.
-
Drag and drop the Output field from the Construct card to the Headers field.
-
Drag and drop the Response field of the If Error card to the Body field.
-
Save the flow and turn it on.
The Workflow is now set.
Copy information for telephony inline hook
- Go to the API Endpoint event card, and then click the </> icon. API Endpoint settings appear.
- 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.