How to Set Up the Vonage Protection Suite for Okta

Introduction

When a user needs to verify their identity in Okta, Okta generates a one-time password (OTP). However, Okta doesn’t send the OTP directly. Instead, it relies on external providers to deliver the OTPs to users. The Vonage Protection Suite for Okta serves this purpose by delivering a managed, plug-and-play connector for SMS and Voice OTP delivery. It integrates directly into your Okta Identity Engine via Telephony Inline Hooks and delivers OTPs through Vonage Verify via SMS or voice calls. The connector is built on Vonage Cloud Runtime (VCR).

Supported Okta Platforms

The Vonage Protection Suite for Okta integrates via Okta's Telephony Inline Hook, which is available in Okta Workforce Identity Cloud, including both the Okta Identity Engine (OIE) and the legacy Classic Engine. Auth0 (Okta Customer Identity Cloud) is not supported in this release. Auth0 uses a different extensibility model (Actions/custom credential providers) rather than Telephony Inline Hook, and requires a separate integration.

Two-Layer Fraud Intelligence Model

The Vonage Protection Suite for Okta uses a two-layer fraud intelligence model:

• Identity Insights Pre-OTP Number Verification (optional): Screens number against carrier databases (validity, carrier) and blocks fraud before OTP delivery is initiated. This is a passive intelligence layer as it doesn't require any action from the end user.
• Layer 2 Fraud Defender During OTP: SMS pumping protection, geographic permissions, velocity controls, and rate limiting.

In this guide, you will connect your Okta tenant to Vonage Verify using the Vonage Protection Suite for Okta, ensuring that OTPs are delivered via SMS or voice.

Connector Flow

The following diagram shows how the connector sits between Okta and Vonage Verify:

Prerequisites

Before you begin, make sure you have the following:

• An active Okta tenant with Okta Identity Engine (OIE).
• Phone authenticator enabled in Okta (Okta Admin Console > Security > Authenticators > Setup > Phone).
• Admin access to the Okta Admin Console to configure Inline Hooks and Event Hooks.
• A Vonage API account (you can sign up for free) along with an API Key (you can find these credentials in your API settings within the Vonage Dashboard).
• Access to the Vonage Dashboard.
• A Vonage Cloud Runtime Advanced subscription. If you don't have one, contact your Vonage Customer Success Associate (CSA) to activate it.

Deploy the Connector on Vonage Cloud Runtime

1. Log into Vonage Cloud Runtime and click on the Vonage Protection Suite for Okta tile.
2. In the menu on the right, select the API Key you want to deploy the connector against. If your account has only one API key, this step is skipped automatically.
3. Click Deploy a new instance.

4. In the Connector Configuration Type, select Standard and click Continue.

5. Fill in the parameters:
   • Region: Region where your entity will be hosted.
   • Instance name: Unique name to your instance.
   • Vonage Number (Optional): This number serves as the SMS sender ID and must be in E.164 format, consisting of digits only (an international number without the "+" sign). If this number is not configured, the Brand Name specified below will be used instead. Note that this value does not apply to voice calls, as the caller number is randomly selected by Vonage Verify.
   • Brand Name (Mandatory): The OTP message body will use this brand name in SMS. This value is ignored for voice calls. Instead, the caller number is randomly selected by Vonage Verify as suitable for the destination region.
   • Voice Call Fallback (Mandatory): When it’s enabled, the connector will automatically attempt to make a voice call if the SMS delivery fails.

6. Click Continue to deploy the instance.

Configure the Connector

Launch the Admin Application

After deploying the instance, launch the connector’s Admin Application. It allows you to configure security policies and generate authentication tokens. To do that, follow the below steps:

1. Select the previously created instance and click the Launch button.

2. Authenticate with Vonage credentials by clicking the Verify Identity with Vonage button.

Review the Dashboard Tab

After launching the connector’s Admin Application, you're redirected to the Dashboard tab. It provides real-time visibility into the delivery of OTPs and authentication activity.

The Dashboard tab presents the following data:

• Counters section presents the following metrics:
  • Total SMS: The overall number of SMS delivery tries (both successful and unsuccessful).
  • SMS Success: The count of SMS deliveries that were successfully completed.
  • SMS Blocked: The number of SMS deliveries that were blocked by Identity Insights or Fraud Defender.
  • Total Voice: The total of voice delivery attempts (both successful and unsuccessful).
  • Voice Success: The total number of voice deliveries that were successfully completed.
  • Voice Blocked: The number of voice deliveries that were blocked.
• Recent OTP Activity shows the most recent 10 OTP delivery attempts for all tokens:
  • Timestamp: When the delivery attempt was made.
  • Destination: The masked phone number.
  • Channel: SMS/VOICE.
  • Status: SUCCESS, FAILED, or FLAGGED (amber, for flag-and-deliver).
  • Description: Click the eye icon to see the complete reason for failure or flagging.
  • Latency: Duration taken to complete the delivery in milliseconds.
  • Token: The shortened token identifier.
