Documentation

Introduction

Use this guide to configure the SecureAuth Authentication API to block specified phone sources, block or allowed lists for phone carriers / countries, and identify phone numbers that recently changed carriers in order to prevent bad actors from using specified phone classes / numbers.

When the end-user attempts to use a phone number as a second authentication factor, an SMS OTP / Voice OTP is dispatched only if the phone number is allowed based on information retrieved from the phone number profiling service.

Prerequisites

1. Complete the steps in the Authentication API Guide

2. Complete Phone Profiling Service configuration steps in the SecureAuth IdP Web Admin

Refer to Phone Number Profiling Service Configuration Guide for additional information

SecureAuth IdP Web Admin
Phone Profiling Service Configuration Steps

Phone Profiling Service must be configured in the Web Admin before Endpoints can be configured 

Data


1. This step is required if the feature to Block Phone Numbers that Recently Changed Carriers is used

Map the Aux ID 2 Profile Property to a directory field that meets these requirements

    • Directory String (syntax: 2.5.5.12)
    • Upper Range of at least 4096
    • Multi-valued (true)

Set the Property to be Writable

NOTE: For example, accountNameHistory can be selected, if not already used

Click Save once the configuration is complete and before leaving the Data page to avoid losing changes

Multi-Factor Methods


2. Configure the Phone Number Blocking frame on the Registration Configuration section for the specified option(s)

The phone number blocking configuration only applies to this realm

Block Phone Numbers from the Following Sources


3. In Block phone numbers from the following sources, select the phone source(s) to be blocked from receiving Voice OTPs or SMS / Text OTPs

  • Cellular Telephones – Mobile / wireless phone numbers
  • Landlines – Phone numbers of home / office wired lines
  • IP Phones – Virtual phone numbers, also known as DID or access numbers, without a directly associated phone line
  • Toll-free Numbers – Phone numbers with the following area codes: 800, 888, 877, 866, 855 or 844
  • Premium Rate Numbers – Phone numbers or phone calls in which certain services are provided and part of the charges are paid to the service provider
  • Pagers – Phone numbers of call devices that can only receive messages
  • Unknown – Phone number of an anonymous classification

Block Phone Numbers that Recently Changed Carriers


4. Enable the Block phone numbers that have recently changed carriers feature to prevent newly ported phone numbers from receiving Voice OTPs or SMS / Text OTPs

5. (OPTIONAL) If the feature in step 4 is enabled, selecting the option to Allow users to approve or delete a phone number that has recently changed carriers lets end-users accept or remove a newly ported phone number from the multi-factor methods page during authentication

6. Specify the Property in which to Store carrier information in by making a selection from the dropdown – e.g. Aux ID 2

Select the Property mapped to the data store, defined in step 1

If using the Authentication API, this is the Property that stores the originalCarrier information

Click Save once the configuration is complete and before leaving the Multi-Factor Methods page to avoid losing changes

Block or Allow Phone Numbers by Carrier / Country


7. In Block or allow phone numbers by carrier or country, select Enable block / allow list to deny / permit Voice OTPs or SMS / Text OTPs to be received by phone numbers from carriers / countries specified on the activated block and allowed lists

8. Click Define list of blocked / allowed numbers and carriers to configure the block and allowed lists

Block or Allow Countries / Carriers


9. On the Block or Allow Countries / Carriers page, indicate whether to Block or Allow numbers of specified countries or carriers

Based on the radio button selection, the heading toggles between Blocked Countries / Carriers and Allowed Countries / Carriers – only one of these two options can be applied

10. Click Add country / carrier

Block or Allow Countries / Carriers


11. In the Find and select countries / carriers box, type in characters of the country / carrier name to block / allow

A filtered list of items appears based on the input – items are organized by country name and carrier names within the country

12. Make the selection(s) from the list of countries and carriers that appears on the picker box below

A selection can be removed from the list by unchecking the box

13. Click Close after all selections are made


14. The list appears with the following information

The name of the latest added country appears at the top of the list – each added carrier name appears as a separate "blue" entry

The name of the latest added carrier in a listed country appears as a new "blue" entry at the end of the country's list

To remove a listed country

Click the X to the right of the country name to remove the country and all carriers listed for that country

To remove a listed carrier

Click the X at the end of the carrier name to remove the selected carrier

Click Save once the configuration is complete and before leaving the Block or Allow Countries / Carriers page to avoid losing changes

Results of Block or Allow Countries / Carriers after Save


Once saved, the name of each added carrier selection appears "gray" for the given country

NOTE: Countries / carriers can be removed from the list, and the list re-saved

After clicking Save, click Back to return to the Multi-Factor Methods page

Endpoints

Endpoints for /numberprofile are used on demand to view an end-user's phone number profile and update the record if information such as carrier, network, and / or country has changed

The POST method retrieves the phone profile record from the data provider which includes the original carrier information

The PUT method is used to update the directory to reflect the phone carrier information

After the information is added, a subsequent POST call retrieves the stored carrier information from the directory and the current carrier information from the data provider

If a discrepancy exists between the original carrier information and current carrier information, a PUT call is made to update the phone profile record

