How to Integrate Bolt.new with Okta

Start at developer.okta.com and sign up for a free Developer Edition account. Once logged in, you land in the Okta Admin Console. Navigate to Applications → Applications in the left sidebar and click 'Create App Integration'. In the dialog, select 'OIDC - OpenID Connect' as the sign-in method and 'Single-Page Application' as the application type — this is the correct type for React apps built with Bolt. Click Next. Give your app a name (e.g., 'My Bolt App'). Under 'Sign-in redirect URIs', add your deployment callback URL: `https://your-app.netlify.app/login/callback`. Also add `http://localhost:3000/login/callback` for local development. Under 'Sign-out redirect URIs', add `https://your-app.netlify.app` and `http://localhost:3000`. Under 'Assignments', choose 'Allow everyone in your organization to access' for development. Click Save. Okta creates the app and shows you the Client ID and your Okta Domain on the General tab. Copy both — you'll need them as environment variables. Your Issuer URL will be `https://{yourOktaDomain}/oauth2/default`. This is a public endpoint that identifies your Okta authorization server to the SDK.

In your Bolt project, open the .env file in the root of the project (or create one if it doesn't exist — it's already in .gitignore). Add your Okta credentials as environment variables. For a Vite-based Bolt project, you need the VITE_ prefix to make variables accessible in the browser. For a Next.js Bolt project, use NEXT_PUBLIC_ for client-side values. The Okta Client ID and Issuer URL are not secret values — they're public identifiers visible to anyone using your app — so using the public prefix is correct. The Client ID tells Okta which app is initiating the login; the Issuer URL is the base URL of your Okta authorization server. Never put these in hardcoded strings in your components — always use environment variables so you can swap between development and production Okta apps without changing code. In Bolt's file tree, click the .env file to open it and add the variables shown in the code block. After saving .env, restart the preview if needed for the variables to take effect.

1# .env
2# Okta Developer App credentials
3# Find these in Okta Admin Console → Applications → your app → General tab
4VITE_OKTA_CLIENT_ID=0oaXXXXXXXXXXXXXXXXX
5VITE_OKTA_ISSUER=https://dev-12345678.okta.com/oauth2/default
6
7# For Next.js projects, use NEXT_PUBLIC_ prefix instead:
8# NEXT_PUBLIC_OKTA_CLIENT_ID=0oaXXXXXXXXXXXXXXXXX
9# NEXT_PUBLIC_OKTA_ISSUER=https://dev-12345678.okta.com/oauth2/default
10
11# For server-side token validation only (keep this private, no VITE_ or NEXT_PUBLIC_ prefix):
12# OKTA_AUDIENCE=api://default

With environment variables in place, use the Bolt chat to generate the Okta authentication integration. Bolt installs @okta/okta-react and @okta/okta-auth-js from npm, then generates the OktaAuth configuration object, wraps your app in the Security provider, creates a /login route with a sign-in button that redirects to Okta's hosted sign-in page, creates the /login/callback route component that processes the OAuth redirect and exchanges the authorization code for tokens, and adds a useOktaAuth hook call to any component that needs the user's session. Review the generated src/main.tsx or src/App.tsx — Bolt wraps the router in the Security component from @okta/okta-react, passing the OktaAuth instance. The LoginCallback component from the SDK handles the /login/callback route automatically — it reads the authorization code from the URL, exchanges it for tokens, and redirects the user to the intended destination. The restoreOriginalUri callback tells the SDK where to send the user after login completes.

1// src/auth/oktaConfig.ts
2import { OktaAuth } from '@okta/okta-auth-js';
3
4export const oktaAuth = new OktaAuth({
5  issuer: import.meta.env.VITE_OKTA_ISSUER,
6  clientId: import.meta.env.VITE_OKTA_CLIENT_ID,
7  redirectUri: `${window.location.origin}/login/callback`,
8  scopes: ['openid', 'profile', 'email', 'groups'],
9  pkce: true,
10});
11
12// src/components/RequiredAuth.tsx
13import { useOktaAuth } from '@okta/okta-react';
14import { useEffect } from 'react';
15import { Outlet } from 'react-router-dom';
16
17export function RequiredAuth() {
18  const { oktaAuth, authState } = useOktaAuth();
19
20  useEffect(() => {
21    if (!authState) return;
22    if (!authState.isAuthenticated) {
23      oktaAuth.signInWithRedirect();
24    }
25  }, [authState, oktaAuth]);
26
27  if (!authState || !authState.isAuthenticated) {
28    return <div>Loading...</div>;
29  }
30
31  return <Outlet />;
32}
33
34// src/App.tsx (relevant section)
35import { Security, LoginCallback } from '@okta/okta-react';
36import { oktaAuth } from './auth/oktaConfig';
37
38const restoreOriginalUri = async (_oktaAuth: OktaAuth, originalUri: string) => {
39  window.location.replace(originalUri ?? '/');
40};
41
42// Wrap your router:
43// <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
44//   <Routes>
45//     <Route path="/login/callback" element={<LoginCallback />} />
46//     <Route element={<RequiredAuth />}>
47//       <Route path="/dashboard" element={<Dashboard />} />
48//     </Route>
49//   </Routes>
50// </Security>

