Skip to main content

Phone Profiling Service authentication API guide

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

  • Complete the steps in the Authentication API guide

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

    For more information, see Phone number profiling service configuration

Identity Platform Web Admin configuration

Before you can configure the Endpoints, configure the Phone Profiling Service in the Identity Platform Advanced Settings (formerly Classic Experience).

To use the Block Phone Numbers that Recently Changed Carriers feature, it requires you to complete these steps.

  1. Go to the Data tab.

    43981467.png
  2. Map the Aux ID 2 profile Property to a directory field that meets these requirements:

    For example, if it is not used, you can use accountNameHistory.

    • Directory String with syntax: 2.5.5.12

    • Upper Range of at least 4096

    • Multi-valued set to true

  3. Select the Writable check box for Aux ID 2.

  4. Save your changes.

  5. Go to the Multi-Factor Methods tab.

  6. In the Registration Configuration section, make the following configurations for Phone Number Blocking.

    Note

    The phone number blocking configuration only applies to this realm.

    43981169.png

    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

    43981470.png

    Block phone numbers that recently changed carriers

    Enable this feature to prevent newly ported phone numbers from receiving Voice OTPs or SMS / Text OTPs.

    Optional. If you enable this feature, then selecting the Allow users to approve or delete a phone number that has recently changed carriers check box lets end-users accept or remove a newly ported phone number from the multi-factor methods page during authentication.

    Set the property in which to Store carrier information in. For example, Aux ID 2.

    Note

    Select the property mapped to the data store, defined in Step 2.

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

    43981471.png

    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.

    To configure block and allowed lists, click the Define list of blocked / allowed numbers and carriers link.

    43981472.png

    Block or Allow Countries / Carriers

    1. Select whether to Block or Allow numbers of specified countries or carriers.

      43981466.png
    2. To add or remove countries and carriers, click the Add country/carrier button.

    3. Start typing in the find and select search box to display a filtered list.

      Names are organized by country name, and the carrier name within the country.

      43981473.png
    4. Select or clear the check boxes in the results list.

    5. After you make your selections, click Close.

      Each new country or carrier is displayed as a blue entry.

      43981475.png

      Tip

      To remove a listed country (and all carriers): Click the X to the right of the country name.

      To remove a listed carrier: Click the X at the end of the carrier name.

  7. Save your changes.

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 Method

URI

Example

POST

/api/v1/numberprofile

https://secureauth.company.com/secureauth2/api/v1/numberprofile

PUT

HTTP Method

URI

Example

PUT

/api/v1/numberprofile

https://secureauth.company.com/secureauth2/api/v1/numberprofile