POST
HTTP MethodURIExample
POST
/api/v1/numberprofile
https://secureauth.company.com/secureauth2/api/v1/numberprofile
Definitions
  • user_id: User ID provided
  • phone_number: User phone number provided
  • status: State of the user ID or phone number provided (not_found, invalid, valid)
  • message: Additional information regarding the status of the user ID or phone number; will always be in response
  • providerRequestId: Unique reference identification number for the request, generated by the data provider
  • portedStatus: User phone status for the option to block phone numbers that recently changed carriers (not_ported, ported)
  • originalCarrier: The first time a POST call is made, user phone profile information from the data provider information appears here – on subsequent POST calls, user phone profile information stored in the directory appears here
  • currentCarrier: Following a PUT call and a subsequent POST call, user phone profile information from the data provider appears here
  • carrierCode: 6-digit number or a concatenation of the country code and phone type
  • carrier: Name of the carrier or a concatenation of the country code and phone type
  • countryCode: 2-character country code
  • networkType: Phone connection source (landline, tollfree, mobile, virtual, unknown, landline_tollfree)
  • carrierStatus:
    • status: State of the carrier (blocked, allowed) based on the configuration defined in the Web Admin
    • reason: Explanation for the state of the carrier (network_type, ported, country, carrier) based on the configuration defined in the Web Admin
POST Endpoint JSON Parameters and Response Examples
JSON ParametersSuccess Response
(Phone profile is returned with this response)
Fail / Error Response
(Phone profile is not returned with this response)
{
  "user_id": "<USERNAME>",
  "phone_number": "<PHONE NO.>"
}

Example:

{
  "user_id": "jsmith",
  "phone_number": "19491234567"
}
{
"numberProfileResult": {
"providerRequestId": "01eda1b2-d47c-4290-b1ca-6de8b2573836",
"internationalFormat": "19491234567",
"nationalFormat": "(949) 123-4567",
"countryPrefix": "1",
"countryCode": "US",
"countryCodeISO3": "USA",
"country": "United States of America",
"portedStatus": "not_ported",
"validNumber": null,
"reachable": null,
"roamingInfo": null,
"currentCarrier": {
"carrierCode": "US-FIXED",
"carrier": "United States of America Landline",
"countryCode": "US",
"networkType": "landline",
"carrierStatus": {
"status": "blocked",
"reason": [
"networkType"
]
}
},
"originalCarrier": {
"carrierCode": "US-FIXED",
"carrier": "T-mobile USA, Inc.",
"countryCode": "US",
"networkType": "mobile",
"carrierStatus": {
"status": "allowed",
"reason": null
}
},
"ipInfo": null,
"ipWarning": null
},
"status": "valid",
"message": ""
}
{
"status": "not_found",
"message": "User Id was not found."
}
HTTP Status 200 (OK - Non-existing user)
{
"status": "not_found",
"message": "The requested resource cannot be found."
}
HTTP Status 404 (Not Found - Non-existing endpoint)
{
"status": "invalid",
"message": "Request validation failed with: PhoneNumber was not present."
}
HTTP Status 400 (Bad Request - Missing phone number)
{
"status": "valid",
"message": ""
}
HTTP Status 200 (OK - Invalid phone number)
{
"status": "not_found",
"message": "The requested resource cannot be found."
}
HTTP Status 404 (Not Found - Non-existing endpoint)
PUT
HTTP MethodURIExample
PUT
/api/v1/numberprofile
https://secureauth.company.com/secureauth2/api/v1/numberprofile
Definitions
  • user_id: User ID provided
  • phone_number: User phone number provided
  • status: State of the user ID or phone number provided (not_found, invalid, valid)
  • message: Additional information regarding the status of the user ID or phone number; will always be in response
  • portedStatus: User phone status for the option to block phone numbers that recently changed carriers (not_ported, ported)
  • carrierCode: 6-digit number or a concatenation of the country code and phone type
  • carrier: Name of the carrier or a concatenation of the country code and phone type
  • countryCode: 2-character country code
  • networkType: Phone connection source (landline, tollfree, mobile, virtual, unknown, landline_tollfree)
PUT Endpoint JSON Parameters and Response Examples
JSON ParametersSuccess Response
(Phone profile is returned with this response) 
Fail / Error Response
(Phone profile is not returned with this response) 
{
  "user_id": "<USERNAME>",
  "phone_number": "<PHONE NO.>",
  "portedStatus": "not_ported",
     "carrierInfo": {
         "carrierCode": "<6-DIGIT NO. OR COUNTRY CODE + PHONE TYPE>",
         "carrier": "<CARRIER NAME OR COUNTRY CODE + PHONE TYPE",
         "countryCode": "<2-CHARACTER COUNTRY CODE>",
         "networkType": "<TYPE OF NETWORK CONNECTION>"
     }
}

Example:

{
  "user_id": "jsmith",
  "phone_number": "19491234567",
  "portedStatus":"not_ported",
     "carrierInfo": {
         "carrierCode": "US-FIXED",
         "carrier": "T-mobile USA, Inc.", 
         "countryCode": "US",
         "networkType": "mobile"
     }
}
{
"status": "valid",
"message": ""
}
HTTP Status 200 (OK - Successful PUT)
{
"status": "not_found",
"message": "User Id was not found."
}
HTTP Status 200 (OK - Non-existing user)
{
"status": "not_found",
"message": "The requested resource cannot be found."
}
HTTP Status 404 (Not Found - Non-existing endpoint)
{
"status": "invalid",
"message": "Request validation failed with: PhoneNumber was not present."
}
HTTP Status 400 (Bad Request - Missing phone number)
{
"status": "valid",
"message": ""
}
HTTP Status 200 (OK - Invalid phone number)
{
"status": "not_found",
"message": "The requested resource cannot be found."
}
HTTP Status 404 (Not Found - Non-existing endpoint)