• Recent Auth Events shows the most recent 10 authentication events obtained from Okta:
  • Timestamp: Indicates when the event was published
  • Token: The shortened identifier for the token.
  • Event: The type of Okta event (e.g., user.authentication.auth_via_mfa).
  • Factor: The authentication factor used (e.g., SMS_FACTOR, CONVERSION).
  • Outcome: SUCCESS, FAILURE, or UNKNOWN.
  • User: The Okta actor ID.
  • Request: The ID associated with the authentication request.
• Token List: The dashboard shows all created tokens along with their current status:
  • Active: The token is currently valid and being utilized.
  • Grace Period: A newer token has taken the place of this one, and both tokens work simultaneously for a 24-hour transition period.
  • Expired: The token has exceeded its expiration date.
  • Revoked: The token has been manually deactivated and is no longer usable.
• Rotating a token creates a new token that possesses the same security claims as the original. The original token enters a 24-hour grace period where both tokens are acceptable. Use token rotation to regularly refresh cycle credentials without experiencing any service interruption.
• Revoking a token instantly deactivates it. This action should be taken if a token has been compromised or is no longer required. The effect of revocation is immediate and cannot be undone.

Generate Token Tab

Now, navigate to the Create Token tab, where you can configure security policies and generate a token. This token serves to authenticate communications between Okta and the connector. Additionally, it encodes the security policies that are applicable to each OTP delivery carried out using that token.

Layer 1: Identity Insights Pre-OTP Number Verification (optional)

The connector's two-layer security model starts with the optional Identity Insights Pre-OTP Number Verification.

Identity Insights is a Vonage API that gives you real-time access to mobile operator databases. It helps you assess the risk level of a phone number. In the connector, it acts as a screening tool before sending an OTP. The connector uses the results of these checks, which you can set up as you wish.

1. To enable the Identity Insights functionality, set the toggle to ON.
2. Select checks you want to enforce:
   • Number Format & Validity (free): Confirms if the number is a valid mobile number, and automatically flags VoIP and virtual numbers.
   • Original Carrier Lookup (charged per request): Identifies the network and line type assigned when this number was first issued. Useful for screening numbers registered as VoIP from the start. Will not catch a mobile number later ported to VoIP.
     • Network Type Filter: Numbers on unselected network types will be flagged.
   • Current Carrier Lookup (charged per request): Identifies the network and live line type currently serving this number, including any changes from porting.
3. Geographic and Channel Filters: These filters restrict OTP delivery based on the geographic or network characteristics of the phone number.
   • Country Allowlist: Provide ISO 3166-1 alpha-2 country codes (e.g., US, GB, DE). Only numbers associated with these countries will be permitted. Keep it empty to allow all countries.
4. Choose which action to take if a destination number is flagged during verification checks:
   • Block OTP: OTP is not delivered. You can view the failure reason in the Dashboard Tab > Recent OTP Activity > Description.
   • Flag & Deliver: The OTP is delivered but flagged amber in the dashboard for further review. Use when you want visibility without blocking potentially legitimate users. You can view the status in the Dashboard Tab > Recent OTP Activity > Status.
   • Log Only: The check result is logged, but no further action is taken. No flag is attached. Useful during initial rollout to understand your flag rate before committing to a block or flag policy. The OTP will be sent as usual. There will be no information visible in the Dashboard tab.

Layer 2: Fraud Defender During OTP

When a number successfully passes the Layer 1 checks (or if Identity Insights is disabled), the OTP is sent to Vonage Verify for delivery. At this stage, Fraud Defender takes over as an additional layer of protection.

Fraud Defender safeguards against SMS pumping, artificially inflated traffic (AIT), and traffic burst attacks. No action is needed to activate this feature. It is automatically applied to all OTP traffic processed through Vonage Verify.

Tier Selection

In the connector's configuration panel, Fraud Defender Advanced shows as Included, and is available at no additional cost for all Verify traffic. If you require Fraud Defender Premium, contact your Vonage Account Manager to enable it.

Rate Limit

Set a maximum number of OTP requests per phone number within a 10-minute window. The default is 5 requests. This protects against repeated OTP requests targeting the same number. This functionality can be disabled if not needed.

Delivery

Brand name: The brand name shown to recipients in the OTP message. Overrides the global brand name configured on the server.
SMS to Voice Fallback: Automatically retries via voice call if SMS delivery fails. This functionality can be disabled if not needed.

Token Expiration

Select the validity period for the token you are about to generate: 24 hours, 7 days, 30 days, 90 days (default), or Never. Shorter expiration periods improve security but require more frequent rotation. The token embeds your current country network, and phone number configuration.

