---
navTitle: SSO 授权提示页定制
---
# SSO 授权提示页定制

<!--
维护说明：本页定制路径来自 bi/com.succez.bi/src/main/java/com/succez/security/sso/impl/SSOPageRender.java，
触发入口主要在 ActionAPIAuth.java 和 ActionAPIMe.java。
ActionAPIOAuth2.java 中的 /sysdata/public/authorize/authorize.html 常量当前未接入 GET /api/oauth2/authorize 流程，
不要把它写成可用的页面定制入口。
-->

SSO 授权提示页用于扫码登录、扫码绑定、授权成功、授权失败、二维码过期和授权方式不可用等场景。系统默认页面位于 `/dist/security/sso/`，需要定制时在 `/sysdata/public/sso/` 下放置约定的 FreeMarker 模板。

## 可定制页面{#pages}

| 场景 | 定制文件 | 默认页面 |
| --- | --- | --- |
| 扫码登录授权确认 | `/sysdata/public/sso/auth-{ssoid}.ftl` | `/dist/security/sso/auth.ftl` |
| 扫码绑定授权确认 | `/sysdata/public/sso/bind-{ssoid}.ftl` | `/dist/security/sso/bind.ftl` |
| 无可用扫码应用提示 | `/sysdata/public/sso/auth-tips.ftl` | `/dist/security/sso/auth-tips.ftl` |
| 二维码过期提示 | `/sysdata/public/sso/auth-expired.ftl` | `/dist/security/sso/auth-expired.ftl` |
| 授权失败提示 | `/sysdata/public/sso/auth-fail-{ssoid}.ftl` | `/dist/security/sso/auth-fail.ftl` |
| 授权成功提示 | `/sysdata/public/sso/auth-success-{ssoid}.ftl` | `/dist/security/sso/auth-success.ftl` |
| SSO 授权方式不可用 | `/sysdata/public/sso/auth-invalid.ftl` | `/dist/security/sso/auth-invalid.ftl` |

`{ssoid}` 是单点登录方案 ID，在[单点登录设置](../../../sys-settings/security/sso.md#common-settings)中配置。需要为不同 SSO 方案展示不同品牌或文案时，使用带 `{ssoid}` 的模板文件。

## 扫码登录授权确认页{#qrcode-auth}

用户在 PC 登录页扫码后，手机端完成第三方认证。如果系统没有开启扫码登录静默授权，手机端会展示授权确认页，提示用户是否授权 PC 端登录。

定制文件：

```text
/sysdata/public/sso/auth-{ssoid}.ftl
```

例如单点登录方案 ID 为 `wechat`，则文件路径为：

```text
/sysdata/public/sso/auth-wechat.ftl
```

## 扫码绑定授权确认页{#qrcode-bind}

用户在个人账号中绑定微信、企业微信、钉钉等 SSO 账号时，手机端会展示绑定授权确认页。

定制文件：

```text
/sysdata/public/sso/bind-{ssoid}.ftl
```

## 授权结果提示页{#auth-result}

扫码流程中还可能出现成功、失败、过期等结果页：

| 场景 | 定制文件 |
| --- | --- |
| 授权成功 | `/sysdata/public/sso/auth-success-{ssoid}.ftl` |
| 授权失败 | `/sysdata/public/sso/auth-fail-{ssoid}.ftl` |
| 二维码过期 | `/sysdata/public/sso/auth-expired.ftl` |

授权成功页在微信内打开时，系统默认页面通常会尝试关闭当前页面；不在微信内打开时，才会展示成功提示。定制成功页时应保留这种移动端场景差异。

## 授权方式不可用提示页{#auth-invalid}

通过 `/api/auth/doSSOAuthRedirect` 跳转某个 SSO 方案时，如果没有找到可用的 SSO Provider，系统会展示授权方式不可用页。

定制文件：

```text
/sysdata/public/sso/auth-invalid.ftl
```

## 无可用扫码应用提示页{#auth-tips}

用户扫码后，如果当前浏览器或 App 没有可用的扫码登录方案，系统会展示无可用扫码应用提示页。

定制文件：

```text
/sysdata/public/sso/auth-tips.ftl
```

该页面运行时会注入 `AVAILABLE_APPS`，表示当前系统可用的扫码登录应用名称列表。定制模板时可以读取这个变量展示提示文案。

## 与 OAuth2 授权接口的关系{#oauth2}

`/api/oauth2/authorize` 是 SuccApp 对外提供 OAuth2 授权码流程的接口。当前实现中，用户已授权时会直接重定向到 `redirect_uri` 并带上 `code`；未登录时会跳转到 `/login?redirect_url=...`，登录成功后再回到授权流程。

因此，当前可定制的用户可见页面主要是[登录页](./login-page.md)和本页列出的 SSO/扫码提示页。OAuth2 API 的参数和返回值见[OAuth2 协议相关 API](../../references/web-api/oauth2/README.md)。