# SSO & External Member Sync

> FastGPT External Member System Integration and Configuration

Source: https://doc.fastgpt.io/guide/admin/sso
Last Updated: 2026-11-12

Use this guide to connect your organization's member system or office messaging platform to FastGPT for SSO and member synchronization. Built-in quick login with GitHub, Google, Microsoft, or WeChat Official Account is configured separately.

## Overview

To simplify integration with **external member systems**, FastGPT provides a set of **standard interfaces** for connecting to external systems, along with a FastGPT-SSO-Service image that serves as an **adapter**.

Through these standard interfaces, you can:

1. SSO login. After a callback from an external system, create a user in FastGPT.
2. Member and organizational structure sync (referred to as "member sync" below).

**How It Works**

FastGPT-pro includes a standard set of SSO and member sync interfaces. The system performs SSO and member sync operations based on these interfaces.

FastGPT-SSO-Service aggregates SSO and member sync interfaces from different sources and converts them into the format recognized by fastgpt-pro.

The login flow is:

1. The user clicks the SSO login button. FastGPT requests an authorization URL from the adapter and redirects the user to the external system.
2. The user signs in to the external system, which redirects back to FastGPT at `/login/provider` with a `code`.
3. FastGPT sends the code to the adapter. The adapter retrieves the external user information and converts it into FastGPT's standard response format.
4. FastGPT uses that response to register or sign in the user.

![SSO through an adapter](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/diagrams/sso-adapter.en.light.svg)

## System Configuration Tutorial

### 1. Deploy the SSO-Service Image

Deploy using docker-compose:

```yaml
fastgpt-sso:
  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:latest
  container_name: fastgpt-sso
  restart: always
  networks:
    - fastgpt
  environment:
    - SSO_PROVIDER=example
    - AUTH_TOKEN=xxxxx # Auth token, used by fastgpt-pro
    # Provider-specific environment variables below
```

Depending on the provider, you'll need different environment variables. Below are the built-in protocols/IMs:

Protocol/Feature
SSO
Member Sync Support

Lark
Yes
Yes

WeCom
Yes
Yes

DingTalk
Yes
No

SAML 2.0
Yes
No

OAuth 2.0
Yes
No

LDAP
No
Yes

### 2. Configure fastgpt-pro

#### 1. Configure Environment Variables

The `EXTERNAL_USER_SYSTEM_BASE_URL` environment variable should be set to the internal network address. For example, with the configuration above:

```yaml
env:
  - EXTERNAL_USER_SYSTEM_BASE_URL=http://fastgpt-sso:3000
  - EXTERNAL_USER_SYSTEM_AUTH_TOKEN=xxxxx
```

> This address is operator-configured and is a trusted internal endpoint rather than user-controlled
> input. SSO authorization, the OAuth callback, and member sync all connect to it directly and are
> unaffected by `CHECK_INTERNAL_IP`; enabling `CHECK_INTERNAL_IP=true` does not break SSO login or
> member sync.

#### 2. In the FastGPT frontend, go to `Admin` -> `System Configuration` -> `User Configuration` to configure button text, icons, etc.

In the admin panel's external user system settings, enter the **SSO login button title** and choose an **SSO login button icon**. Use a label that identifies your provider, such as "Sign in with Lark". The icons below are examples for the supported providers.

WeCom
DingTalk
Lark

![WeCom](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/sso15.png)
![DingTalk](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/sso16.png)
![Lark](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/sso17.png)

#### 3. Enable Member Sync (Optional)

To synchronize members from an external system, select **Member sync mode** in the admin panel's team mode settings. See [Team Mode Documentation](https://doc.fastgpt.io/guide/admin/teamMode) for each mode's account and team behavior.

The screenshot below shows the team mode selector and the SSO button title and icon controls. Its selector currently displays multi-team mode; choose member sync mode to enable synchronization. Use the service address from your deployment configuration above.

![Team mode selector and SSO login button settings](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso1.png.webp)

#### 4. Optional Configuration

1. Automatic scheduled member sync

Set the fastgpt-pro environment variable to enable automatic member sync:

```yaml
env:
  - 'SYNC_MEMBER_CRON=0 0 * * *' # Cron expression, runs daily at 00:00. Note: uses UTC (timezone 0). For example, to sync at 12:00 Beijing time, set this to "0 4 * * *" (UTC 04:00)
```

