Next.js 的SDK望远镜

Next.js的Descope SDK为在Next.js上书写的应用程序提供了方便的Descope访问. 你可以读更多关于 望远镜网站。 。 。 .

这个SDK在罩下使用Descope React SDK和Descope节点SDK 参见 瞄准镜反射 SDK 财务报告和审定财务报表 望远镜节点 SDK 更多细节.

所需资源

• SDK支持Next.js版本13及以上.
• 望远镜 Project ID 用于使用SDK。 硂т descope 控制台中的项目页面。 。 。 .

安装 SDK

以 :

npm i --save @descope/nextjs-sdk

使用量

本节包含App路由器和Pages路由器的指南. 关于Pages路由器,见 页面路由器 节.

应用路由器

以 Auth 提供方来包装您的应用程序布局

// src/app/layout.tsx

import { AuthProvider } from '@descope/nextjs-sdk';

export default function RootLayout({
    children
}: {
    children: React.ReactNode
}) {
    return (
        <AuthProvider projectId="your-descope-project-id">
            <html lang="en">
                <body>{children}</body>
            </html>
        </AuthProvider>
    );
}

说明: AuthProvider 用途 sessionTokenViaCookie={{ sameSite: 'Lax' }} 默认,以便 自动中间软件 将工作出盒子. 会话符号饼干设定为 SameSite=Lax; Secure; 默认. 如果您需要自定义, 您可以设置 sessionTokenViaCookie={{sameSite: 'Strict'}} (如果你只通过) sameSite, (中文(简体) ), secure 将设定为 true (默认情况下).

使用视角来渲染流程

你用得着 默认流量 或者说 提供流量 id 直接转到Descope组件

// Login page, e.g. src/app/sign-in.tsx
import { Descope } from '@descope/nextjs-sdk';
// you can choose flow to run from the following without `flowId` instead
// import { SignInFlow, SignUpFlow, SignUpOrInFlow } from '@descope/nextjs-sdk'

const Page = () => {
    return (
        <Descope
            flowId="sign-up-or-in"
            onSuccess={(e) => console.log('Logged in!')}
            onError={(e) => console.log('Could not logged in!')}
            redirectAfterSuccess="/"
            // redirectAfterError="/error-page"
        />
    );
};

参见 瞄准镜反射 SDK 部分 用于列出可用的道具.

正在中断更改( v- next) : 如果您将自定义屏幕通过 onScreenUpdate,则 服务器生成的用于直接显示的屏幕数据 context 现在生活在 context.data - 比如说. context.totp → context.data.totp见 反应 SDK onScreenUpdate 节 编辑 @ descope/ web- 组件 README 完整清单 context.data 字段.

说明: Descope是一个客户端组件. 如果使它成为服务器组件,则无法通过 onSuccess编号 :onError编号 :errorTransformer编号 :logger 道具是因为它不是系列的。 要在流程完成后重定向用户,请使用 redirectAfterSuccess 财务报告和审定财务报表 redirectAfterError 道具来.

客户端使用量

使用 useDescope, (中文(简体) ), useSession 财务报告和审定财务报表 useUser 为获取认证状态、用户细节和公用设备在组件中设置钩子

这可能有助于实施应用程序特定逻辑. 实例:

• 如果当前会话被认证, 将不同组件渲染
• 渲染用户内容
• 注销按钮

注意:这些钩子只应在客户端组件中使用(例如,组件带有 use client 注释).

'use client';
import { useDescope, useSession, useUser } from '@descope/nextjs-sdk/client';
import { useCallback } from 'react';

const App = () => {
    // NOTE - `useDescope`, `useSession`, `useUser` should be used inside `AuthProvider` context,
    // and will throw an exception if this requirement is not met
    // useSession retrieves authentication state, session loading status, and session token
    // Use `isAuthenticated` to check whether there is an active session - not `sessionToken`
    const { isAuthenticated, isSessionLoading, sessionToken } = useSession();
    // useUser retrieves the logged in user information
    const { user } = useUser();
    // useDescope retrieves Descope SDK for further operations related to authentication
    // such as logout
    const sdk = useDescope();

    if (isSessionLoading || isUserLoading) {
        return <p>Loading...</p>;
    }

    const handleLogout = useCallback(() => {
        sdk.logout();
    }, [sdk]);

    if (isAuthenticated) {
        return (
            <>
                <p>Hello {user.name}</p>
                <button onClick={handleLogout}>Logout</button>
            </>
        );
    }

    return <p>You are not logged in</p>;
};

重要内容: 总是使用 isAuthenticated 确定是否存在活动会话 - 从不 sessionToken。 。 。 .

