on - edited on by
Jason Kunst
- Introduction
- Components Used:
- Prerequisites:
- Configuration Steps:
- Twilio setup
- ISE setup:
- Sample POST message with Twilio
- Addendum support
Introduction
Cisco Identity Services Engine (ISE) provides the ability for a guest user to create an account using the Self-Registered Guest Portal. Newly created guest account credentials can be sent to the user via SMS or Email (or both). This guide provides the steps required to use the Twilio SMS service to send SMS to guest users. Twilio uses the HTTPS POST method to receive API calls to send messages.
Components Used:
1) Cisco ISE 2.1 patch 3
2) Twilio SMS service (https://www.twilio.com/)
Prerequisites:
1) ISE Policy Nodes have to be able to communicate with the URL https://api.twilio.com. The Twilio service is hosted on the Amazon Web service (AWS) cloud that has a dynamic IP range. Twilio servers are in the East Servers of the IP ranges described in http://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html. Allow outbound Firewall rules to these ranges to allow for successful communication.
2) ISE running the minimum versions given below:
- 1.4 patch 8
- 2.0 patch 3
- 2.1 and above
3) Twilio Account with Phone number.
Configuration Steps:
Twilio setup
1) Sign up for a Twilio account at Twilio | Try Twilio Free. You would need to verify your phone number for successful account creation. This is an important security step that is mandatory to trying Twilio.
2) Navigate to Home > Account > Account Settings to see your Live and Test credentials. Each of these will have an Account SID and Auth Token. These will translate to your HTTPS Username and Password on ISE SMS gateway settings.
3) Obtain a new phone number with SMS capabilities by going to https://www.twilio.com/console/phone-numbers/getting-started. Twilio provides a few free credits and a phone number for you to test the account without having to purchase a number and account balance.
More information on Twilio's trial capability is given here:
https://support.twilio.com/hc/en-us/articles/223136107-How-does-Twilio-s-Free-Trial-work-
ISE setup:
1) Upload the HTTPS CA certificate for the Twilio API URL (https://api.twilio.com) to allow ISE to have trusted communication. Twilio uses an SSL certificate issued by Thawte. Only the Thawte intermediate certificate (thawte SSL CA - G2) needs to be uploaded on to ISE as it should already have the Thawte Root CA certificate. The uploaded certificate is shown below (box checked).
2) Create an SMS Gateway at with the following Administration > Settings > SMS Gateway Provider List using the below settings.
| ISE setting | Value |
|---|---|
| Provider Interface Type | SMS HTTP API |
| URL |
|
| Data (Url encoded portion) | $message$ |
| Use HTTP POST method for data portion | Checked |
| HTTP POST data content type | application/x-www-form-urlencoded |
| HTTPS Username | <Twilio Account SID> |
| HTTPS Password | <Twilio Auth Token> |
| HTTPS Port | 443 |
From Number is the number obtained from Twilio. This is added in the URL section.
To Number is the number provided by Guests to send the message. This is automatically added by ISE in the request.
A snapshot of a working setup is below:
3) Configure the Self-Registered Guest Portal to use the new SMS Gateway.
Sample URL = https://api.twilio.com/2010-04-01/Accounts/ACea78bcaca92922a9ecf9a6bf47942c99/Messages.json?From=%2B19513392481
4) Once the Guests registers on the portal page, they should receive a message from the Twilio number. During registration, the Guest should add the entire E.164 format (+1xxxxxxxxx or 1xxxxxxxxxx for US numbers) of the phone number as ISE automatically adds the To Number into the POST request.
A sample message is seen below. Twilio adds "Sent from your Twilio trial account" for a trial number.
Sample POST message with Twilio
- URL : https://api.twilio.com/2010-04-01/Accounts/ACea78bcaca92622a9e5f9a5bf47944c99/Messages.json?From=%2B19513392481
- Content Type : application/x-www-form-urlencoded
- Body of the Message:
From=%2B19514452481&To=%2B15677053635&Body="testmessage 3 from Harish to phone using Twillio !!!
Note:
- Upload Twillio certificate ( the entire certificate chain ) to ISE trusted certificates Trust store ( ISE certificate Trust Store will already contain he Thawte issued root certificate )
- The “From” phone number is URL encoded for e.g. %2B19148765678 to represent +19148765678
- The “To” phone number when entered from an ISE portal such as Self-Registration Portal can be entered either as 19199056778 or with the preceding + (the E.164 number format) for e.g. +19199056778. The To phone number must not be entered as a URL encoded value.
Addendum support
12/3/2019 - To add information to keep this fresh @awatson20 found out that Twilio made a change to the certificate required. Had to export this cert, then import into ISE. Now this is working.
On August 20, 2018 at 9:45 AM Pacific, we updated our REST API's root certificate from Thawte Primary Root CA to DigiCert Global Root CA (this change was announced in June). If the errors you're seeing started on or after August 20, your system does not have our new root certificate installed in its local trust store. This can happen if you have pinned our old certificate, or if your local certificate bundle is out of date.
