ISE Guest SMS support for Telnyx provider

[tjanssen]

• Introduction
• Components Used:
• Prerequisites:
• Configuration Steps:
• Telnyx setup
• ISE setup:

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 Telnyx SMS service to send SMS to guest users. Telnyx uses the HTTPS POST method to receive API calls to send messages. Credit goes to Rahul Govindan for initially getting ISE to communicate with Twilio which this guide is based on. 

Components Used:

1) Cisco ISE 3.0

2) Telnyx SMS service (https://www.telnyx.com/)

Prerequisites:

1) ISE Policy Nodes have to be able to communicate with the URL https://api.telnyx.com. The Telnyx service is hosted behind the CloudFlare (CF) cloud that has a dynamic IP range. Telnyx servers are geographically diverse of the IP ranges described in https://www.cloudflare.com/ips/. Allow outbound Firewall rules to these ranges to allow for successful communication.

2) ISE running the minimum versions given below:

1.     1.4 patch 8
2.     2.0 patch 3
3.     2.1 and above

3) Telnyx Account with Phone number.

Configuration Steps:

Telnyx setup

1) Sign up for a Telnyx account at Telnyx. 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 API Keys to create an API key for use with Cisco ISE. This will translate to your HTTPS Password on ISE SMS gateway settings.

3) Head to a command prompt or a Linux terminal and enter the following command:

curl --request GET \
  --url https://api.telnyx.com/v2/whoami \
  --header 'Authorization: Bearer ${auth_v2_api_key}'

The above command will yield the following result which you will want to take note of the organization_id. This will translate to your HTTPS Username on ISE SMS gateway settings.

{
  "data": {
    "organization_id": "ORGANIZATION_ID",
    "user_id": "USER_ID"
  }
}

3) Obtain a new phone number with SMS capabilities by going to https://portal.telnyx.com/#/app/numbers/search-numbers

ISE setup:

1) Upload the HTTPS CA certificate for the Telnyx API URL (https://api.telnyx.com) to allow ISE to have trusted communication. Telnyx uses an SSL certificate issued by CloudFlare. Only the CloudFlare intermediate certificate (Cloudflare Inc ECC CA-3) needs to be uploaded on to ISE as it should already have the Baltimore CyberTrust 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	https://api.telnyx.com/2010-04-01/Accounts/<Organization-ID>/Messages.json e.g https://api.telnyx.com/2010-04-01/Accounts/57cfad55-7293-4645-91dd-10bd3f5736b6/Messages.json
Data (Url encoded portion)	{     "From": "<Your Telnyx Number Here in E.164 Format",     "To": $mobilenumber$,     "Body": $message$ }
Use HTTP POST method for data portion	Checked
HTTP POST data content type	application/json
HTTPS Username	<Telnyx Organization ID>
HTTPS Password	<Telnyx API Key Created Earlier>
HTTPS Port	443

From Number is the number obtained from Telnyx. This is added in the Data (Url encoded portion).

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.telnyx.com/2010-04-01/Accounts/57cfad55-7293-4645-91dd-10bd3f5736b6/Messages.json

4) Once the Guests registers on the portal page, they should receive a message from the Telnyx number. During registration, the Guest should select their country that their cell phone is from as it will format the $mobilenumber$ with 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. 

Sample POST message with Telnyx 

1. URL : https://api.telnyx.com/2010-04-01/Accounts/57cfad55-7293-4645-91dd-10bd3f5736b6/Messages.json
2. Content Type : application/json
3. Body of the Message:

{
    “From”: ”+19514452481”,
    ”To”:”+15677053635”,
    ”Body”:"testmessage 3 from Trevor to phone using Telnyx !!!
}

Note:

1. Upload Telnyx certificate ( the entire certificate chain ) to ISE trusted certificates Trust store ( ISE certificate Trust Store will already contain the Baltimore CyberTrust issued root certificate )
2. 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.