Okta has just made generally available its Workflows Connector Builder and I am writing this post to celebrate. Okta’s Workflow Connector Builder delivers the powerful concept of reuse to your Workflows. It allows you build connections and actions once for re-use throughout all of your Workflows. Additionally, it gives vendors the opportunity to build and test their own workflows before submitting them to Okta for publication in our Connector Library. In this post I’ll show you the steps to create a Twilio Messaging Connector. This could be used to greatly simplify my last post “Bring Your Own Messaging Provider: WhatsApp OTP with Inline Hooks & Workflows“. We will be following the steps laid out in this blog post and in the Okta documentation. The high level steps as detailed are:
- Create your connector project
- Configure required authentication
- Create connector flows
- Test the connection
- Deploy your connector
- Submit to Okta
Read on to see how to use these steps to create a Twilio Messaging Connector.
Prerequisites
In order to complete this blog you’ll need access an Okta tenant with Workflows enabled and a Twilio account. If you do not yet have a Twilio Account you can head over here and create one. You’ll get a small amount of credit, enough to try this out. I recommend reading through this guide to understand how to work with the trial account.
Create Twilio Messaging Connector Project
To create the new connector navigate to the Workflows Console in your Tennant and click on the Connector Builder Button in the top right then click the + next to Connectors in the top left. You’ll then be asked for a name and description. You can then edit the Settings and add things like a custom Icon, colour scheme, documentation URL and support email.
Setup Authentication
The next step is to follow the prompt and setup Authentication by clicking on Set up Authentication as shown below.
Twilio leverages basic authentication as well as leveraging an account SID in the URL. Here we suggest that you follow best practice and leverage API keys rather than using your Account SID and Auth Token as your user name and password. For details on how to obtain an API key I recommend reading Better Twilio Authentication with API Keys. Setup your authentication as shown below with API Key SID as your username and API Secret as the password. Also add Account SID as an optional Parameter of type text.
Creating required Flows
Now that we have captured the required settings we need to build the required flows. Each connector requires several specific flows to be built in particular for Twilio we need the following.
| Flow Type | Description |
|---|---|
| Helper Flow | This flow manages two things for each action card that you’ll build in Connector Builder: authentication and any HTTP request. This is implemented in support of the Don’t Repeat Yourself (DRY) principle of software development aimed at reducing repetition of software patterns. |
| Action Flow | A Custom API Action (CAPIA) is an action card available on a connector that allows the end user to make an authenticated HTTP request to the service in question. The base url is hard coded into the connector, so users only need to add the relative url for the endpoint. They then manually create the required objects for header, query, and/or request body if necessary. The CAPIA then returns data from the service as three outputs: Status Code, Headers, and Body. |
| Authping Flow | This is a system flow that allows the platform to “ping” an API and check for valid authorization. This acts as a sort of health check that runs when the connector is first authenticated, new connectors are added, or flows are opened. The flow must be named _authping in order to be recognized by the platform. Authping flows are not displayed to the end user and are only used by the platform. It has no options or input fields. |
The first flow required is the helper flow. This will be used for ALL requests made by the Connector as well as by the Authping flow. This flow uses the HTTP Raw Request Card to actually make the request out to the Twilio service. The flow, shown below, does the following things.
Helper Flow
- Creates the headers
- It creates the authentication value which is a Base64 encoded concatenation of the username and password after the word Basic
- It leverages an object construct card to create the Authorization header containing the authentication value from above and adds a Content-Type: application/json header.
- Then it merges any headers from the inbound request with the above headers.
- Creates the request URL by taking the base URL: https://api.twilio.com/2010-04-01/Accounts/ adding the account SID we specified in the settings and then appending the relative URL provided to the helper flow.
- Sends a HTTP Raw Request to Twilio with the headers and URL created plus any query parameters or body passed the helper flow
- Returns the results with a Flow Control Return card.
Authping Flow
The next flow to create is the Authping flow. This is a system flow with the reserved name of _authping. This flow must be setup to make a request using the above Helper Flow to a Twilio endpoint that will always return something if the account settings are correct. Okta will use this to check the status of the connection. The endpoint used must not trigger any actions on the other end. In our case with Twilio we are simply checking the list of messages sent and confirming we are getting a valid response. The flow, depicted below, was constructed following the documentation. It calls the helper flow above from within an If Error block, checks if the status code is a 200 and returns this status. Essentially if it is not a 200 Ok then it will return a status of not working: false.
Send Message
The final workflow we will create here is a Connector Action this will be made available for users of the connector in their workflows. In this case we’re going to create a Send Message card. There are a number of variants that would possibly make sense with a Twilio Connector send WhatsApp Message and send using Messaging Service (the preferred way to send with Twilio) would both be great options.
The workflow uses the on-demand Connector Action card which can take Options and Inputs. Options are set when adding the card to the workflow and are static across all runs of that instance of the workflow. In our case we are going to request a From Number as an option. When a user adds the card to the workflow they will be asked to specify the Twilio number from which the messages will come.
We will also specify the To number and Body as inputs. These will need to be supplied to the card every time the flow is run.
The flow itself is straightforward we create the request body by concatenating the To, From and Body together. We add a Content-Type header set to application/x-form-url-encoded and then we call our Helper Flow and return the results.
Testing the Connector
Once you have built the flows we can test the flow. To do this hit Test inside the Send Message flow. At this point if you have not yet created a test connection you’ll be prompted to set one up. Follow the prompts and supply your Twilio API Key SID and Secret along with your account SID. Then fill in the Options and Inputs as appropriate. Then click Run Test and you should receive. a test message on your test device.
Deploying the Connector
Once tested you can switch to the deployment tab and hit create test version. This will make live within your Okta tenant for use within Workflows as a test connector. After validation you can then optionally create a private deployment by clicking the actions menu and selecting Deploy Version
To leverage your Test or deployed Connector navigate to the standard Workflow console and create a new flow. You’ll be able to then select the Send Messaging action by selecting Add app action and searching for Twilio. Note that you need to select Include test connectors to see the test version.
Once you have selected the Send Message action you should populate the From option and save it as shown below.
You can then create a very simple test flow that takes a To number and Body and calls the Send Message card as shown below.
Assuming everything was setup correctly you should be able to save and test this flow to receive another test message.
Submitting your Connector
If you’re only intending to use the connector internally then at this stage you’re all set. Alternatively if you’d like to make this available to other users you can follow the process outlined here to submit it to Okta.
Resources
Exporting the workflows from within connector builder is not allowed, the intent being that Connectors would instead be submitted and approved. As such I have not exported the FloPacks for this blog post. Instead you should recreate them from the images and instructions above.
