使用 Renaiss 登录（SSO）

通过使用 Renaiss 登录，用户可以用自己的 Renaiss 账户登录你的应用。如果应用已有登录方式，可直接使用钱包身份验证接入收藏和配送。

工作流程

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

接入前准备

向 Renaiss 注册应用，提供应用名称和每个回调的完整 URI。团队会通过安全渠道提供 client_id 和 client_secret。
在后端配置 OIDC 客户端。下方示例采用 Node.js 和 openid-client。

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

配置

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

.env

# 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 可让用户每次登录都确认授权。省略它会复用已有授权。

${RENAISS_ISSUER}/oauth2/authorize?...&prompt=consent

快速接入

发现提供方

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

构建登录路由

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

处理回调

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

读取声明

使用已验证的 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 后，可直接发送以下请求验证配置。

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。

入门

抽卡

交易市场

钱包收藏

实物兑换与配送

开发资源

合作伙伴接入