Okta redirect URI is required for SSO. Provide it in the opt

Error message

Okta redirect URI is required for SSO. Provide it in the options or set OKTA_REDIRECT_URI environment variable.

What it means

Validation thrown in the OktaAuthProvider constructor when no redirect URI is provided via options.redirectUri or OKTA_REDIRECT_URI. The redirect URI must match a whitelisted URI on the Okta application for the SSO authorization-code flow to work.

Source

Thrown at auth/okta/src/auth-provider.ts:169

    if (!domain) {
      throw new Error('Okta domain is required. Provide it in the options or set OKTA_DOMAIN environment variable.');
    }

    if (!clientId) {
      throw new Error(
        'Okta client ID is required. Provide it in the options or set OKTA_CLIENT_ID environment variable.',
      );
    }

    if (!clientSecret) {
      throw new Error(
        'Okta client secret is required for SSO. Provide it in the options or set OKTA_CLIENT_SECRET environment variable.',
      );
    }

    if (!redirectUri) {
      throw new Error(
        'Okta redirect URI is required for SSO. Provide it in the options or set OKTA_REDIRECT_URI environment variable.',
      );
    }

    if (cookiePassword.length < 32) {
      throw new Error('Cookie password must be at least 32 characters. Set OKTA_COOKIE_PASSWORD environment variable.');
    }

    this.domain = domain;
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    // Normalize trailing slashes so a stray `OKTA_ISSUER=https://domain/` doesn't produce `.../oauth2//v1/...`
    this.issuer = trimTrailingSlashes(issuer ?? `https://${domain}/oauth2/default`);
    // Org authorization servers use issuer `https://{domain}` but serve endpoints under `/oauth2/v1/*`.
    // Custom authorization servers use issuer `https://{domain}/oauth2/<name>` and serve endpoints under `<issuer>/v1/*`.
    // `issuer` is still used verbatim for JWT `iss`-claim validation on both server types.
    this.endpointBase =
      this.issuer.includes('/oauth2/') || this.issuer.endsWith('/oauth2') ? this.issuer : `${this.issuer}/oauth2`;

View on GitHub (pinned to 75dd419e61)

Solutions

Set the OKTA_REDIRECT_URI environment variable (e.g. https://yourapp.com/api/auth/sso/okta/callback).
Pass `redirectUri` explicitly in the constructor options.
Ensure the exact URI is registered as a allowed redirect URI in the Okta application settings.
Use environment-specific values so each deployment points at its own callback.

Example fix

// before
new OktaAuthProvider({ domain, clientId, clientSecret });
// after
new OktaAuthProvider({
  domain,
  clientId,
  clientSecret,
  redirectUri: process.env.OKTA_REDIRECT_URI, // e.g. https://app.example.com/callback
});

Defensive patterns

Strategy: validation

Validate before calling

if (!process.env.OKTA_REDIRECT_URI) {
  throw new Error('Set OKTA_REDIRECT_URI before constructing OktaAuthProvider');
}
const auth = new OktaAuthProvider();

Try / catch

try {
  auth = new OktaAuthProvider();
} catch (e) {
  if (e instanceof Error && e.message.includes('redirect URI is required')) {
    throw new Error('Server misconfiguration: OKTA_REDIRECT_URI missing');
  }
  throw e;
}

Prevention

Configure one redirect URI per environment and register each in the Okta app.
Keep the callback URL in sync between the authorize request and env config.
Include a startup config check that prints the effective redirect URI in dev.

When it happens

Trigger: new OktaAuthProvider(...) with domain, clientId, clientSecret set but neither options.redirectUri nor OKTA_REDIRECT_URI defined.

Common situations: Forgetting to configure the callback URL env var per environment (dev vs prod have different callbacks); Okta app whitelist not including the deployed domain so the var was left unset.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/2d57d28ed705470a. Report an issue: GitHub.