React-OIDC 开源项目使用教程

React-OIDC 开源项目使用教程

1. 项目介绍

react-oidc 是一个基于 React 的开源项目，用于实现 OpenID Connect (OIDC) 协议的认证功能。它提供了一个轻量级、安全的 JavaScript 客户端库，支持与各种 OIDC 提供商如 Auth0、Duende Identity Server、Identity Server 4、Azure AD、Google、AWS、Keycloak 等集成。项目旨在简化 OIDC 认证流程，同时提供与 Service Worker 的集成，增强安全性。

2. 项目快速启动

环境准备

确保您的系统中已经安装了 Node.js 和 npm。

安装

npm install @axa-fr/react-oidc --save

配置 Service Worker

在项目根目录下运行以下命令，以确保 Service Worker 文件是最新的：

node ./node_modules/@axa-fr/react-oidc/bin/copy-service-worker-files.mjs public

如果您的项目中有一个 public 文件夹，上述命令会在该文件夹下创建或更新 OidcServiceWorker.js 和 OidcTrustedDomains.js 文件。

启动项目

pnpm start

启动后，您可以在浏览器中访问项目，通常地址为 http://localhost:4200。

3. 应用案例和最佳实践

集成 OIDC 认证

在 React 组件中，您可以使用 @axa-fr/react-oidc 提供的 useOidc 钩子来集成 OIDC 认证。

import { useOidc } from '@axa-fr/react-oidc';

const MyComponent = () => {
  const { oidcUser, oidcLoading, oidcError } = useOidc();

  if (oidcLoading) {
    return <div>加载中...</div>;
  }

  if (oidcError) {
    return <div>认证错误：{oidcError}</div>;
  }

  return (
    <div>
      <h1>用户信息</h1>
      <pre>{JSON.stringify(oidcUser, null, 2)}</pre>
    </div>
  );
};

安全配置

确保 Service Worker 文件与库的版本保持一致，并在 OidcTrustedDomains.js 文件中配置受信任的域名。

// OidcTrustedDomains.js
module.exports = {
  trustedDomains: ['example.com', 'api.example.com']
};

4. 典型生态项目

@axa-fr/react-oidc 是 @axa-fr/oidc-client 库的 React 包装器。以下是与之相关的其他生态项目：

• @axa-fr/oidc-client: 纯 JavaScript OIDC 客户端库。
• @axa-fr/svelte-oidc: 用于 Svelte 框架的 OIDC 集成。
• @axa-fr/vue-oidc: 用于 Vue 框架的 OIDC 集成。
• @axa-fr/angular-oidc: 用于 Angular 框架的 OIDC 集成。

通过这些项目，您可以轻松地在不同的 JavaScript 框架中实现 OIDC 认证。