---
title: 三层规则模型
description: Sudomimus 将应用访问控制拆成三个相互独立的层：允许哪些认证方式、允许哪些身份，以及允许哪些返回路径。每一层都采用允许列表和默认拒绝。
editUrl: true
head: []
template: doc
sidebar:
  order: 1
  label: 概述
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

import { CardGrid, LinkButton, LinkCard } from "@astrojs/starlight/components";

Sudomimus 上的每一个应用都由三层相互独立的规则把关。每一层回答一个不同的问题、由各自独立的配置驱动，并在认证流程中的不同位置被检查。三层都**没有**隐式默认值：一层里没有规则，就意味着这一层什么都不放行。

## 三个层

| 层 | 名称 | 回答的问题 | 检查时机 |
|---|---|---|---|
| **Layer 1** | 认证规则 | 允许使用哪些认证方式？ | 向用户展示可选方式时，以及每一次实际的认证尝试。 |
| **Layer 2** | 身份准入规则 | 允许哪些身份完成登录？ | 认证成功之后、把认证请求标记为 realized 之前。 |
| **Layer 3** | 返回规则 | 如何把认证结果回传给应用？ | `/establish` 时（针对声明的 return methods），以及运行时（如 `/status-poll`）。 |

这样切分的好处是：三个维度可以独立演化。新开启一种认证方式不会顺带放宽可登录身份的范围，收紧允许的回调域也不需要动认证配置。

## 允许列表 + 默认拒绝

每一层都是**纯允许列表**。新应用的三层均为空，必须显式添加规则后才能使用。系统不存在“全部放行”的隐式模式；删除任一层的最后一条规则，就会让应用停止接受登录，而不会回退到其他默认值。

这是刻意为之：默认放行的认证系统在配置被误解时会悄无声息地泄露访问权限。默认拒绝意味着配置错误的表现是一次显眼的失败，而不是一次无声的越权。

## 按 Inquiry 收紧

应用级规则定义应用**整体上**允许的范围，单次登录通常可以更严格。例如，管理员入口可能只允许通行密钥，某个租户的入口则可能只允许特定邮箱列表。因此，`/establish` 请求接受三个可选的限制字段：

| `/establish` 上的字段 | 收紧的层 |
|---|---|
| `authenticationConstraints` | 认证规则（Layer 1） |
| `realizeConstraints` | 身份准入规则（Layer 2） |
| `returnMethods` | 返回规则（Layer 3） |

每个字段的形状与对应的规则形状对齐，所以两边用的是同一套词汇。

- **字段缺失** —— 这一层不做额外收紧；只看应用规则。
- **字段存在但是空数组** —— 直接拒绝。空收紧表达的是"什么都不放行"，而把应用里的规则删空已经能表达同样的语义。
- **字段存在且非空** —— 每一项都会经过结构校验并写入认证请求。评估时，它与应用规则按 **AND** 组合。

## 同层 OR、跨层 AND

当同一个评估点上有多条记录可能匹配时，组合方式如下：

- **同一层、同一来源的多条记录 = OR** —— 例如，应用的多条认证规则只需任意一条匹配。
- **跨层 = AND；同层跨来源也 = AND** —— 认证规则、身份准入规则和返回规则必须全部通过。每一层内，应用规则与可选的单次请求限制也必须同时放行。

因此，认证请求上的限制**只能缩小允许范围**，不能放宽应用规则原本禁止的内容。

## Token TTL

每条规则和每项认证请求限制都可以提供 `accessTokenTtlSeconds` 与 `refreshTokenTtlSeconds`。Connect API 会收集所有匹配值，并在所有层和来源之间取**最小值**，让最严格的设置生效。

默认 access token **3 小时**、refresh token **30 天**。Refresh 的 TTL 永远会被拉到不小于 access TTL。完整区间（access 60 秒 – 7 天；refresh 1 天 – 365 天）见 [令牌与验证](/zh-cn/concepts/tokens-and-verification/#ttl-区间)。

## 接下来读哪里

每一层都有专门的页面，给出 schema、通配/匹配语义，以及一个实际示例：

<CardGrid>
<LinkCard
    title="Layer 1 —— 认证规则"
    description="应用允许哪些认证方式，以及如何限制单次认证请求。"
    href="/zh-cn/application-rules/authentication-rules/"
/>
<LinkCard
    title="Layer 2 —— 身份准入规则"
    description="允许哪些身份完成登录 —— 通过邮箱（支持通配）、Steam ID、账户别名（精确匹配）或扇区主体（精确匹配）。"
    href="/zh-cn/application-rules/realize-rules/"
/>
<LinkCard
    title="Layer 3 —— 返回规则"
    description="结果如何回传 —— 回调、status polling、REVEAL、DIRECT_ISSUE、OIDC。"
    href="/zh-cn/application-rules/return-rules/"
/>
</CardGrid>

<LinkButton href="/zh-cn/application-rules/authentication-rules/" variant="primary" icon="right-arrow">从认证规则开始</LinkButton>