Skip to content

docs: describe rejected authentication header values #27

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
soulteary merged 1 commit into from
Nov 7, 2026
Merged

docs: describe rejected authentication header values #27

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 7 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,10 +324,13 @@ On successful authentication, the following headers are set:
| `X-Auth-Role` | User role | `admin` |
| `X-Auth-AMR` | Authentication methods used | `otp,mfa` |

Emitted header values are sanitised: CR and LF are stripped, and a scope or AMR
value containing a comma is dropped rather than emitted — `X-Auth-Scopes` is
comma-separated, so a scope like `read,admin` would otherwise mint an extra
permission downstream. Parse the header back with `ParseScopesFromHeader`.
Scalar identity values containing CR, LF or NUL are omitted rather than repaired.
An empty or rejected user ID still emits `"authenticated"` in the primary user
header, but omits the auth-user header (`X-Auth-User` by default). Scope and AMR
entries containing those characters or a comma are dropped; remaining entries
are trimmed and empty entries are dropped. `X-Auth-Scopes` is comma-separated,
so a scope like `read,admin` would otherwise mint an extra permission downstream.
Parse the header back with `ParseScopesFromHeader`.

## Auth Result

Expand Down
8 changes: 5 additions & 3 deletions README_CN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,9 +309,11 @@ if result.AuthRefreshFailed {
| `X-Auth-Role` | 用户角色 | `admin` |
| `X-Auth-AMR` | 使用的认证方法 | `otp,mfa` |

输出的 header 值经过净化：CR 和 LF 会被剥掉，含逗号的 scope 或 AMR 值会被丢弃而不是
输出——`X-Auth-Scopes` 是逗号分隔的，像 `read,admin` 这样的 scope 否则会在下游凭空
多出一项权限。读回 header 请用 `ParseScopesFromHeader`。
标量身份值如果含有 CR、LF 或 NUL，会被省略，而不是删除字符后输出。用户 ID 为空或
被拒绝时，主用户 header 仍输出 `"authenticated"`，但省略 auth-user header
（默认为 `X-Auth-User`）。scope 和 AMR 中含这些字符或逗号的项会被丢弃；其余项会去掉
首尾空白，空项也会被丢弃。`X-Auth-Scopes` 用逗号分隔，所以 `read,admin` 这样的 scope
否则会在下游多出一项权限。读回 header 请用 `ParseScopesFromHeader`。

## 认证结果

Expand Down
Loading