After a successful Okta login, the user's profile information and group memberships are available through the useOktaAuth hook. The authState object contains the idToken and accessToken — the ID token holds user profile claims (name, email, preferred_username) while the access token is used for calling protected APIs. To access group-based roles, you need to configure Okta to include the groups claim in the token. In your Okta Admin Console, navigate to Security → API → Authorization Servers → default → Claims → Add Claim. Create a claim named 'groups', include it in the 'ID Token', set the value type to 'Groups', and filter to include all groups (or specific groups by regex). After adding the claim, users' group memberships appear in idToken.claims.groups as an array of strings. In your React component, read the groups array and use it to conditionally render admin UI, gate feature access, or pass a role to your backend. For server-side enforcement, pass the access token as a Bearer header to your API routes and validate it against Okta's JWKS endpoint.

1// src/hooks/useOktaUser.ts
2import { useOktaAuth } from '@okta/okta-react';
3
4interface OktaUser {
5  name: string;
6  email: string;
7  groups: string[];
8  isAdmin: boolean;
9  isMember: boolean;
10  accessToken: string | null;
11}
12
13export function useOktaUser(): OktaUser | null {
14  const { authState } = useOktaAuth();
15
16  if (!authState?.isAuthenticated || !authState.idToken) {
17    return null;
18  }
19
20  const claims = authState.idToken.claims;
21  const groups: string[] = (claims.groups as string[]) ?? [];
22
23  return {
24    name: (claims.name as string) ?? '',
25    email: (claims.email as string) ?? '',
26    groups,
27    isAdmin: groups.includes('Admins'),
28    isMember: groups.includes('Members'),
29    accessToken: authState.accessToken?.accessToken ?? null,
30  };
31}
32
33// Usage in a component:
34// const user = useOktaUser();
35// if (!user) return <LoadingSpinner />;
36// return <div>Welcome, {user.name} — {user.isAdmin ? 'Admin' : 'Member'}</div>;

The Okta SSO flow cannot be tested end-to-end inside Bolt's WebContainer preview because OAuth 2.0 requires Okta to redirect the browser to a registered callback URL after authentication. Bolt's WebContainer environment doesn't have a stable, publicly accessible URL that Okta can redirect to — this is a fundamental WebContainer limitation, not a configuration issue. To test the full login flow, deploy your Bolt app to Netlify or Vercel. In Netlify, connect your project through the Netlify dashboard and deploy. Note your deployed URL (e.g., `https://my-bolt-app.netlify.app`). Now return to your Okta Admin Console → Applications → your app → General tab → Edit. Under 'Sign-in redirect URIs', confirm your deployed callback URL is listed: `https://my-bolt-app.netlify.app/login/callback`. Under 'Sign-out redirect URIs', confirm `https://my-bolt-app.netlify.app` is listed. Save the changes. In your Netlify site configuration, add the environment variables: set `VITE_OKTA_CLIENT_ID` and `VITE_OKTA_ISSUER` to the same values from your .env file (Netlify injects these at build time for Vite apps). Trigger a new deploy. Once deployed, visit your app URL, click 'Sign in with Okta', and you'll be redirected to Okta's hosted login page — complete the sign-in and you'll be redirected back to your app with an authenticated session.

1# netlify.toml
2[build]
3  command = "npm run build"
4  publish = "dist"
5
6[[redirects]]
7  from = "/*"
8  to = "/index.html"
9  status = 200
10
11# Environment variables to set in Netlify Dashboard (Site Configuration → Environment Variables):
12# VITE_OKTA_CLIENT_ID     = your Okta app Client ID
13# VITE_OKTA_ISSUER        = https://dev-XXXXXXXX.okta.com/oauth2/default
14#
15# After deploy, confirm in Okta Admin Console → Applications → your app → General:
16# Sign-in redirect URI:  https://your-app.netlify.app/login/callback
17# Sign-out redirect URI: https://your-app.netlify.app