## Built-in Provider Configuration Examples

### Lark

#### 1. Get Parameters

App ID and App Secret

Go to the developer console, click on your enterprise self-built app, and view the app credentials on the Credentials & Basic Info page.

![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso3.png.webp)

#### 2. Permission Configuration

Go to the developer console, click on your enterprise self-built app, and enable permissions on the Permission Management page under Development Configuration.

![2. Permission Configuration — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso4.png.webp)

You can use the **Batch Import/Export Permissions** feature to import the following permission configuration:

```json
{
  "scopes": {
    "tenant": [
      "contact:user.phone:readonly",
      "contact:contact.base:readonly",
      "contact:department.base:readonly",
      "contact:department.organize:readonly",
      "contact:user.base:readonly",
      "contact:user.department:readonly",
      "contact:user.email:readonly",
      "contact:user.employee_id:readonly"
    ],
    "user": []
  }
}
```

Note: The accessible data scope must be set to visible to all members.

#### 3. Redirect URL

Go to the developer console, click on your enterprise self-built app, and set the redirect URL in Security Settings under Development Configuration.
The redirect URL should follow the format `https://www.fastgpt.cn/login/provider` — replace the domain with your publicly accessible FastGPT domain.
![3. Redirect URL — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso5.png.webp)

#### 4. yml Configuration Example

```yaml
fastgpt-sso:
  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:latest
  container_name: fastgpt-sso
  restart: always
  networks:
    - fastgpt
  environment:
    - SSO_PROVIDER=feishu
    - AUTH_TOKEN=xxxxx
    # OAuth endpoint (for private Lark deployments, replace with your private address; same below)
    - SSO_TARGET_URL=https://accounts.feishu.cn/open-apis/authen/v1/authorize
    # Token endpoint
    - FEISHU_TOKEN_URL=https://open.feishu.cn/open-apis/authen/v2/oauth/token
    # User info endpoint
    - FEISHU_GET_USER_INFO_URL=https://open.feishu.cn/open-apis/authen/v1/user_info
    # Redirect address — must match the URL from step 3 exactly
    - FEISHU_REDIRECT_URI=https://www.fastgpt.cn/login/provider
    # Lark App ID, usually starts with cli
    - FEISHU_APP_ID=xxx
    # Lark App Secret
    - FEISHU_APP_SECRET=xxx
```

### DingTalk

#### 1. Get Parameters

CLIENT_ID and CLIENT_SECRET

Go to the DingTalk Open Platform, click App Development, select your app, and record the Client ID and Client Secret on the Credentials & Basic Info page.
![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso6.png.webp)

#### 2. Permission Configuration

Go to the DingTalk Open Platform, click App Development, select your app, and manage permissions on the Permission Management page under Development Configuration. Required permissions:

1. **_Personal phone number information_**
2. **_Contact personal information read permission_**
3. **_Basic permission to obtain DingTalk open interface user access credentials_**

#### 3. Redirect URL

Go to the DingTalk Open Platform, click App Development, select your app, and configure on the Security Settings page under Development Configuration.
Two items need to be filled in:

1. Server egress IP (list of server IPs calling DingTalk server-side APIs)
2. Redirect URL (callback domain)

#### 4. yml Configuration Example

```yaml
fastgpt-sso:
  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:latest
  container_name: fastgpt-sso
  restart: always
  networks:
    - fastgpt
  environment:
    - SSO_PROVIDER=dingtalk
    - AUTH_TOKEN=xxxxx
    # OAuth endpoint
    - SSO_TARGET_URL=https://login.dingtalk.com/oauth2/auth
    # Token endpoint
    - DINGTALK_TOKEN_URL=https://api.dingtalk.com/v1.0/oauth2/userAccessToken
    # User info endpoint
    - DINGTALK_GET_USER_INFO_URL=https://oapi.dingtalk.com/v1.0/contact/users/me
    # DingTalk App ID
    - DINGTALK_CLIENT_ID=xxx
    # DingTalk App Secret
    - DINGTALK_CLIENT_SECRET=xxx
```

### WeCom

> After the WeCom member sync logic is updated, redeploy the `fastgpt-sso-service` relay service
> using the published `latest` image.

#### 1. Get Parameters