sessionToken 当会话符号无法为客户端代码访问时为空, 例如当Descope项目配置为在 cookie 中管理会话符号时( )Secure + 键 HttpOnly DS 饼干),或何时 persistTokens={false} 已经设定。 在这些设置中,用户被充分认证,同时 sessionToken 是一个空字符串,所以默默地守护它上的逻辑跳过这个逻辑:

// WRONG - skipped for authenticated users when the session token lives in an HttpOnly cookie
if (!sessionToken && !isSessionLoading) {
  return; // e.g. bailing out before calling sdk.logout()
}

// CORRECT
if (!isAuthenticated && !isSessionLoading) {
  return;
}

isAuthenticated 来源于会话的过期, SDK 在每一个符号存储模式中都会收到。 读取 sessionToken 仅当您实际需要原始 JWT(例如将其附加到API 请求中)时,并使用 claims 以在会场上宣读索赔。 在服务器一侧使用 session() 换句话说.

基于活动的会话刷新

默认情况下,SDK在标签活动时会点出周期性心跳(重新呼叫). 你可以选择通过通过精细的控制 autoRefresh={{ customActivityTracking: true }} 改为 AuthProvider。启用此模式后, SDK 只在 sdk.markUserActive() 自上次刷新以来, 一直被调用, 用于执行服务器侧不活动超时 .

步骤1: 启用于 AuthProvider数字 :

import { AuthProvider } from '@descope/nextjs-sdk';

<AuthProvider
    projectId="my-project-id"
    autoRefresh={{ customActivityTracking: true }}
>
    <App />
</AuthProvider>;

步骤2: 打电话 markUserActive() 使用 useDescope 钩从 @descope/nextjs-sdk/client数字 :

'use client';
import { useEffect } from 'react';
import { useDescope } from '@descope/nextjs-sdk/client';

function useActivityTracking() {
    const sdk = useDescope();

    useEffect(() => {
        const { markUserActive } = sdk;

        document.addEventListener('click', markUserActive);
        document.addEventListener('keydown', markUserActive);
        document.addEventListener('touchstart', markUserActive);

        const onVisibility = () => {
            if (document.visibilityState === 'visible') markUserActive();
        };
        document.addEventListener('visibilitychange', onVisibility);

        return () => {
            document.removeEventListener('click', markUserActive);
            document.removeEventListener('keydown', markUserActive);
            document.removeEventListener('touchstart', markUserActive);
            document.removeEventListener('visibilitychange', onVisibility);
        };
    }, [sdk]);
}

打电话 useActivityTracking() 内置客户组件 <AuthProvider>。 。 。 .

触发自动刷新

useSession 触发对 Descope 后端的单个请求,以尝试刷新会话。 狦 别 useSession 在您的应用程序中,会话不会自动被刷新 。 如果您的应用程序不需要 useSession,您可以手动触发刷新 refresh 从 useDescope 钩. 示例

import { useEffect } from 'react';

const { refresh } = useDescope();
useEffect(() => {
    refresh().catch(console.error);
}, [refresh]);

服务器侧用法

应用程序需要认证 (Middleware)

您可以使用 Next.js Middleware 要求认证一个页面/路由或一组页面/路由 .

Descope SDK提供一种中间软件功能,可用于要求认证一个页面/路由或一组页面/路由.

// src/middleware.ts
import { authMiddleware } from '@descope/nextjs-sdk/server'

export default authMiddleware({
    // The Descope project ID to use for authentication
    // Defaults to process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID
    projectId: 'your-descope-project-id',

    // The URL to redirect to if the user is not authenticated
    // Defaults to process.env.SIGN_IN_ROUTE or '/sign-in' if not provided
    // NOTE: In case it contains query parameters that exist in the original URL, they will override the original query parameters. e.g. if the original URL is /page?param1=1&param2=2 and the redirect URL is /sign-in?param1=3, the final redirect URL will be /sign-in?param1=3&param2=2
    redirectUrl?: string,

    // These are the public and private routes in your app. You can also use wildcards (e.g. /api/*) with routes as well in these definitions.
    // Read more about how to use these below.
    publicRoutes?: string[],
    privateRoutes?: string[]
    // If you having privateRoutes and publicRoutes defined at the same time, privateRoutes will be ignored.

  // Optional: log level for the middleware
  // Defaults to 'info'
  // logLevel: 'debug' | 'info' | 'warn' | 'error'

    // Optional: skip the refresh token validation fallback
    // Defaults to false
    skipRefreshTokenValidation?: boolean
})

export const config = {
    matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)']
}

公共和私人路线定义

