What is the Onboarding Modal?

Okto’s Onboarding Modal provides a streamlined way to authenticate users by displaying an embeddable flow (via an iframe) without requiring them to leave your React app. Under the hood, the Onboarding Modal can handle multiple authentication flows (Email OTP, Phone OTP, Google OAuth, etc.), and can be customized with brand data, visuals, and theming.

Why Use the Onboarding Modal?

1. No Authentication Flow Management
   Vendors need not work or worry about the authentication flow or the code for it. Okto handles everything on the server side, simplifying the implementation and saving development time.

2. Multi-Auth Support
   The modal can be set up to handle Google Auth, Email OTP, Phone OTP, or your primary authentication of choice.

3. Brand & Theme Customizations
   Pass your branding (title, subtitle, icon) and theming (colors, backgrounds, etc.) to tailor the onboarding experience to your style guidelines.

Typical Flow

Below is a simplified sequence for how the Onboarding Modal works:

1. Trigger the Modal
   Your React app calls showOnboardingModal() from the Okto SDK. This opens a modal containing an iframe.

2. Iframe Initialization
   The iframe loads the Okto environment for your selected BuildType (Sandbox, Staging, or Production).
   It also receives your brand data, theming, and selected primary authentication method.

3. User Authentication
   The user proceeds to completes the steps (e.g., Google login, Email OTP, or Phone OTP). If the flow requires an external token (like Google ID token), the modal can request it from your app via gAuthCb().

4. Auth Success
   Once the user is authenticated, Okto returns the relevant tokens (authToken, refreshToken, etc.) and closes the modal automatically.

Sequence Diagram

Key Points to Remember

• showOnboardingModal() in the SDK is your main entry point to launch the modal.
• You can customize brand data, theming, and the primary auth method (Email, Phone, or Google).
• For Google OAuth, provide a callback (gAuthCb) to exchange the OAuth code for an ID token—or return an ID token directly if you have it.
• On success, your app will have the user’s authToken (and refresh token) stored in Okto’s internal state.

Enabling Google Authentication in the Onboarding Modal

Okto’s Onboarding Modal can integrate with Google Authentication to offer a smooth, single-click login experience. To enable this, you need to configure the gAuthCb callback, which handles the exchange of Google OAuth credentials for an ID token. The specifics depend on your framework/setup:

• React: Typically needs a server-side exchange (Authorization Code Flow).
• Next.js: Can often get an ID token directly using NextAuth or similar, without spinning up a separate backend.

Below, we’ll show both approaches.

npm init -y
npm install express google-auth-library cors dotenv

require("dotenv").config();
const express = require("express");
const { OAuth2Client } = require("google-auth-library");
const cors = require("cors");
 
const app = express();
app.use(cors());
app.use(express.json());
 
const oAuth2Client = new OAuth2Client(
  process.env.CLIENT_ID,
  process.env.CLIENT_SECRET,
  "postmessage"
);
 
app.post("/auth/google", async (req, res) => {
  try {
    const { tokens } = await oAuth2Client.getToken(req.body.code); // Exchange code for tokens
    res.json(tokens);
  } catch (error) {
    console.error("Error exchanging tokens:", error);
    res.status(500).send("Authentication failed");
  }
});
 
app.listen(3001, () => console.log("Backend server is running on port 3001"));

CLIENT_ID=your-google-client-id
CLIENT_SECRET=your-google-client-secret

node okto-gauth-server.js

import React, { useState } from "react";
import { OktoProvider, useOkto, BuildType, AuthType } from "okto-sdk-react";
import { useGoogleLogin } from "@react-oauth/google";
import axios from "axios";
 
const OKTO_CLIENT_API_KEY = process.env.REACT_APP_OKTO_CLIENT_API_KEY;
 
const App = () => {
  const { showOnboardingModal } = useOkto();
  const [authPromise, setAuthPromise] = useState(null);
 
  const googleLogin = useGoogleLogin({
    flow: "auth-code",
    onSuccess: async ({ code }) => {
      try {
        const { data: tokens } = await axios.post("http://localhost:3001/auth/google", { code });
        if (authPromise) {
          authPromise.resolve(tokens.id_token); // Resolve the promise with the ID token
        }
      } catch (error) {
        console.error("Error during token exchange:", error);
        if (authPromise) {
          authPromise.reject(error);
        }
      }
    },
    onError: (error) => {
      console.error("Google Login Error:", error);
      if (authPromise) {
        authPromise.reject(error);
      }
    },
  });
 
  const handleGAuthCb = async () => {
    return new Promise((resolve, reject) => {
      setAuthPromise({ resolve, reject });
      googleLogin(); // Trigger Google login
    });
  };
 
  return (
    <OktoProvider
      apiKey={OKTO_CLIENT_API_KEY}
      buildType={BuildType.SANDBOX}
      gAuthCb={handleGAuthCb}
      primaryAuth={AuthType.GAUTH}
    >
      <button onClick={showOnboardingModal}>Show Onboarding Modal</button>
    </OktoProvider>
  );
};
 
export default App;

Sample Implementation

For a complete working example, refer to the Okto React Template App or the Okto Next.js Starter App.

Common Tips & FAQ

• Securing Secrets: Keep your Google Client Secret in environment variables, never commit it to git.

• Local Development: For React, use localhost:3000 for your front-end and localhost:3001 for your backend. For Next.js, you can do everything on localhost:3000 if using NextAuth.

• Custom Branding: Okto’s brandData allows you to pass title, subtitle, and icon to customize the onboarding modal.

• Primary Auth Method: By default, you can set primaryAuth={AuthType.GAUTH} (Google), AuthType.EMAIL, or AuthType.PHONE. You can also switch it dynamically if needed.