Record the Generated Token Details

Once the security policies have been set up and the token has been produced, make sure to record the generated token details. The token details will not be shown again, and this information is essential for the Okta setup in the Configure Okta step:

• Telephony Webhook URL
• Event Webhook URL
• Auth Header Name
• Token Secret

Configure Okta

After deploying the connector and generating the token, it’s time to set up Telephony Inline Hook and Event Hook in the Okta Admin Console with webhook URLs and token.

Configure the Telephony Inline Hook

Now, follow the below steps to configure the Telephony Inline Hook:

1. Log into your Okta Admin Console.
2. Navigate to Workflow > Inline Hooks. Click the Add Inline Hook, then select Telephony.

3. Fill in the hook details:

• Name: Enter a name (e.g., "Vonage OTP").
• URL: Paste the Telephony Webhook URL from the generated token details.
• Authentication field: Paste the Auth Header Name from the generated token details.
• Authentication secret: Paste the Token Secret from the generated token details.

4. Click Save.

Configure the Event Hook

Next, follow the below steps to configure the Event Hook:

1. Navigate to Workflow > Event Hooks.

2. Click the Create event Hook.
3. Fill in the hook details:

• Name: Enter a name (e.g., "Vonage Events").
• URL: Paste the Event Webhook URL from the generated token details.
• Authentication field: Paste the Auth Header Name from the generated token details.
• Authentication secret: Paste the Token Secret from the generated token details.

4. The Requests section defines the requests that Okta will send to the endpoint. Subscribe to the Authentication of user via MFA event.
5. Click Save & Continue.

Verify Connectivity

Now, it’s time to verify that the connection between Okta and the connector is active. To do that, we need to confirm both hooks show Active & Verified status in Okta Admin Console:

1. Click the Verify button on the Verify Endpoint Ownership pop up that appears right after creating the Event Hook.

Test the Integration

You can test the integration using Okta's built-in preview tool following the steps:

1. In the Okta Admin Console, navigate to Security > Authenticators > Setup > Phone to ensure that phone authentication is enabled in your Okta.
2. Run the preview test:
   • Navigate to Workflow > Inline Hooks.
   • Find the telephony inline hook you created and click Actions > Preview.
   • In Configure inline hook request:
     • Enter a test user’s information: data.userProfile (a user who has a phone as a valid authenticator).
     • Select requestType (MFA enrollment, MFA verification, Account unlock, or Password reset).
   • Click Generate request to build the JSON payload.
   • Click Edit to modify the request if needed.
   • Replace the default phone number (9876543210) with a real mobile number in E.164 format (e.g., +447700900000).
   • Click View response to trigger the hook. A successful response will show status: SUCCESSFUL with the delivery duration.

Troubleshooting

Quick Checks

Before tracing the full flow, verify the following:

Credentials: Confirm that the Telephony Webhook URL, Event Webhook URL, Auth Header Name, and Token Secret in Okta exactly match the values from the token generation details.

Hook status: In the Okta Admin Console, navigate to Workflow > Inline Hooks and confirm the hook status is Active and Verified.

Dashboard: Check the connector's Dashboard tab for recent OTP activity. Look for FAILED or FLAGGED events and click the description icon for error details.

Identity Insights: If OTPs are being blocked, check whether Identity Insights is flagging the destination number. Consider adjusting the When number is flagged action to Block > Flag and Deliver or Only Log for testing.

Phone authenticator: Confirm phone authentication is enabled in Okta: Okta Admin Console > Security > Authenticators > Setup > Phone.

Trace the Issue Step By Step

If something is not working as expected, trace the issue through the following stages:

1. Okta sends the request: Check the Okta Admin Console > Reports > System Log for the hook call, target URL, and request status.
2. Connector processes the request: Check Vonage Cloud Runtime > Instances > Your Instance > Logs for the incoming request, Identity Insights result, and Verify API call.
3. OTP delivered: Check Vonage Dashboard > Message Logs for message status, channel, sender ID, error codes, and any Fraud Defender blocks.
4. Auth event received: Check Connector Admin Dashboard > Recent Auth Events for event received, event type, factor, outcome, and token match.
5. Conversion recorded: Check Vonage Dashboard > Verify Logs for converted status, conversion fee, and missing conversion.

Connector Error Codes & Identity Insights Sub-Codes

For a full list of connector error codes and Identity Insights sub-codes, see the Vonage Protection Suite for Okta User Guide.

Need Help?

If you are unable to resolve the issue using the Troubleshooting section above, contact Vonage Help Center. When submitting a request, include your API Key (account ID only, not secret), the Inline Hook event ID from the Okta System Log, and any relevant screenshots or logs to help with faster resolution.

Further Reading

• Identity Insights
• Fraud Defender
• Vonage Protection Suite for Okta article (User Guide)
• Verify Analytics and Logs Overview