• 默认情况下,所有路线都是私人路线.
• publicRoutes数字 : 用它来指定哪些路由不需要认证. 如果指定,只有这些路线和默认的公共路线将是公开的.
• privateRoutes数字 : 使用此选项来指定哪些路径需要认证 。 如果指定,只有这些路线是私有的,所有其他路线都是公有的.
• 冲突处理: 如果两者兼有 publicRoutes 财务报告和审定财务报表 privateRoutes 提供, privateRoutes 警告将被记录下来.

此设置可确保您可以清晰定义应用程序中的哪些路径需要认证, 而哪些则不需要认证, 同时提供一种机制来优雅地处理潜在的错误配置 .

公共路线

• 说明 : 一系列不需要认证的公用路线.
• 配置 : 使用 publicRoutes 指定不需要认证的路径.
• 额外的默认 : 除您指定的路线外,还包括下列默认的公共路线:
  • process.env.SIGN_IN_ROUTE 或者说 /sign-in 未提供
  • process.env.SIGN_UP_ROUTE 或者说 /sign-up 未提供
• 示例

  const options = {
    publicRoutes: ['/home', '/about']
  };
  

私人路线

• 说明 : 一系列需要认证的私人路线.
• 配置 : 使用 privateRoutes 以指定需要认证的路径。 所有其他路线都将被视为公开路线.
• 冲突处理: 如果两者兼有 publicRoutes 财务报告和审定财务报表 privateRoutes 同时界定, privateRoutes 警告将被记录下来.
• 示例

  const options = {
    privateRoutes: ['/dashboard', '/profile']
  };
  

跳过刷新托肯验证

默认情况下,当会话令牌丢失或过期时,中间软件会倒回验证刷新令牌,如果请求有效,则让请求通过. 中间软件不刷新会话, 因此依赖的服务器侧码 session() 仍然看不到有效的会话.

设定 skipRefreshTokenValidation: true 以要求一个有效的会话令牌 - 只有有效的刷新令牌的请求会被重定向到登录的路由. 当您的服务器侧码需要在每个私有路径上一个有效的会话时,此功能是有用的 .

const options = {
    skipRefreshTokenValidation: true
};

应用软件要做什么

用户带有过期的会话符和仍然有效的刷新符被重定向到登录路由. 在客户身上, AuthProvider 单独从刷新符中刷新会话符号(autoRefresh ),因此,用户无需重新认证即可再次认证.

您的登录页面将会发送一个已经认证的用户离开, 否则他们会坐在它上 . 渲染 <Descope /> 与 redirectAfterSuccess 包括这个,以及检查 useSession() 然后离开自己. 重定向取代了原来的路径名,并且只包含它的查询参数,所以如果想要将用户返回到他们来自的页面,请在重定向前亲自抓取.

在服务器侧读取会话信息

使用该 session() 帮助在服务器组件和路由处理器中读取会话信息.

注:使用时 authMiddleware 仍然建议会议管理(因为它只验证一次会议), session() 可以没有它而运行。 若为 authMiddleware 没有设置会话, session() 将尝试从 cookie 取回会话符号, 然后分析并验证它 .

服务器组件 :

// src/app/page.tsx

import { session } from '@descope/nextjs-sdk/server';

async function Page() {
    const sessionRes = await session();
    if (!sessionRes) {
        // ...
    }
    // Use the session jwt or parsed token
    const { jwt, token } = sessionRes;
}

路由处理器 :

// src/pages/api/routes.ts
export async function GET() {
    const currSession = await session();
    if (!currSession) {
        // ...
    }

    // Use the session jwt or parsed token
    const { jwt, token } = currSession;
}

这个 session() 函数使用 Next.js 的 cookies() 财务报告和审定财务报表 headers() 函数以获取会话符号。 如果您正在使用 Next.js 版本 13, 您可以使用 getSession(req) 换句话说.

import { getSession } from '@descope/nextjs-sdk/server';

export async function GET(req) {
    const currSession = await getSession(req);

    // ...
}

可选参数

如果中间软件没有设置会话,则 session() 函数将尝试从 cookie 取回会话令牌并验证它,这需要项目ID要么设置在环境变量中,要么作为函数的参数被传递. 您也可以将日志级别传递到函数(默认为"info").

session({
  projectId?: string;
  baseUrl?: string;
  logLevel?: 'debug' | 'info' | 'warn' | 'error'
})

• 项目编号 : 地镜工程ID. 如果不提供,该函数将返回到 NEXT_PUBLIC_DESCOPE_PROJECT_ID 从环境变量.
• 基础Url : Descope API 基础 URL.

这允许开发者使用 session() 即使工程ID不在环境中设置.

在服务器一侧访问 Descope SDK

使用 createSdk 在服务器侧创建 Descope SDK 的函数.

参见 望远镜节点 SDK 用于列出可用的函数.

路由处理器中的用法示例 :

// src/pages/api/routes.ts
import { createSdk } from '@descope/nextjs-sdk/server';

