OpenAM 2FA using the TeleSign PhoneID Score API

Introduction

TeleSign PhoneID Score combines predictive data from multiple sources, including telecom data, traffic patterns, and reported fraud to assess the risk level of a phone number. The product provides a reputation score, ranging from 0 to 1000, a risk level, and a recommendation based on a user’s phone number. PhoneID Score provides a real-time score, risk assessment, and recommendation. The scoring algorithm is dynamically updated to match ever-changing fraud trends. In fact, whenever a user’s activities change so does the score. More information can be found at TeleSign .

TeleSign Verify SMS API can be used to authenticate a known user, verify a transaction, or block fraudsters from opening thousands of accounts on your site. TeleSign Verify SMS verifies users in real time by sending a one-time verification code via SMS to their mobile phone. TeleSign delivers SMS to more than 200 countries. More info can be found here.

Demo

A custom authentication module receives the user’s telephone number, and uses TeleSign PhoneID Score API to evaluate the risk level of the phone number. If the phone number is of acceptable risk (low or moderate), then the authentication module uses the TeleSign Verify SMS API to send a verification code to the phone number entered.

The API returns a risk level for the phone number. If the risk level is “allow”, the module will send a random verify code via the TeleSign Verify SMS API, and upon user entry, use the TeleSign Verify SMS API to verify the code.

If the risk level from Score API is “deny”, OpenAM will show a denied screen to the user. A deny response looks like this:

{"reference_id":"####","sub_resource":"score","errors":[],"status":{"updated_on":"2015-03-10T22:48:59.139040Z","code":300,"description":"Transaction successfully completed"},"numbering":{"original":{"phone_number":"####","complete_phone_number":"####","country_code":"92"},"cleansing":{"sms":{"phone_number":"####","country_code":"92","min_length":9,"max_length":12,"cleansed_code":105},"call":{"phone_number":"####","country_code":"92","min_length":9,"max_length":12,"cleansed_code":105}}},"risk":{"level":"high","score":959,"recommendation":"block"}}

If the user entered an incorrect code, the TeleSign Verify SMS API will indicate as such, and OpenAM will reject the login attempt.

If the verify code validates correctly, then the user simply has to enter their username to login to AM.

An low risk response from the TeleSign PhoneID Score API looks like this:

{"reference_id":"####","sub_resource":"score","errors":[],"status":{"updated_on":"2015-03-10T22:52:17.603141Z","code":300,"description":"Transaction successfully completed"},"numbering":{"original":{"phone_number":"####","complete_phone_number":"####","country_code":"1"},"cleansing":{"sms":{"phone_number":"####","country_code":"1","min_length":10,"max_length":10,"cleansed_code":100},"call":{"phone_number":"####","country_code":"1","min_length":10,"max_length":10,"cleansed_code":100}}},"risk":{"level":"low","score":1,"recommendation":"allow"}}

Note that TeleSign uses a global phone directory, so if you do not prefix your country code, it will take the first digit(s) from the phone from the left and use that to identify the country.

Source Code

Github

 

This article was first published on the OpenAM Wiki Confluence site: OpenAM and TeleSign Integration