Next.js中HomePage组件OktaAuth实例未定义的问题求助

问题概述 #

运行Next.js应用时，HomePage组件中的oktaAuth实例显示为undefined，无法正常执行Okta认证流程，未认证用户无法跳转至Okta登录页面，不确定Security组件配置是否正确，或存在遗漏的必要配置。

项目结构 #

/my-nextjs-app
├── /contexts
│   └── UserContext.tsx
├── /pages
│   ├── _app.tsx
│   └── index.tsx
├── /container
│   └── HomeContainer.tsx
├── /utils
│   └── oktaConfig.ts
├── /styles
│   └── globals.css
└── package.json

相关代码 #

HomePage组件 (/pages/index.tsx) #

import React, { useEffect } from "react";
import { OktaAuth } from "@okta/okta-auth-js";

const HomePage: React.FC<{ oktaAuth: OktaAuth }> = ({ oktaAuth }) => {
  useEffect(() => {
    const checkAuth = async () => {
      if (!oktaAuth) {
        console.error("oktaAuth is undefined");
        return;
      }
      
      const isAuthenticated = await oktaAuth.isAuthenticated();
      console.log("isAuthenticated", isAuthenticated);
      
      if (!isAuthenticated) {
        await oktaAuth.signInWithRedirect(); // 跳转至Okta SSO登录页
      } else {
        try {
          const accessToken = await oktaAuth.getAccessToken();
        } catch (error) {
          console.error("获取用户信息或accessToken失败:", error);
        }
      }
    };

    checkAuth();
  }, []);

  return <div></div>;
};

export default HomePage;

MyApp组件 (/pages/_app.tsx) #

import { AppProps } from "next/app";
import { UserProvider } from "../contexts/UserContext";
import { OktaAuth } from "@okta/okta-auth-js";
import { Security } from "@okta/okta-react";
import { useRouter } from "next/router";
import { oktaConfig } from "../utils/oktaConfig";
import "../styles/globals.css";

function MyApp({ Component, pageProps }: AppProps) {
  const router = useRouter();
  const oktaAuth = new OktaAuth(oktaConfig);

  return (
    <UserProvider>
      <Security oktaAuth={oktaAuth} restoreOriginalUri={() => {}}>
        <Component {...pageProps} oktaAuth={oktaAuth} />
      </Security>
    </UserProvider>
  );
}

export default MyApp;

依赖版本 #

"@okta/okta-auth-js": "^7.8.1",
"@okta/okta-react": "^6.9.0",
"next": "^14.1.2",
"next-auth": "^4.24.5",

解决方案 #

1. 使用官方钩子获取oktaAuth实例 #

手动通过props传递oktaAuth容易出现实例丢失问题，@okta/okta-react提供的useOktaAuth钩子是获取实例的标准方式，修改HomePage组件：

import React, { useEffect } from "react";
import { useOktaAuth } from "@okta/okta-react";

const HomePage: React.FC = () => {
  const { oktaAuth } = useOktaAuth();

  useEffect(() => {
    const checkAuth = async () => {
      if (!oktaAuth) {
        console.error("oktaAuth is undefined");
        return;
      }
      
      const isAuthenticated = await oktaAuth.isAuthenticated();
      console.log("isAuthenticated", isAuthenticated);
      
      if (!isAuthenticated) {
        await oktaAuth.signInWithRedirect();
      } else {
        try {
          const accessToken = await oktaAuth.getAccessToken();
          // 此处可添加accessToken的后续业务逻辑
        } catch (error) {
          console.error("获取用户信息或accessToken失败:", error);
        }
      }
    };

    checkAuth();
  }, [oktaAuth]); // 添加oktaAuth到依赖项，避免闭包导致的实例过期问题

  return <div></div>;
};

export default HomePage;

2. 修复restoreOriginalUri函数实现 #

Security组件的restoreOriginalUri是必填项，用于登录完成后重定向回原页面，修改MyApp组件：

import { AppProps } from "next/app";
import { UserProvider } from "../contexts/UserContext";
import { OktaAuth } from "@okta/okta-auth-js";
import { Security } from "@okta/okta-react";
import { useRouter } from "next/router";
import { oktaConfig } from "../utils/oktaConfig";
import "../styles/globals.css";

function MyApp({ Component, pageProps }: AppProps) {
  const router = useRouter();
  const oktaAuth = new OktaAuth(oktaConfig);

  // 正确实现登录后重定向逻辑
  const restoreOriginalUri = async (_oktaAuth: OktaAuth, originalUri: string) => {
    router.replace(originalUri || "/");
  };

  return (
    <UserProvider>
      <Security oktaAuth={oktaAuth} restoreOriginalUri={restoreOriginalUri}>
        <Component {...pageProps} /> {/* 无需手动传递oktaAuth */}
      </Security>
    </UserProvider>
  );
}

export default MyApp;

Okta集成Next.js最佳实践 #

• 优先使用官方钩子：依赖useOktaAuth、useAuthState等官方钩子获取认证实例和状态，避免手动传参的不可靠性。
• 全局单例OktaAuth实例：将OktaAuth实例封装在utils文件中，确保全局只有一个实例，避免重复创建导致的状态不一致：

  // utils/oktaConfig.ts
  import { OktaAuth } from "@okta/okta-auth-js";
  
  export const oktaConfig = {
    clientId: process.env.NEXT_PUBLIC_OKTA_CLIENT_ID!,
    issuer: `${process.env.NEXT_PUBLIC_OKTA_ISSUER}/oauth2/default`,
    redirectUri: `${window.location.origin}/login/callback`,
    scopes: ["openid", "email", "profile"],
    pkce: true,
  };
  
  export const oktaAuth = new OktaAuth(oktaConfig);
  

  之后在MyApp中直接导入该实例即可，无需重复创建。
• 添加登录回调页面：必须创建/pages/login/callback.tsx页面处理Okta登录回调：

  // pages/login/callback.tsx
  import { useRouter } from "next/router";
  import { useEffect } from "react";
  import { useOktaAuth } from "@okta/okta-react";
  
  const LoginCallback = () => {
    const { oktaAuth } = useOktaAuth();
    const router = useRouter();
  
    useEffect(() => {
      const handleCallback = async () => {
        try {
          await oktaAuth.handleLoginRedirect();
          router.push("/");
        } catch (error) {
          console.error("登录回调处理失败:", error);
          router.push("/");
        }
      };
  
      handleCallback();
    }, [oktaAuth, router]);
  
    return <div>登录中...</div>;
  };
  
  export default LoginCallback;
  

• 避免认证方案冲突：你的依赖中同时包含next-auth和Okta官方SDK，两者都是认证解决方案，会导致逻辑冲突，建议只保留一种。
• 适配SSR场景：如果使用服务器端渲染，确保Okta配置在客户端和服务器端一致，使用NEXT_PUBLIC_前缀的环境变量暴露客户端所需配置。

遗漏配置检查 #

• Okta应用配置：确认Okta控制台中创建的是**Single-Page Application(SPA)**类型应用，而非Web应用。
• 回调地址配置：redirectUri必须在Okta控制台的应用设置中添加为允许的回调地址，否则会出现认证失败。
• CORS配置：在Okta控制台的安全设置中，将你的应用域名添加到CORS允许列表，避免跨域请求被拦截。
• 环境变量验证：确保NEXT_PUBLIC_OKTA_CLIENT_ID、NEXT_PUBLIC_OKTA_ISSUER等环境变量已正确配置并可被客户端访问。

内容的提问来源于stack exchange，提问作者rakesh_shetty