This site requires JavaScript to be enabled
External Customer KB > General > SMS Authentication Factor
SMS Authentication Factor
Article: KB0010574 Published: 08/16/2022 Last modified: 08/16/2022

This doc provides steps to configure SMS security codes as an auth factor for OneLogin. OneLogin uses Twilio as an SMS provider, which sends a code to users that attempt to login.


Administrator Configuration

Follow the the instructions below to configure SMS OTP.

  1. Log in to your Twilio account as an account owner.

  2. Go to the Console dashboard and copy the AccountSID and AuthToken strings. You will also need your Twilio phone number and/or short code. For Twilio Copilot, you need the Message Service ID.

  3. As an account owner, log in to OneLogin and go to Security > Authentication Factors, then select New Auth Factor and OneLogin SMS.

  4. Click on the icon in the small blue circle to upload a Custom Icon for SMS.

    Note: The square icon should be at least 96 x 96 pixels and a transparent image in PNG or SVG format.

  5. In Use the phone number in field, select the correct user field to store the phone number. The default is User > Phone Number.

  6. In the OTP Timeout field, select the number of minutes that the OTP is valid and choose the OTP Format.

  7. Enter your Twilio AccountSID, Auth Token, and Number or Short code into their respective fields. If using Twilio Copilot, select the radio button for Message Service ID and enter the ID.

  8. Custom SMS Message enables you to customize the SMS message the end user receives. The Custom SMS Message is limited to 160 characters, which includes the OTP code. The message for registration and verification is identical. 

    Note: Contact your account manager to enable Custom SMS Message.

    configure sms for onelogin

  9. Click Save. OneLogin OTP SMS is configured for your account.

Note: If you have created a custom brand through the OneLogin Branding Service and have set it to be your default, then setting a custom SMS message through the GUI as described above will not work. The templates that defined within the custom brand that you have created will take precedence. In order to then create a custom SMS message you will currently have to use the Branding API

Configure End Users

When the MFA policy is applied, the user is prompted to register their phone number to use SMS.

The MFA registration flow supports international number formats. On registering, the registration flow detects a user's IP address and offers an appropriate country code (incl. country flag). The user can also select other country codes, they are not forced into their IP's country code.

Note: Before a user completes the steps below, they should verify the format of their phone number in their OneLogin Profile. If the phone number is incorrectly formatted, the SMS will fail. A user's phone number must contain a Plus ( + ) and country code before their number.  For example, a UK phone number should resemble this format: +4407911123456, rather than 07911 123456. 

An end user can also register their device from their profile. To register a mobile device for SMS password resets, do the following:

  1. Log in to your OneLogin account and go to your profile page.

  2. Under 2-Factor Authentication, click the plus sign "+" to add a factor.

  3. Select OneLogin SMS from the dropdown menu.

  4. Click Send Security Code to mobile. OneLogin sends a security code to the mobile number specified earlier. Input the code received into the Security Code field and click Continue.

  5. Your registered device appears under Authentication Devices in the security page. When you log inUpon logging in, you may be prompted for your SMS Security Code depending on the security settings your admin has configured. Your code is sent automatically to your device and is valid for 120 seconds. Enter the security code and click Log In.


Custom SMS as an authentication factor

The OneLogin API allows organizations to customize the SMS that's sent to users. For more information, see our developer guide on SMS customization.

Expand/Collapse Comments
Was this helpful?