> ## Documentation Index
> Fetch the complete documentation index at: https://docs.renaiss.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Renaiss 登录（SSO）

> 将 Renaiss 配置为 OpenID Connect 身份提供方，让用户使用已有 Renaiss 账户登录你的应用。

通过**使用 Renaiss 登录**，用户可以用自己的 Renaiss 账户登录你的应用。如果应用已有登录方式，可直接使用[钱包身份验证](https://docs.renaiss.xyz/cn/authentication.md)接入收藏和配送。

## 工作流程

应用将用户重定向到 Renaiss 确认授权。后端通过授权码和 PKCE 流程换取令牌，验证 ID 令牌后，读取用户授权的账户信息。

## 接入前准备

* [向 Renaiss 注册应用](#联系团队)，提供应用名称和每个回调的完整 URI。团队会通过安全渠道提供 `client_id` 和 `client_secret`。
* 在后端配置 OIDC 客户端。下方示例采用 Node.js 和 [openid-client](https://github.com/panva/node-openid-client)。

请将 `client_secret` 保存在服务端的密钥管理器中，避免写入浏览器代码或代码仓库。若密钥泄露，请联系 Renaiss 更换。

## 配置

使用接入时获得的凭据和已注册的回调地址替换示例值。

```bash .env theme={null}
# Renaiss SSO
RENAISS_ISSUER=https://www.renaiss.xyz/api/auth
RENAISS_CLIENT_ID='your-client-id'
RENAISS_CLIENT_SECRET='your-client-secret'
RENAISS_REDIRECT_URI=https://your-app.example.com/auth/callback
RENAISS_SCOPE="openid profile email safe x"
```

发现文档位于 `${RENAISS_ISSUER}/.well-known/openid-configuration`。将客户端指向该文档即可解析其他接口。

### 客户端设置

| 配置项 | 默认值 |
| - | - |
| 客户端类型 | 机密客户端 |
| 授权方式 | `authorization_code`、`refresh_token` |
| PKCE | 必需，`code_challenge_method=S256` |
| 令牌接口认证 | `client_secret_post`，在请求体中发送密钥 |
| 授权确认页 | 指定 `prompt=consent` 时每次显示，否则仅在首次授权时显示 |

### 选择签发方

`RENAISS_ISSUER` 决定登录环境。使用接入团队为该环境提供的值。

| 环境 | `RENAISS_ISSUER` |
| - | - |
| 生产环境 | `https://www.renaiss.xyz/api/auth` |
| 开发或预览环境 | 由团队提供 |
| 本地 Renaiss（端口 3000） | `http://localhost:3000/api/auth` |

只有 `localhost` 可使用明文 HTTP。已部署的签发方均使用 HTTPS。

### 注册回调地址

回调 URI 必须与应用实际发送的值完全相同，包括端口、路径和末尾斜杠。新增或更改地址时，需将新 URI 提交给团队注册。

### 控制授权确认页

在授权请求中添加 `prompt=consent` 可让用户每次登录都确认授权。省略它会复用已有授权。

```text theme={null}
${RENAISS_ISSUER}/oauth2/authorize?...&prompt=consent
```

## 快速接入

**1. 发现提供方**

加载 `${RENAISS_ISSUER}/.well-known/openid-configuration` 来配置客户端。

**2. 构建登录路由**

生成 PKCE 的 `code_verifier` 和 `code_challenge`（S256），再生成随机 `state` 和 `nonce`，保存在会话中。将用户重定向到授权接口，指定 `scope=openid profile email safe x`，按需添加 `prompt=consent`。

**3. 处理回调**

在回调路径验证 `state`，使用令牌接口交换授权码，在请求体中发送客户端密钥。通过 JWKS 验证 `id_token` 的签名，并检查 `iss`、`aud`、`exp` 和 `nonce`。

**4. 读取声明**

使用已验证的 `id_token` 获取用户信息，也可以调用 userinfo 接口。

接入时可向团队索取基于 `openid-client` 的完整参考实现。

## 返回的用户声明

`id_token` 和 userinfo 根据请求的权限范围返回相应声明。

| 声明 | 权限范围 | 说明 |
| - | - | - |
| `sub` | `openid` | 稳定且不透明的用户标识。用作记录主键，不要解析其内部含义。 |
| `name`、`picture` | `profile` | 姓名和头像。 |
| `email`、`email_verified` | `email` | 邮箱及验证状态。 |
| `safe_wallet_address`、`chain_id`、`legacy_wallet_address` | `safe` | `safe_wallet_address` 为 null 表示钱包尚未就绪。提示用户稍后重试或显示空状态，仍可继续登录。 |
| `twitter_username` | `x` | 缓存的 X 用户名，未关联 X 时为 null。 |

始终验证 `id_token` 的签名及 `iss`、`aud`、`exp`、`nonce`。符合标准的 OIDC 客户端库可以执行这些验证。

## 测试令牌交换

获得授权码 `code` 及对应的 `code_verifier` 后，可直接发送以下请求验证配置。

```bash theme={null}
curl -s -X POST "$RENAISS_ISSUER/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  --data-urlencode code="$AUTH_CODE" \
  --data-urlencode code_verifier="$CODE_VERIFIER" \
  --data-urlencode client_id="$RENAISS_CLIENT_ID" \
  --data-urlencode client_secret="$RENAISS_CLIENT_SECRET" \
  --data-urlencode redirect_uri="$RENAISS_REDIRECT_URI"
```

成功时返回 `access_token` 和 `id_token`，如已请求，还会返回 `refresh_token`。

## 联系团队

如需注册客户端、添加或修改回调 URI，或轮换密钥，请联系 [info@renaiss.xyz](mailto:info@renaiss.xyz)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.