const sdk = createSdk({
    // The Descope project ID to use for authentication
    // Defaults to process.env.NEXT_PUBLIC_DESCOPE_PROJECT_ID
    projectId: 'your-descope-project-id',

    // The Descope management key to use for management operations
    // Defaults to process.env.DESCOPE_MANAGEMENT_KEY
    managementKey: 'your-descope-management-key'

    // Optional: Descope API base URL
    // Defaults to process.env.NEXT_PUBLIC_DESCOPE_BASE_URL
    // baseUrl: 'https://...'
});

export async function GET(req) {
    const { searchParams } = new URL(req.url);
    const loginId = searchParams.get('loginId');

    const { ok, data: user } = await sdk.management.user.load(loginId);
    if (!ok) {
        // ...
    }
    // Use the user data ...
}

页面路由器

本节正在执行中:-) 在此期间,你可以在 页面路由器 文件夹.

部件

部件是允许您曝光基于租户执行的管理特性的组件. 在某些情况下,您的客户可能需要独立执行管理行动的能力,从而减轻与您联系的必要性。 部件是一个功能,使您能够以模块化的方式将这些能力委托给客户.

重要说明:

• 要让用户能够使用部件,需要指定 Tenant Admin 作用.

用户管理

这个 UserManagement 部件将允许您在您的网站上嵌入一个用户表以查看并采取行动 .

部件让你:

• 创建新用户
• 编辑已有的用户
• 激活/ 禁用已有用户
• 重置现有用户密码
• 删除已有用户的密码
• 删除已有的用户

说明:

• 自定义字段也出现在表格中.

使用量

import { UserManagement } from '@descope/nextjs-sdk';
...
  <UserManagement
    widgetId="user-management-widget"
    tenant="tenant-id"
  />

示例 管理用户

角色管理

这个 RoleManagement 部件会让您在您的站点内嵌入一个角色表以查看并采取行动 .

部件让你:

• 创建新角色
• 改变现有角色的字段
• 删除现有角色

说明:

• 这个 Editable 字段是由用户对角色的访问决定的 - 意思是项目级角色不能被租户级用户编辑.
• 您需要预先定义用户可以使用的权限, 这些权限不能在部件中编辑 .

使用量

import { RoleManagement } from '@descope/nextjs-sdk';
...
  <RoleManagement
    widgetId="role-management-widget"
    tenant="tenant-id"
  />

示例 管理角色

访问密钥管理

这个 AccessKeyManagement 部件会让您在您的站点内嵌入一个访问密钥表, 以查看并采取行动 .

部件让你:

• 创建新访问密钥
• 激活/关闭现有访问密钥
• 删除扩展访问密钥

使用量

import { AccessKeyManagement } from '@descope/nextjs-sdk';
{
    /* admin view: manage all tenant users' access keys */
}
<AccessKeyManagement
    widgetId="access-key-management-widget"
    tenant="tenant-id"
/>;

{
    /* user view: mange access key for the logged-in tenant's user */
}
<AccessKeyManagement
    widgetId="user-access-key-management-widget"
    tenant="tenant-id"
/>;

示例 管理访问密钥

审计管理

这个 AuditManagement 部件会让您在您的站点内嵌入一个审计表 .

使用量

import { AuditManagement } from '@descope/nextjs-sdk';
...
  <AuditManagement
    widgetId="audit-management-widget"
    tenant="tenant-id"
  />

示例 管理审计

用户配置

这个 UserProfile 部件允许您在您的应用程序中嵌入用户配置文件组件, 并允许登录在用户中更新其配置文件 .

部件让你:

• 更新用户配置图
• 更新用户个人信息
• 更新认证方法
• 注销

使用量

import { UserProfile } from '@descope/nextjs-sdk';
...
  <UserProfile
    widgetId="user-profile-widget"
    onLogout={() => {
      // add here you own logout callback
      window.location.href = '/login';
    }}
  />

示例 用户配置

应用程序门户

这个 ApplicationsPortal 允许您在应用程序中嵌入一个应用程序门户组件,并允许登录用户打开分配给他们的应用程序.

使用量

import { ApplicationsPortal } from '@descope/nextjs-sdk';
...
  <ApplicationsPortal
    widgetId="applications-portal-widget"
  />

示例 用户配置

代码示例

您可以在其中找到一个实例响应应用程序 示例文件夹- 说说看 应用路由器 - 说吧 页面路由器

学习更多

学习更多 请看 视角文档和 API 参考页面。 。 。 .

联系我们

如果您需要帮助, 您可以发送电子邮件 瞄准镜支持

许可证

用于反应的SDK探测器在下列条件下获得使用许可: 麻省理工学院许可证协议。 。 。 .