Configure and use telephony
You can configure SMS messages or voice calls as part of authentication policies or account recovery. This topic describes how to enable SMS messages or voice calls, customize SMS messages, and monitor usage using the System Log and reports.
If you're configuring telephony for the first time for your org, you must first set up an external telephony service provider. See Connect to an external telephony service provider.
Enable SMS messages or voice for account recovery
The default password policy enables Okta users to reset their account password or unlock their account using an email link. You can modify this policy to enable users to receive an SMS messages or a voice call to reset their password or unlock their account. Okta recommends adding another password policy to the same effect and place it at a higher priority.
For information about adding a password authenticator with a default policy rule, see Configure the password authenticator.
Configure SMS messages or voice for multifactor authentication
You can configure a phone as an authenticator to use SMS messages or voice messages for multifactor authentication, device enrollment, and recovery. Or you can only allow the use of SMS messages or voice for account recovery. When you configure the phone as an authenticator, you can choose to enable only SMS messages text codes, only voice calls, or to allow both.
Toll-free, premium, and invalid phone numbers can't 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 is rejected as an invalid phone number.
Costs and availability
If you enable SMS messages or voice for account recovery, be aware that 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 messages 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 messages or voice calls:
- In the Admin Console, go to .
-
If Phone is listed as an authenticator on the Setup tab, continue to the next step.
If Phone isn't listed as an authenticator, click Add Authenticator and follow the steps in any authenticator topic to add it. See Multifactor authentication for a list of authenticators.
-
Under Actions, click Edit.
-
Configure the settings for phone-based authentication as described in Configure the phone authenticator.
-
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 authenticator enrollment policy.
For more information about adding authenticators and configuring sign-on policy rules, see the following topics:
Customize SMS messages templates
You can customize the SMS messages by modifying the default message template or by localizing the message. In addition, some countries require that the SMS messages include branding information or comply with specific regulatory requirements. See Customize an SMS message.
Before you customize the default SMS messages template, consider the following:
-
The languages you need to support
-
The character set required for the languages that you support
-
The maximum number of characters allowed for a single SMS messages
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 the SMS messages is 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 can't be encoded using the GSM-7 character set, it's typically encoded using UCS-2. Examples include messages in a non-Latin-based alphabet language such as Arabic, Chinese, or Cyrillic. 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 message 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 and then assembled by the recipient endpoint. If your message consists of 161 characters, it's sent as two separate messages. The first with 153 characters and the second with 8 characters. It's counted as two 160-character messages.
Messages that have non-GSM characters are limited to 70 characters for a single SMS message segment. Not all phones or mobile networks support non-GSM characters. Only a few carriers support concatenation of the 70 character segments, with a maximum of 67 characters that can be used for SMS messages. If the SMS message segment exceeds the 70 character limit, it's treated as multiple messages.
Validation for custom message templates
For a customized SMS message template, Okta checks the message to determine whether it contains GSM or non-GSM characters and enforces the corresponding character limit before saving it. This check ensures that your custom SMS messages follow the character limit for message segments.
The character set validation isn't 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 message templates that you aren't planning to update, it can be difficult to determine whether they contain non-GSM characters. Try entering such texts in an online tool that can evaluate the characters used.
View or query SMS messages or voice call events
You can use the System Log to view or query for SMS messages 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 the 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 isn't 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 message 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 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 message 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 voice call for self-service password reset has been sent. |
| system.voice.send_phone_verification_call | Recorded when a voice call for phone verification 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 domestic and international SMS messages sent in a month for users in your organization. Use this report to identify patterns of user behavior and whether the SMS message is 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 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 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.