1. Enterprise CorpID

   a. Log in to the WeCom admin console with an admin account: `https://work.weixin.qq.com/wework_admin/loginpage_wx`

   b. Go to the "My Enterprise" page and find the Enterprise ID

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso7.png.webp)

2. Create an internal app for FastGPT:

   a. Get the app's AgentID and Secret

   b. The app's visibility scope determines the WeCom member sync scope. Include at least the departments that should be synchronized; to synchronize the entire enterprise, select the root department (all visible).

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso8.png.webp)

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso9.png.webp)

3. A domain name with the following requirements:

   a. Resolves to a publicly accessible server

   b. Can serve static files at the root path (for domain ownership verification — follow the prompts, you only need to host one static file, which can be removed after verification)

   c. Configure web authorization, JS-SDK, and WeCom authorization login

   d. You can set "Hide app in Studio" at the bottom of the WeCom Authorization Login page

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso10.png.webp)

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso11.png.webp)

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso12.png.webp)

4. Get the "Contact Sync Assistant" secret

   Retrieving contacts and organization member IDs requires the "Contact Sync Assistant" secret

   Security & Management -- Management Tools -- Contact Sync

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso13.png.webp)

5. Enable interface sync

6. Get the Secret

7. Configure enterprise trusted IPs

   ![1. Get Parameters — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/sso14.png.webp)

#### 2. Use the latest image to deploy the fastgpt-sso relay service

WeCom SSO login uses the app Secret, while member synchronization uses the Contact Sync Assistant Secret. Pull the published `latest` image and recreate the service:

```bash
docker compose pull fastgpt-sso
docker compose up -d --force-recreate fastgpt-sso
```

```yaml
fastgpt-sso:
  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:latest
  container_name: fastgpt-sso
  restart: always
  networks:
    - fastgpt
  environment:
    - AUTH_TOKEN=xxxxx
    - SSO_PROVIDER=wecom
    # OAuth endpoint, used in WeCom client
    - WECOM_TARGET_URL_OAUTH=https://open.weixin.qq.com/connect/oauth2/authorize
    # SSO endpoint, QR code scan
    - WECOM_TARGET_URL_SSO=https://login.work.weixin.qq.com/wwlogin/sso/login
    # Get user ID (returns ID only)
    - WECOM_GET_USER_ID_URL=https://qyapi.weixin.qq.com/cgi-bin/auth/getuserinfo
    # Get detailed user info (everything except name)
    - WECOM_GET_USER_INFO_URL=https://qyapi.weixin.qq.com/cgi-bin/auth/getuserdetail
    # Get user info (has name, no other info)
    - WECOM_GET_USER_NAME_URL=https://qyapi.weixin.qq.com/cgi-bin/user/get
    # Get department ID list
    - WECOM_GET_DEPARTMENT_LIST_URL=https://qyapi.weixin.qq.com/cgi-bin/department/list
    # Get user ID list
    - WECOM_GET_USER_LIST_URL=https://qyapi.weixin.qq.com/cgi-bin/user/list_id
    # WeCom CorpId
    - WECOM_CORPID=
    # WeCom App AgentId, usually 1000xxx
    - WECOM_AGENTID=
    # WeCom App Secret
    - WECOM_APP_SECRET=
    # Contact Sync Assistant Secret
    - WECOM_SYNC_SECRET=
```

#### 4. WeCom member sync rules

* `/org/list` returns departments visible to the WeCom app.
* `/user/list` still retrieves members through the Contact Sync Assistant, but keeps only members who belong to at least one department visible to the app.
* A member's department list is filtered to visible departments; a member who belongs only to invisible departments is not synchronized to FastGPT.
* After changing the app visibility scope or image version, run member synchronization again. You can also call the endpoints below to verify the result first.

### Standard OAuth 2.0

We provide OAuth 2.0 integration support using the authorization code grant from RFC 6749.
References:

