Configure and use telephony
As described in Basic use cases for telephony, there are several common scenarios for using SMS messages or voice calls as part of authentication policies or account recovery. Most often, you configure telephony options as part of setting up sign-in or multifactor authentication policies. However, there are a few special considerations and use cases that are specific to using SMS or voice calls that are not covered in the more general documentation for setting up policies or viewing events.
The following topics describe how to perform common telephony-related tasks:
Enable SMS or voice for account recovery
The default password policy for Okta users enables users to reset their account password or unlock their account by clicking a link in an email message sent to their primary and secondary email addresses. You can modify the default password policy or add a new password policy to enable users to receive an SMS text message or a voice call to reset their password or unlock their account. In most cases, you should add a new password policy to allow SMS text messages or voice calls to be used to reset passwords or unlock accounts because the default password policy has the lowest priority.
If you choose to enable SMS or voice for account recovery, be aware that these services are not supported for all countries and that there are costs associated with using SMS or voice. The costs can vary widely depending on the telecommunication services available in the countries where calls are placed.
For information about adding a Password Authenticator with a default policy rule in Okta Identity Engine, see Configure the Password authenticator.
Configure SMS or voice for multifactor authentication
You can configure a phone as an authenticator to use SMS or voice messages for multifactor authentication, device enrollment, and recovery or to only allow the use of SMS or voice for account recovery. When you configure the phone as an authenticator, you can choose to enable only SMS text codes, only voice calls, or to allow both.
Toll-free, premium, and invalid phone numbers cannot be used for multifactor authentication or device enrollment. If you attempt to use a toll-free, premium, or unrecognized phone number format, the phone number will be rejected as an invalid phone number.
Costs and availability
If you choose to enable SMS or voice for account recovery, be aware that these services are not supported for all countries and that there are costs associated with using SMS or voice. The costs can vary widely depending on the telecommunication services available in the countries where calls are placed.
Service protection and reliability
If you enable SMS for multifactor authentication, users authenticate by entering a security token that is sent to their mobile device. The sender ID or phone number that appears on the devices can be a short code, a long code, or a toll free number. The sender ID can change without notice to ensure service protection and might change from one sign-in attempt to another. Changes to the sender ID allow Okta to maintain service reliability, adjust the routing of messages to telecommunication providers, and provide a more consistent delivery rate for different destinations.
To set up multifactor authentication to use SMS text codes or voice messages:
- In the Admin Console, go to Security > Authenticators.
-
If Phone is listed as an authenticator on the Setup tab, continue to the next step.
If Phone is not listed as an authenticator, click Add Authenticator and follow the steps in About MFA authenticators to add it.
-
Under Actions, click Edit.
-
Configure the settings for phone-based authentication as described in Configure the Phone authenticator.
Note that SMS and voice are not supported for all countries. You can find the countries that support SMS text messaging, voice messages, or both by contacting Okta Support.
In addition, be aware that there are costs associated with using SMS or voice and the costs can vary widely depending on the telecommunication services available in the countries where calls are placed. If your organization supports an international workforce or international customers, you should check for any regulatory requirements in the countries where you have workers or customers.
-
Configure one or more Okta sign-on policy rules to include primary and secondary factors for authentication as described in Add a global session policy rule and Create an authentication enrollment policy.
For more information about adding authenticators and configuring sign-on policy rules, see the following topics:
Customize SMS message templates
You can customize your organization's SMS messages by modifying the default message template or by localizing the message. In addition, some countries require that SMS messages include branding information or comply with specific regulatory requirements. See Customize an SMS message.
Before you customize the default SMS message template, consider the following:
-
The languages you need to support
-
The character set required for the languages you support
-
The maximum number of characters allowed for a single SMS message
Character set limitations
Most telecommunication providers encode SMS messages using the GSM-7 character set. The GSM-7 character set supports the most commonly used letters and symbols in many languages that use the Latin-based alphabet, such as English, Spanish, and French. Because SMS messages are transmitted 140 8-bit octets at a time, messages that are encoded using the GSM-7 character set can contain a maximum of 160 characters. If a message cannot be encoded using the GSM-7 character set—for example, because the message uses a non-Latin based alphabet languages such as Arabic, Chinese, or Cyrillic—it is typically encoded using UCS-2. With UCS-2 encoding, the maximum message length is 70 characters.
Message segments and delivery
Okta supports sending SMS messages that use GSM and non-GSM character sets. However, the character set you use affects both the maximum number of characters you can use per message and how messages are broken down into segments and delivered. For example, if you send SMS messages using the standard GSM character set, the character limit for a single SMS segment is 160 characters. If the SMS message is over 160 characters, the message is split into segments with a maximum of 153 characters. The segments are sent individually then assembled by the recipient endpoint. If your message consists of 161 characters, it is sent as two separate messages—one with 153 characters and another with 8 characters—and counted as if you had sent two 160 character messages.
Messages that have non-GSM characters are limited to 70 characters for a single SMS segment. Not all phones or mobile networks support non-GSM characters and only a few carriers support concatenation of the 70 character segments, with a maximum of 67 characters that can be used for the SMS message. If the SMS segment exceeds the 70 character limit, it is treated as multiple messages.
Validation for custom message templates
If you customize the default SMS message template, the Admin Console checks the message to determine whether it contains GSM or non-GSM characters and enforces the GSM or non-GSM character limit before saving the message. This check ensures that you don't create custom SMS messages that exceed the GSM or non-GSM character limit for message segments.
The character set validation is not performed for custom SMS message templates that you might have previously created. However, if you change existing custom templates, the new restrictions are enforced if your messages contain non-GSM characters.
If you have existing SMS templates that you aren't planning to update, it can be difficult to determine whether they contain non-GSM characters. If you have existing custom SMS message templates and you aren't sure whether they contain GSM or non-GSM characters, try entering the text in an online tool that can evaluate the characters used.
View or query SMS or voice call events
You can use the System Log to view or query for SMS or voice call events.
For example, you can use the System Log to view details about when an SMS message was sent to verify a phone as an authenticator or if verification was successful:
You can expand these events to view additional details about activity. For example, if an SMS message was successfully delivered to its destination, you can see details similar to the following:
You can also use the System Log to filter and query for a specific provider status. For example:
There are several scenarios that can cause SMS messages or voice calls to fail.
For example, authentication requests might fail for any of the following reasons:
- A telephony provider can’t be reached
- The phone number used is incorrect or inactive
- The service requested is not available in the country where the request was made
- A request for verification has timed out
- A number has been blocked because of suspicious activity
SMS event types
The System Log records the following events for SMS messages:
| Event | Description |
|---|---|
| system.sms.receive_status | Recorded when a status update for an SMS messages has been received from a service provider. You can use this event to identify users who aren't getting one-time passcodes delivered successfully. For any system.sms.send_* event, there should be exactly one corresponding system.sms.receive_status event. |
| system.sms.send_account_unlock_message | Recorded when a self-service account unlock SMS message has been sent. |
| system.sms.send_factor_verify_message | Recorded when a second factor authentication has been sent as an SMS text message. |
| system.sms.send_okta_push_verify_message | Recorded when a request to activate Okta Verify Push for mobile SMS message has been sent. |
| system.sms.send_password_reset_message | Recorded when a self-service password reset SMS message has been sent. |
| system.sms.send_phone_verification_message | Recorded when a phone verification SMS message has been sent. |
For additional information about the System Log API and SMS event types, see Event Types in the Okta developer documentation and type sms in the search field.
Voice event types
The System Log records the following events for voice messages:
| Event | Description |
|---|---|
| system.voice.receive_status | Recorded when a status update for a voice messages has been received from a service provider. You can use this event to identify users who aren't getting one-time passcodes delivered successfully. For any system.voice.send_* event, there should be exactly one corresponding system.voice.receive_status event. |
| system.voice.send_account_unlock_call | Recorded when a self-service account unlock voice call has been sent. |
| system.voice.send_call | Recorded when a voice call has been sent. |
| system.voice.send_mfa_challenge_call | Recorded when a second factor authentication has been sent as a voice call. |
| system.voice.send_password_reset_call | Recorded when a self-service password reset voice call has been sent. |
| system.voice.send_phone_verification_call | Recorded when a phone verification voice call has been sent. |
For additional information about the System Log API and voice event types, see Event Types in the Okta developer documentation and type voice in the search field.
View the SMS usage report
You can see details about the number of domestic and international SMS messages being sent on a monthly basis for users in your organization. The report includes a breakdown of the SMS messages sent for different purposes so you can see patterns of user behavior and whether SMS messages are being used for enrollment, sign-in requests, password resets, or unlocking accounts.
Select a language for voice-based authentication
Individual users can select the language used for the voice message they receive to verify their identity. To select a language, users click Settings in the My Apps end-user dashboard. After they click Edit Profile to validate their credentials, they can edit the Display Language setting to select the language used for voice-based authentication and recovery. If they authenticate using a phone call after changing the language setting, they will hear the voice message in their selected language.
For more information about modifying user settings, see End-user settings or direct your user community to Select your display language.