用于在反应应用程序中使用 FusionAuth 的 SDK .
目录
概览
此 SDK 管理您 React app 的认证状态, 并提供登录、 注册和登录用户的功能 。 它可以很容易的配置来自动管理您的刷新令牌并获取用户信息.
您的用户将被发送到 FusionAuth 的主题主机登录页面和 然后登录。 之后,它们会被送回你的反动应用程序.
认证成功后, 以下安全, HTTP 唯一的 cookie 将设置 :
访问令牌可以提交API,以授权请求和 刷新符可以用来获取新的访问符.
与这个SDK有两种互动方式:
- 通过托管执行 OAuth 令牌交换并满足 fusionAuth Web SDKs的服务器代码要求。 。 。 .
- 通过使用您 FusionAuth 实例中托管的服务器, 即不写入您的服务器代码 .
如果您正在托管自己的服务器, 请查看 服务器代码要求。 。 。 .
您可以使用此库对抗 FusionAuth 或任何 OIDC 版本 符合要求的身份服务器 .
开始
如果您是新建的 React 开发, 您可能想要从快速启动指南开始 。 如果您已经熟悉 React 开发, 请跳到安装区 .
快速启动
见 FusionAuth 反应快速启动 用于使用 FusionAuth 和 React 的完整教程.
安装
国家预防机制:
npm install @fusionauth/react-sdk
亚伦:
yarn add @fusionauth/react-sdk
配置
包装您的应用程序 FusionAuthProvider。 。 。 .
import ReactDOM from 'react-dom/client';
import { FusionAuthProviderConfig, FusionAuthProvider } from '@fusionauth/react-sdk';
const config: FusionAuthProviderConfig = {
clientId: "", // Your app's FusionAuth client id
redirectUri: "", // The URI that the user is directed to after the login/register/logout action
serverUrl: "", // The url of the server that performs the token exchange
shouldAutoFetchUserInfo: true, // Automatically fetch userInfo when logged in. Defaults to false.
shouldAutoRefresh: true, // Enables automatic token refresh. Defaults to false.
onRedirect: (state?: string) => { }, // Optional callback invoked upon redirect back from login or register.
// useDpop: true, // Opt-in to DPoP mode. See "DPoP Mode" below. Defaults to false.
};
ReactDOM.createRoot(document.getElementById("my-app")).render(
<FusionAuthProvider {...config}>
<App />
</FusionAuthProvider>
)
配置为 下一个 JS
用下个配置 SDK, 安装 next-client-cookies 通过 useCookies 输入配置对象为 nextCookieAdapter。 。 。 .
'use client'
import { useCookies } from 'next-client-cookies';
export default function Providers({ children }) {
return (
<FusionAuthProvider {...config} nextCookieAdapter={useCookies}>
{children}
</FusionAuthProvider>
);
}
记得将您的布局包入 <CookiesProvider/> 从 next-client-cookies/server。 。 。 .
Vercel出版了一本指南,用于 在服务器组件中提供第三方上下文提供者。 。 。 .
使用量
使用FusionAuth系统
一旦你的应用被包裹 FusionAuthProvider,您可以使用 useFusionAuth。 。 。 .
import { useFusionAuth } from '@fusionauth/react-sdk';
function MyComponent() {
const {
isLoggedIn,
isFetchingUserInfo,
startLogin,
startRegister,
userInfo
} = useFusionAuth()
if (isFetchingUserInfo) {
return <p>Loading...</p>
}
if (!isLoggedIn) {
return (
<div>
<button onClick={startLogin}>Login</button>
<p>or</p>
<button onClick={startRegister}>Register</button>
</div>
);
}
if (userInfo?.given_name) {
return <p>Welcome {userInfo.given_name}!</p>
}
}
或者,您可以使用 SDK 与 SDK 交互 withFusionAuth 更高级的组件.
状态参数
这个 startLogin 财务报告和审定财务报表 startRegister 函数接受可选字符串参数: state中输入的值将转给 onRedirect 调用您的 FusionAuthProviderConfig。虽然您可以传递您想要的状态参数的值,但它通常用于在重新定向到登录或注册之前显示用户在哪个页面,这样用户可以在成功认证后返回该位置.
保护内容
这个 RequireAuth 组件可以用来保护信息不受未经授权的用户的影响。 需要可选道具 withRole 用于确保用户发挥特定作用。 如果一系列角色被传递,用户必须拥有至少一个需要授权的角色. 这个 Unauthenticated 组件提供反向功能.
import { RequireAuth, useFusionAuth } from '@fusionauth/react-sdk';
const UserNameDisplay = () => {
const { userInfo } = useFusionAuth();
return (
<>
<RequireAuth>
<p>User: {userInfo.given_name}</p> // Only displays if user is authenticated
</RequireAuth>
<Unauthenticated>
<p>Please log in to view this page</p>
</Unauthenticated>
</>
);
};
const AdminPanel = () => (
<RequireAuth withRole="admin">
<button>Delete User</button> // Only displays if user is authenticated and has 'admin' role
</RequireAuth>
);
UI 组件
这个SDK提供3个预建的UI组件.
import {
FusionAuthLoginButton,
FusionAuthLogoutButton,
FusionAuthRegisterButton
} from '@fusionauth/react-sdk';
export const LoginPage = () => (
<>
<h1>Welcome, please log in or register</h1>
<FusionAuthLoginButton />
<FusionAuthRegisterButton />
</>
);
export const AccountPage = () => (
<>
<h1>Hello, user!</h1>
<FusionAuthLogoutButton />
</>
);
DPOP 模式
默认情况下,SDK会调用HttpOnly cookie中存储符号的Hosted后端(useDpop: false,默认值). 在 DPoP 模式中, SDK 转而直接调用 FusionAuth 端点,并将符号绑定在浏览器生成的私人密钥上, per RFC 9449 (韩语)设置时启用 useDpop: true 打开 FusionAuthProviderConfig数字 :
const config: FusionAuthProviderConfig = {
clientId: "",
redirectUri: "",
serverUrl: "",
useDpop: true, // Opt-in to DPoP mode.
dpopTokenStorage: 'localStorage', // 'localStorage' (default, persists across reloads) or 'memory'.
};
何时 useDpop: true, (中文(简体) ), useFusionAuth() 额外返回 dpopFetch, (中文(简体) ), generateProof,以及 getAccessToken这些是: undefined 何时 useDpop 实值 false 或未设.
const { dpopFetch, generateProof, getAccessToken } = useFusionAuth();
// Recommended — handles attaching DPoP headers (and nonce retries) automatically.
const response = await dpopFetch('https://api.example.com/data', { method: 'GET' });
// Advanced — for axios or other HTTP libraries that can't use dpopFetch.
const accessToken = getAccessToken();
const proof = await generateProof('https://api.example.com/data', 'GET', accessToken);
// axios.get('https://api.example.com/data', {
// headers: { Authorization: `DPoP ${accessToken}`, DPoP: proof }
// });
已知问题
无.
文档
这些文件是用 类型doc 并配置为 类型doc- 插件- 标记下。 。 。 .
格式化
推到分行时,有多个林丁包运行. 一个是 prettier如果失败,您可以从命令行中修正文件 :
- npm 运行安装
- npm 运行更美 - -w / path/ to/ file
这样做会覆盖您的文件, 但纠正更漂亮的反对意见.
释放
此软件包通过 GitHub 动作发布 .
升级政策
此库可定期接收带有错误修正、安全补丁、测试、代码样本或文档更改的更新.
这些版本也可能更新依赖性,语言引擎和操作系统,因为我们将遵循图书馆使用的基本技术的贬值和日出政策.
这意味着在依赖性(如语言,框架,或操作系统)被其维护者贬值后,这个库也会被我们贬值,最终可能会被更新以使用更新的版本.