* [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749) documentation
* [Ruan Yifeng's blog post on OAuth 2.0](https://www.ruanyifeng.com/blog/2014/05/oauth_2_0.html)

#### Parameter Requirements

##### Three Endpoints

We provide a standard OAuth 2.0 integration flow requiring three endpoints:

1. Login authorization endpoint (users are redirected here with parameters after clicking the SSO button), e.g., `http://example.com/oauth/authorize`
   ```bash
   curl -X GET\
   "http://example.com/oauth/authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider"
   ```
   After entering credentials, users are redirected to redirect_uri with a code parameter:
   `https://fastgpt.cn/login/provider?code=4/P7qD2qAz4&state=xyz`
2. Access token endpoint. After obtaining the code, make a *server-side request* to this endpoint to get the access_token, e.g., `http://example.com/oauth/access_token`
   ```bash
   curl -X POST\
       -H "Content-Type: application/x-www-form-urlencoded"\
   "http://example.com/oauth/access_token?grant_type=authorization_code&client_id=s6BhdRkqt3&client_secret=xxx&code=4/P7qD2qAz4&redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider"
   ```
   Set `Content-Type` to `application/x-www-form-urlencoded`.
3. User info endpoint, requires passing the access_token, e.g., `http://example.com/oauth/user_info`
   ```bash
   curl -X GET\
       -H "Authorization: Bearer 4/P7qD2qAz4"\
       "http://example.com/oauth/user_info"
   ```
   Note: access_token is passed as the Authorization header in the format: Bearer xxxx

##### Parameter Configuration

* CLIENT_ID: Required
* CLIENT_SECRET: Optional, skip if not needed
* SCOPE: Optional, skip if not needed

> The redirect_uri parameter is auto-populated based on the runtime environment
>
> Other fixed parameters like grant_type and response_type are auto-populated

#### Configuration Example

```yaml
fastgpt-sso:
  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:latest
  container_name: fastgpt-sso
  restart: always
  networks:
    - fastgpt
  environment:
    - SSO_PROVIDER=oauth2
    - AUTH_TOKEN=xxxxx
    # OAuth2.0
    # === Request URLs ===
    # 1. OAuth2 login authorization URL (required)
    - OAUTH2_AUTHORIZE_URL=
    # 2. OAuth2 access token URL (required)
    - OAUTH2_TOKEN_URL=
    # 3. OAuth2 user info URL (required)
    - OAUTH2_USER_INFO_URL=
    # === Parameters ===
    # 1. client_id (required)
    - OAUTH2_CLIENT_ID=
    # 2. client_secret (optional)
    - OAUTH2_CLIENT_SECRET=
    # 3. scope (optional)
    - OAUTH2_SCOPE=
    # === Field Mapping ===
    # OAuth2 username field mapping (required)
    - OAUTH2_USERNAME_MAP=
    # OAuth2 avatar field mapping (optional)
    - OAUTH2_AVATAR_MAP=
    # OAuth2 member name field mapping (optional)
    - OAUTH2_MEMBER_NAME_MAP=
    # OAuth2 contact field mapping (optional)
    - OAUTH2_CONTACT_MAP=
```

### LDAP User and Organization Sync

The LDAP provider only synchronizes users and organizations. It does not provide login. The recommended setup is to use separate providers for login and synchronization:

```yaml
fastgpt-sso:
  image: registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-sso-service:latest
  environment:
    - SSO_PROVIDER=oauth2
    - SSO_SYNC_PROVIDER=ldap
    - AUTH_TOKEN=replace-with-a-sync-token
    - LDAP_URL=ldap://ldap.example.com:389
    - LDAP_BASE_DN=dc=example,dc=com
    - LDAP_BIND_DN=cn=fastgpt-sync,dc=example,dc=com
    - LDAP_BIND_PASSWORD=replace-with-readonly-password
    - LDAP_USER_BASE_DN=ou=people,dc=example,dc=com
    - LDAP_USER_FILTER=(&(objectClass=inetOrgPerson)(uid=*))
    - LDAP_USER_USERNAME_ATTRIBUTE=uid
    - LDAP_USER_MEMBER_NAME_ATTRIBUTE=displayName
    - LDAP_USER_CONTACT_ATTRIBUTE=mail
    - LDAP_USERNAME_PREFIX=ldap-
    - LDAP_MEMBERSHIP_MODE=user_attribute
    - LDAP_USER_ATTRIBUTE_ORG_BASE_DN=ou=company,dc=example,dc=com
    - LDAP_USER_ATTRIBUTE_ORG_FILTER=(objectClass=organizationalUnit)
    - LDAP_USER_ATTRIBUTE_ORG_NAME_ATTRIBUTE=ou
    - LDAP_USER_ATTRIBUTE_MEMBERSHIP_ATTRIBUTE=ou
    - LDAP_USER_ATTRIBUTE_MEMBERSHIP_VALUE_TYPE=name_or_dn
```

SSO_PROVIDER remains responsible for login. Setting SSO_SYNC_PROVIDER=ldap makes /user/list and /org/list use LDAP. LDAP does not provide login endpoints; do not set SSO_PROVIDER=ldap when SSO login is required.

#### FastGPT Configuration

fastgpt-pro must reach the SSO service and use the same token as SSO-service.AUTH_TOKEN:

```yaml
env:
  - EXTERNAL_USER_SYSTEM_BASE_URL=http://fastgpt-sso:3000
  - EXTERNAL_USER_SYSTEM_AUTH_TOKEN=replace-with-a-sync-token
  - SYNC_MEMBER_CRON=0 0 * * *
```

Select **Member sync mode** under **Team mode settings** in the FastGPT frontend at `Admin` -> `System Configuration` -> `User Configuration`. `SYNC_MEMBER_CRON` uses UTC; leaving it empty disables scheduled synchronization.

#### LDAP Connection Configuration

| Environment variable            | Required | Default                                | Description                                                     |
| ------------------------------- | -------- | -------------------------------------- | --------------------------------------------------------------- |
| LDAP_URL                        | Yes      | -                                      | Only ldap\:// and ldaps\:// are supported; do not use https\:// |
| LDAP_BASE_DN                    | Yes      | -                                      | Default search base DN                                          |
| LDAP_BIND_DN                    | Yes      | -                                      | Read-only synchronization account DN                            |
| LDAP_BIND_PASSWORD              | Yes      | -                                      | Synchronization account password                                |
| LDAP_USER_BASE_DN               | No       | LDAP_BASE_DN                           | User search base                                                |
| LDAP_USER_FILTER                | No       | (&(objectClass=inetOrgPerson)(uid=\*)) | LDAP user filter                                                |
| LDAP_USER_USERNAME_ATTRIBUTE    | No       | uid                                    | User identifier attribute                                       |
| LDAP_USER_MEMBER_NAME_ATTRIBUTE | No       | displayName                            | Display name attribute                                          |
| LDAP_USER_CONTACT_ATTRIBUTE     | No       | mail                                   | Contact attribute                                               |
| LDAP_USER_AVATAR_ATTRIBUTE      | No       | Empty                                  | Avatar attribute; empty disables sync                           |
| LDAP_USERNAME_PREFIX            | No       | ldap-                                  | Username prefix                                                 |
| LDAP_PAGE_SIZE                  | No       | 500                                    | LDAP page size                                                  |
| LDAP_TIMEOUT_MS                 | No       | 10000                                  | LDAP operation timeout in milliseconds                          |
| LDAP_CONNECT_TIMEOUT_MS         | No       | 10000                                  | LDAP connection timeout in milliseconds                         |

For ldaps\://, configure LDAP_TLS_REJECT_UNAUTHORIZED, LDAP_TLS_CA_FILE, LDAP_TLS_CA, LDAP_TLS_CERT_FILE, LDAP_TLS_KEY_FILE, and LDAP_TLS_SERVERNAME as needed. Use LDAP_TLS_CA_FILE for a private CA. Client certificate and key must be configured together.

#### Membership Modes

LDAP_MEMBERSHIP_MODE supports four modes:

| Mode             | Relationship                                                    | Main configuration        |
| ---------------- | --------------------------------------------------------------- | ------------------------- |
| user_attribute   | A user attribute, usually ou, points to an organization         | `LDAP_USER_ATTRIBUTE_*`   |
| group_member_dn  | A group attribute, usually member, contains user DNs            | `LDAP_GROUP_MEMBER_DN_*`  |
| user_member_of   | A user attribute, usually memberOf, contains group DNs          | `LDAP_USER_MEMBER_OF_*`   |
| posix_member_uid | A group attribute, usually memberUid, contains user identifiers | `LDAP_POSIX_MEMBER_UID_*` |

**1. user_attribute: user attribute points to an organization**

```dotenv
LDAP_MEMBERSHIP_MODE=user_attribute
LDAP_USER_ATTRIBUTE_ORG_BASE_DN=ou=company,dc=example,dc=com
LDAP_USER_ATTRIBUTE_ORG_FILTER=(objectClass=organizationalUnit)
LDAP_USER_ATTRIBUTE_ORG_NAME_ATTRIBUTE=ou
LDAP_USER_ATTRIBUTE_MEMBERSHIP_ATTRIBUTE=ou
LDAP_USER_ATTRIBUTE_MEMBERSHIP_VALUE_TYPE=name_or_dn
```

name_or_dn first tries a DN match and then falls back to the organization name.

**2. group_member_dn: groups contain user DNs**

```text
dn: cn=engineering,ou=groups,dc=example,dc=com
objectClass: groupOfNames
cn: engineering
member: uid=alice,ou=people,dc=example,dc=com
```

```dotenv
LDAP_MEMBERSHIP_MODE=group_member_dn
LDAP_GROUP_MEMBER_DN_ORG_BASE_DN=ou=groups,dc=example,dc=com
LDAP_GROUP_MEMBER_DN_ORG_FILTER=(objectClass=groupOfNames)
LDAP_GROUP_MEMBER_DN_ORG_NAME_ATTRIBUTE=cn
LDAP_GROUP_MEMBER_DN_MEMBER_ATTRIBUTE=member
LDAP_GROUP_MEMBER_DN_MEMBER_VALUE_TYPE=dn
```

For groupOfUniqueNames, change the filter to objectClass=groupOfUniqueNames and usually set the member attribute to uniqueMember.

**3. user_member_of: users contain group DNs**

```dotenv
LDAP_MEMBERSHIP_MODE=user_member_of
LDAP_USER_MEMBER_OF_ORG_BASE_DN=ou=groups,dc=example,dc=com
LDAP_USER_MEMBER_OF_ORG_FILTER=(objectClass=groupOfNames)
LDAP_USER_MEMBER_OF_ORG_NAME_ATTRIBUTE=cn
LDAP_USER_MEMBER_OF_MEMBERSHIP_ATTRIBUTE=memberOf
LDAP_USER_MEMBER_OF_MEMBERSHIP_VALUE_TYPE=dn
```

User entries must contain the memberOf attribute. Some OpenLDAP deployments require the memberof overlay.

**4. posix_member_uid: POSIX groups contain user UIDs**

```text
dn: cn=engineering,ou=groups,dc=example,dc=com
objectClass: posixGroup
cn: engineering
memberUid: alice
```

```dotenv
LDAP_MEMBERSHIP_MODE=posix_member_uid
LDAP_POSIX_MEMBER_UID_ORG_BASE_DN=ou=groups,dc=example,dc=com
LDAP_POSIX_MEMBER_UID_ORG_FILTER=(objectClass=posixGroup)
LDAP_POSIX_MEMBER_UID_ORG_NAME_ATTRIBUTE=cn
LDAP_POSIX_MEMBER_UID_MEMBER_ATTRIBUTE=memberUid
LDAP_POSIX_MEMBER_UID_USER_ID_ATTRIBUTE=uid
LDAP_POSIX_MEMBER_UID_MEMBER_VALUE_TYPE=username
```

#### Sync Results and Limitations

* Organization IDs use normalized LDAP DNs, and parentId is derived from DN hierarchy.
* If the final organization list has multiple parentless organizations, a virtual root with id ldap-virtual-root and name ROOT is inserted.
* The user result uses orgs for organization IDs. Synced usernames default to ldap- plus the LDAP user identifier.
* The login provider must use the same prefix and identifier rule.
* Nested groups are not recursively expanded, and dynamic groups are not parsed.

#### Manually Check the Sync Interfaces

```bash
curl -H 'Authorization: Bearer replace-with-a-sync-token' http://fastgpt-sso:3000/org/list
curl -H 'Authorization: Bearer replace-with-a-sync-token' http://fastgpt-sso:3000/user/list
```

## Standard Interface Documentation

Below is the standard interface documentation for SSO and member sync in FastGPT-pro. If you need to integrate with a non-standard system, refer to this section for development.

With a custom integration, your external system implements the standard endpoints directly. FastGPT requests the authorization URL, redirects the user to sign in, and then exchanges the returned `code` for user information. It uses that information to register or sign in the user. The adapter-based flow described above performs the same exchange through FastGPT-SSO-Service.

![SSO through standard provider endpoints](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/diagrams/sso-direct.en.light.svg)

FastGPT provides the following standard interfaces:

1. [https://example.com/login/oauth/getAuthURL](https://example.com/login/oauth/getAuthURL) - Get the authorization redirect URL
2. [https://example.com/login/oauth/getUserInfo?code=xxxxx](https://example.com/login/oauth/getUserInfo?code=xxxxx) - Consume the code and exchange it for user info
3. [https://example.com/org/list](https://example.com/org/list) - Get the organization list
4. [https://example.com/user/list](https://example.com/user/list) - Get the member list

### Get SSO Login Redirect URL

Returns a redirect login URL. FastGPT will automatically redirect to this URL. The redirect_uri is automatically appended to the URL query string.

#### Request Example

```bash
curl -X GET "https://redirect.example/login/oauth/getAuthURL?redirect_uri=xxx&state=xxxx" \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json"
```

#### Response Example

Success:

```json
{
  "success": true,
  "message": "",
  "authURL": "https://example.com/somepath/login/oauth?redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider%0A"
}
```

Failure:

```json
{
  "success": false,
  "message": "Error message",
  "authURL": ""
}
```

### SSO Get User Info

This interface accepts a code parameter for authentication, consumes the code, and returns user info.

#### Request Example

```bash
curl -X GET "https://oauth.example/login/oauth/getUserInfo?code=xxxxxx" \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json"
```

#### Response Example

Success:

```json
{
  "success": true,
  "message": "",
  "username": "fastgpt-123456789",
  "avatar": "https://example.webp",
  "contact": "+861234567890",
  "memberName": "Member name (optional)"
}
```

Failure:

```json
{
  "success": false,
  "message": "Error message",
  "username": "",
  "avatar": "",
  "contact": ""
}
```

### Get Organizations

#### Request Example

```bash
curl -X GET "https://example.com/org/list" \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json"
```

#### Response Example

Warning: Only one root department can exist. If your system has multiple root departments, you need to add a virtual root department first. Return type:

```ts
type OrgListResponseType = {
  message?: string; // Error message
  success: boolean;
  orgList: {
    id: string; // Unique department ID
    name: string; // Name
    parentId: string; // parentId — empty string for root department
  }[];
};
```

```json
{
  "success": true,
  "message": "",
  "orgList": [
    {
      "id": "od-125151515",
      "name": "Root Department",
      "parentId": ""
    },
    {
      "id": "od-51516152",
      "name": "Sub Department",
      "parentId": "od-125151515"
    }
  ]
}
```

### Get Members

#### Request Example

```bash
curl -X GET "https://example.com/user/list" \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json"
```

#### Response Example

Return type:

```typescript
type UserListResponseListType = {
  message?: string; // Error message
  success: boolean;
  userList: {
    username: string; // Unique ID. username must match the username returned by the SSO interface. Must include a prefix, e.g., sync-aaaaa, consistent with the SSO interface prefix
    memberName?: string; // Name, used as tmbname
    avatar?: string;
    contact?: string; // email or phone number
    orgs?: string[]; // IDs of organizations the member belongs to. Pass [] if no organization
  }[];
};
```

Example response:

```json
{
  "success": true,
  "message": "",
  "userList": [
    {
      "username": "fastgpt-123456789",
      "memberName": "John Doe",
      "avatar": "https://example.webp",
      "contact": "+861234567890",
      "orgs": ["od-125151515", "od-51516152"]
    },
    {
      "username": "fastgpt-12345678999",
      "memberName": "Jane Smith",
      "avatar": "",
      "contact": "",
      "orgs": ["od-125151515"]
    }
  ]
}
```

## How to Integrate Non-Standard Systems

1. Self-development: Build according to the standard interfaces provided by FastGPT, then configure the deployed service address via the `EXTERNAL_USER_SYSTEM_BASE_URL` environment variable (displayed as read-only under `Admin` -> `System Configuration` -> `User Configuration`).
   You can use this template repository as a starting point: [fastgpt-sso-template](https://github.com/labring/fastgpt-sso-template)
2. Custom development by the FastGPT team:
   a. Provide the system's SSO documentation, member and organization retrieval documentation, and an external test address.
   b. In fastgpt-sso-service, add the corresponding provider and environment variables, and write the integration code.
