> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://helpdesk.ggcircuit.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 使用 ggLeap 作为 OpenID Connect (OIDC) 提供商

## 🔐 将 ggLeap 用作 OpenID Connect (OIDC) 提供商

ggLeap 支持 **OpenID Connect (OIDC)**，允许第三方应用程序使用其 ggLeap 账户对用户进行身份验证。这支持为合作伙伴应用程序、网站或服务进行 **"使用 ggLeap 登录"** 等集成。

OIDC 基于 OAuth 2.0 构建，允许应用程序安全地验证用户身份并获取基本的个人资料信息。

## 🧠 概述

通过与 ggLeap 的 OIDC 提供商集成，应用程序可以：

* 允许用户 **使用其 ggLeap 账户登录**
* 在支持的应用程序中启用 **单点登录 (SSO)**
* 检索用户信息，例如 **电子邮件、个人资料和群组成员身份**
* 在需要时支持 **特定中心的身份验证**

应用程序通过 ggLeap 对用户进行身份验证，并接收确认身份和请求的权限的 **令牌响应**。

## 🌐 OIDC 颁发者端点

应用程序必须根据环境使用适当的 **颁发者 URL**。

| 环境 | 颁发者 URL |
| ---- |
| 生产环境 | `https://api.ggleap.com/production/oidc` |
| 测试环境 | `https://api.ggleap.com/beta/oidc` |

OIDC 发现元数据和公开签名密钥在颁发者端点下自动可用。大多数 OIDC 库将自动检索此配置。

## 🔑 所需的集成信息

要与 ggLeap OIDC 集成，应用程序开发人员将收到以下凭据：

| 参数 | 描述 |
| ---- |
| **客户端 ID** | 应用程序的唯一标识符 |
| **客户端密钥** | 令牌交换期间使用的机密密钥 |
| **重定向 URI** | ggLeap 发送身份验证响应的 HTTPS 回调 URL |

这些值必须在应用程序的 OIDC 客户端设置中进行配置。

## 🔐 授权请求

应用程序通过将用户发送到 ggLeap **授权端点** 来启动登录。

**端点**

```
{issuer}/connect/authorize
```

**示例授权请求**

```
{issuer}/connect/authorize
?client_id={client_id}
&redirect_uri={encoded_redirect_uri}
&response_type=code
&scope=openid%20email%20profile
&state=abc
&nonce=xyz
[&center_uuid={guid}]
```

### 参数

| 参数 | 描述 |
| ---- |
| `client_id` | 为应用程序颁发的客户端 ID |
| `redirect_uri` | 必须完全匹配已注册的重定向 URL |
| `response_type` | 对授权代码流使用 `code` |
| `scope` | 请求的权限 |
| `state` | 可选的应用程序状态值 |
| `nonce` | 推荐的安全值 |
| `center_uuid` | 如果应用程序支持多个中心，则为必需 |

## 🧾 可用的作用域

应用程序可以在身份验证期间请求以下作用域。

| 作用域 | 描述 |
| ---- |
| `openid` | OIDC 身份验证所需 |
| `email` | 提供用户的电子邮件地址 |
| `profile` | 提供基本的个人资料信息 |
| `group` | 返回用户的 ggLeap 群组信息 |

## 🏢 特定中心的身份验证

某些集成绑定到 **特定的 ggLeap 中心**，而其他集成支持 **多个中心**。

### 中心集成

支持单个中心的应用程序必须包括：

```
center_uuid={guid}
```

在 **授权请求** 中。

## 🔁 令牌交换

用户成功登录后，ggLeap 使用 **授权代码** 将用户重定向回应用程序。

然后应用程序使用令牌端点将此代码交换为令牌。

**端点**

```
{issuer}/connect/token
```

此步骤应使用标准 OAuth **授权代码流**。

## 🚪 登出（结束会话）

应用程序可以使用登出端点将用户登出 ggLeap 会话。

**端点**

```
{issuer}/connect/logout
```

### 参数

| 参数 | 描述 |
| ---- |
| `id_token_hint` | 来自用户最近登录会话的令牌 |
| `post_logout_redirect_uri` | 登出后的可选重定向 URL |

如果提供并允许有效的重定向 URI，用户将在登出后被重定向。

## ⚠️ 常见集成问题

| 问题 | 解决方案 |
| ---- |
| 重定向 URI 不匹配 | 确保重定向 URI 与已注册的 URL 完全匹配 |
| 缺少 `center_uuid` | 为多中心应用程序包括该参数 |
| 身份验证失败 | 确认正确的颁发者环境（生产环境与测试环境） |
| 登录未完成 | 确保应用程序使用授权代码流 |

## 🧪 基本集成测试

要验证集成是否正常工作：

1. 使用您的 **客户端 ID** 和 **重定向 URI** 构造授权请求。
2. 在浏览器中打开该 URL。
3. 使用 ggLeap 账户登录。
4. 确认应用程序在重定向 URL 中接收 **授权代码**。
5. 使用 **令牌端点** 交换代码。

如果成功，应用程序将接收 **访问令牌和身份令牌**，确认用户的登录。