Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

✨ feat: support login & session authentication via OAuth 2.0 (Auth0) #1143

Merged
merged 15 commits into from
Feb 8, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
📝 docs: Add authentication integration guide for LobeChat
docs: Add authentication integration guide with Auth.js

Adds a comprehensive guide on integrating a new authentication provider
using Auth.js in both English and Chinese documentation. The guide
includes pre-requisites, step-by-step code integration, server
configuration updates, frontend changes, and environment variable setup.
```

The changes introduce a new guide in the documentation for integrating new authentication providers using Auth.js. The guide is provided in both English and Chinese, ensuring broad accessibility. It covers the necessary pre-requisites, detailed instructions for adding the core authentication code, updating server configuration, modifying frontend components, and setting up the required environment variables. This will aid developers in implementing authentication features using Auth.js in the LobeChat application.
  • Loading branch information
CloudPassenger committed Feb 7, 2024
commit 604cbd712ef5e3ca06e6ec6099cbc97a8dad5f38
85 changes: 85 additions & 0 deletions docs/Development/Authentication.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# New Authentication Provider Guide

LobeChat uses [Auth.js v5](https://authjs.dev/) as the external authentication service. Auth.js is an open-source authentication library that provides a simple way to implement authentication and authorization features. This document will introduce how to use Auth.js to implement a new authentication provider.

### TOC

- [Add New Authentication Provider](#add-new-authentication-provider)
- [Pre-requisites: Check the Official Provider List](#pre-requisites-check-the-official-provider-list)
- [Step 1: Add Authenticator Core Code](#step-1-add-authenticator-core-code)
- [Step 2: Update Server Configuration Code](#step-2-update-server-configuration-code)
- [Step 3: Change Frontend Pages](#step-3-change-frontend-pages)
- [Step 4: Configure the Environment Variables](#step-4-configure-the-environment-variables)

## Add New Authentication Provider

To add a new authentication provider in LobeChat (for example, adding Okta), you need to follow the steps below:

### Pre-requisites: Check the Official Provider List

First, you need to check the [Auth.js Provider List](https://authjs.dev/reference/core/providers) to see if your provider is already supported. If yes, you can directly use the SDK provided by Auth.js to implement the authentication feature.

Next, I will use [Okta](https://authjs.dev/reference/core/providers/okta) as an example to introduce how to add a new authentication provider.

### Step 1: Add Authenticator Core Code

Open the `src/app/api/oauth/next-auth.ts` file and import `next-auth/providers/okta`.

```ts
import { NextAuth } from 'next-auth';
import Auth0 from 'next-auth/providers/auth0';
import Okta from 'next-auth/providers/okta';

// Import Okta provider
```

Add the predefined server configuration.

```ts
// Import server configuration
const { OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, OKTA_ISSUER } = getServerConfig();

const nextAuth = NextAuth({
providers: [
// ... Other providers

Okta({
clientId: OKTA_CLIENT_ID,
clientSecret: OKTA_CLIENT_SECRET,
issuer: OKTA_ISSUER,
}),
],
});
```

### Step 2: Update Server Configuration Code

Open the `src/config/server/app.ts` file and add Okta-related environment variables in the `getAppConfig` function.

```ts
export const getAppConfig = () => {
// ... Other code

return {
// ... Other environment variables

OKTA_CLIENT_ID: process.env.OKTA_CLIENT_ID || '',
OKTA_CLIENT_SECRET: process.env.OKTA_CLIENT_SECRET || '',
OKTA_ISSUER: process.env.OKTA_ISSUER || '',
};
};
```

### Step 3: Change Frontend Pages

Modify the `signIn` function parameter in `src/Features/Conversation/Error/OAuthForm.tsx` and \`src/app/settings/common/Common.tsx

The default is `auth0`, which you can change to `okta` to switch to the Okta provider, or remove this parameter to support all added authentication services

This value is the id of the Auth.js provider, and you can read the source code of the corresponding `next-auth/providers` module to read the default ID.

### Step 4: Configure the Environment Variables

Add `OKTA_CLIENT_ID`、`OKTA_CLIENT_SECRET`、`OKTA_ISSUER` environment variables when you deploy.

Now, you can use Okta as your provider to implement the authentication feature in LobeChat.
83 changes: 83 additions & 0 deletions docs/Development/Authentication.zh-CN.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
# 新身份验证方式开发指南

LobeChat 使用 [Auth.js v5](https://authjs.dev/) 作为外部身份验证服务。Auth.js 是一个开源的身份验证库,它提供了一种简单的方式来实现身份验证和授权功能。本文档将介绍如何使用 Auth.js 来实现新的身份验证方式。

### TOC

- [添加新的身份验证提供者](#添加新的身份验证提供者)
- [准备工作:查阅官方的提供者列表](#准备工作查阅官方的提供者列表)
- [步骤 1: 新增关键代码](#步骤-1-新增关键代码)
- [步骤 2: 更新服务端配置代码](#步骤-2-更新服务端配置代码)
- [步骤 3: 修改前端页面](#步骤-3-修改前端页面)
- [步骤 4: 配置环境变量](#步骤-4-配置环境变量)

## 添加新的身份验证提供者

为了在 LobeChat 中添加新的身份验证提供者(例如添加 Okta),你需要完成以下步骤:

### 准备工作:查阅官方的提供者列表

首先,你需要查阅 [Auth.js 提供者列表](https://authjs.dev/reference/core/providers) 来了解是否你的提供者已经被支持。如果你的提供者已经被支持,你可以直接使用 Auth.js 提供的 SDK 来实现身份验证功能。

接下来我会以 [Okta](https://authjs.dev/reference/core/providers/okta) 为例来介绍如何添加新的身份验证提供者

### 步骤 1: 新增关键代码

打开 `src/app/api/oauth/next-auth.ts` 文件,引入 `next-auth/providers/okta`

```ts
import { NextAuth } from 'next-auth';
import Auth0 from 'next-auth/providers/auth0';
import Okta from 'next-auth/providers/okta';

// 引入 Okta 提供者
```

新增预定义的服务端配置

```ts
// 导入服务器配置
const { OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, OKTA_ISSUER } = getServerConfig();

const nextAuth = NextAuth({
providers: [
// ... 其他提供者

Okta({
clientId: OKTA_CLIENT_ID,
clientSecret: OKTA_CLIENT_SECRET,
issuer: OKTA_ISSUER,
}),
],
});
```

### 步骤 2: 更新服务端配置代码

打开 `src/config/server/app.ts` 文件,在 `getAppConfig` 函数中新增 Okta 相关的环境变量

```ts
export const getAppConfig = () => {
// ... 其他代码

return {
// ... 其他环境变量

OKTA_CLIENT_ID: process.env.OKTA_CLIENT_ID || '',
OKTA_CLIENT_SECRET: process.env.OKTA_CLIENT_SECRET || '',
OKTA_ISSUER: process.env.OKTA_ISSUER || '',
};
};
```

### 步骤 3: 修改前端页面

修改在 `src/features/Conversation/Error/OAuthForm.tsx` 及 `src/app/settings/common/Common.tsx` 中的 `signIn` 函数参数

默认为 `auth0`,你可以将其修改为 `okta` 以切换到 Okta 提供者,或删除该参数以支持所有已添加的身份验证服务

该值为 Auth.js 提供者 的 id,你可以阅读相应的 `next-auth/providers` 模块源码以读取默认 ID

### 步骤 4: 配置环境变量

在部署时新增 Okta 相关的环境变量 `OKTA_CLIENT_ID`、`OKTA_CLIENT_SECRET`、`OKTA_ISSUER`,并填入相应的值,即可使用
Loading