This article is for MSPs who are using Phone (SMS or Voice) as Okta authenticators in any Okta org. Read more about this change or learn why MSPs should avoid using voice and SMS as authenticators.
NOTE
ZeroTek strongly recommends that MSPs stop using voice and SMS wherever possible and use recommended authenticators instead.
However, if you must continue using voice or SMS, follow the procedures below to switch to a bring-your-own telephony provider model using Okta's telephony inline hook. We offer instructions for SendGrid and Twilio, or you can follow the same process with functionally equivalent service. These configurations support SMS and voice messaging for both MFA and non-MFA use cases, including authentication, account unlock, and password reset.
If you would prefer to have ZeroTek Support manage this for you, email [email protected] to set up a call.
Configuration
The process you will follow includes these stages:
Get SendGrid Account SID and Auth token
Create an inline hook in Okta
Add a phone authenticator in Okta
Create an enrolment policy in Okta
Create an authentication policy in Okta
Test the configuration
Get SendGrid Account SID and Auth token
The steps below assume you are creating a new Twilio account for this integration. If you have an existing Twilio account you want to use, refer to the vendor's documentation on how to retrieve the account SID and Auth token.
Log in to SendGrid and choose Twilio Comms - SMS, Voice & Video from the Options menu.
Complete the welcome questionnaire and click Get Started with Twilio.
From the Account Info panel, copy the values for Account SID and Auth Token and store them securely. You will need these values in the next stage.
Create an inline hook in Okta
Log in to the Okta admin console with sufficient privilege to perform the operations described here.
Navigate to Security>Authenticators and click Add authenticator.
Locate the Phone authenticator and click Add.
Because an inline hook has not been configured, you will be prompted to set one up. Click Open inline hook.
Click Add inline hook, and then click Telephony - Allows provider selection for SMS/Voice.
Provide a name for the inline hook and enter https://console.twilio.com in the URL field.
Under the Authentication section, select OAuth 2.0.
Paste the Twilio Account SID value recorded in the previous section into the Client ID field.
Paste the Twilio Auth Token value recorded in the previous section into the Client Secret field.
Enter https://console.twilio.com as the Token URL.
Click Save.
Add a phone authenticator in Okta
Navigate to Security > Authenticators and click Add authenticator.
Locate the Phone authenticator and click Add.
Enable the SMS checkbox and confirm Authentication and recovery is selected.
Click Add.
Navigate to Directory > Groups and click Add group.
Type a name for the group (for example SMS group).
Assign a test user to the group.
Create an enrollment policy in Okta
Navigate to Security > Authenticators > Enrollment and click Add a policy.
Provide a meaningful name for the policy.
Assign the group you created with the test user to the policy.
Set Password and Phone to Required and disable all other options.
Click Create Policy.
In the Add Rule screen, accept the defaults and click Create rule OR if you are using geofencing:
Specify In Zone for IF User's IP is.
In the Zones field, specify the zones you want to include.
Click Create rule.
Add a rule to use SMS to an authentication policy in Okta
Navigate to Security > Authentication Policies and select the policy you want to update with the voice/SMS rule.
Click Add rule and provide a meaningful name for the rule.
Select the group(s) to which the policy will be applied.
In the THEN area, choose User must authenticate with > Password / Idp + Another factor.
Click Save. You may be prompted to confirm you want to save this rule. If so, click Save anyway.
Assign the rule to Priority 1.
Test the configuration
Log in to the selected test user's dashboard.
Click Set up.
Click Receive a code via SMS.
Once you receive the code, enter it and click Verify.