fix: add docs for 10 commits starting from 9ad2b8ca (2026-06-17) (#1011)

Author: lulululu-debug

docs/application/dynamic-client-registration.md

@@ -75,6 +75,14 @@ Your registration request needs at least one redirect URI. Everything else is op
 
 Applications created through DCR get a 7-day token expiration and are tagged with `dcr` for easy identification in the admin interface.
 
+## Managing a registered client
+
+Casdoor also implements [RFC 7592](https://datatracker.ietf.org/doc/html/rfc7592) so a client can read, update, or delete its own registration at `/api/oauth/register/{client_id}`:
+
+- `GET /api/oauth/register/{client_id}` — read the client's current metadata.
+- `PUT /api/oauth/register/{client_id}` — update the client's metadata.
+- `DELETE /api/oauth/register/{client_id}` — delete the client.
+
 ## Controlling DCR Per Organization
 
 Organizations control whether DCR is available through the `dcrPolicy` setting on the organization configuration page. Two values are supported:

docs/application/terminology.md

@@ -51,7 +51,7 @@ The application edit page is split into eight tabs. Fields below are grouped by
 - **Scopes** — Custom scopes for Agent-category apps (name, display name, description); exposed in OIDC discovery.
 - **Token format** — `JWT`, `JWT-Empty`, `JWT-Custom`, or `JWT-Standard`. See [Token overview](/docs/token/overview).
 - **Token signing method** — Signing algorithm: RS256, RS512, ES256, ES384, or ES512.
-- **Token fields** — Additional user fields included in the token payload (available when format is `JWT-Custom`).
+- **Token fields** — User fields included in the token payload (available when format is `JWT-Custom`). This list also acts as a whitelist for the `/userinfo` endpoint: when non-empty, only the listed fields are returned. Leave empty to include the full set. See [Token overview](/docs/token/overview#restricting-fields-with-token-fields).
 - **Token attributes** — Custom claims added to the token (available when format is `JWT-Custom`). Each row has a **Category**, **Value**, and **Type**:
   - **Category: Static Value** — the Value field is a template string (supports `${user.xxx}` substitution). Type controls whether the claim is a `String` or `Array`.
   - **Category: Existing Field** — the Value field is a dropdown of known user fields (`Owner`, `Name`, `Id`, `DisplayName`, `Email`, `Phone`, `Tag`, `Roles`, `Permissions`, `Groups`, etc.). Casdoor reads the field directly from the user object at token issuance. Properties sub-fields are referenced as `Properties.<key>`.

docs/how-to-connect/oauth.md

@@ -193,6 +193,14 @@ Casdoor provides a built-in device login page at the `verification_uri` where th
 
 Second, you should request `token endpoint` to get Access Token with parameter define in [rfc8628](https://datatracker.ietf.org/doc/html/rfc8628#section-3.4).
 
+:::info Multi-replica deployments
+
+The pending device-authorization requests (the mapping between the device code and the user code) are held in an in-memory store by default. In a multi-replica / horizontally-scaled deployment, the polling request from the device and the browser confirmation may land on different replicas, so an in-memory store causes the device flow to fail intermittently.
+
+To make the device flow work across replicas, configure `redisEndpoint` in `conf/app.conf`. When it is set, Casdoor automatically backs the device-authorization store with Redis so all replicas share the same state. No extra configuration key is needed — the same `redisEndpoint` value used for shared sessions is reused (format: `host:port[,db[,password]]`). If Redis cannot be reached at startup, Casdoor logs a warning and falls back to the in-memory store. See [Configuration](/docs/basic/configuration).
+
+:::
+
 ### Resource Owner Password Credentials Grant
 
 If your application doesn't have a frontend that redirects users to Casdoor, then you may need this.

docs/provider/faceid/overview.md

@@ -11,5 +11,7 @@ Casdoor supports Face ID as a sign-in method. Only enable it when you can ensure
 
 1. Open the Casdoor admin UI → **Providers** → **Add**.
 2. Set **Category** to **Face ID**.
-3. Choose the **Type** (e.g. Alibaba Cloud FaceBody).
-4. Fill in the required fields (e.g. **Client ID**, **Client Secret**, **Endpoint** as needed) and save.
+3. Choose the **Type**:
+   - **Alibaba Cloud Facebody** — cloud face recognition (requires the provider's credentials/endpoint).
+   - **Local UniFace** — on-device face recognition using the [UniFace](https://github.com/yakhyo/uniface) model, with no external service.
+4. Fill in the required fields (e.g. **Client ID**, **Client Secret**, **Endpoint** for cloud types) and save.

docs/provider/oauth/telegram.md

@@ -50,3 +50,9 @@ With the setup completed, users can now log in with Telegram.
 ## Authentication flow
 
 Users sign in via Telegram’s login widget; Casdoor validates the HMAC-SHA256 signature and timestamp per [Telegram’s spec](https://core.telegram.org/widgets/login#checking-authorization). Profile data includes user ID, name, username, and optional photo. Telegram does not provide email via the widget; collect email separately if needed.
+
+:::note Users without a Telegram username
+
+A Telegram username (`@handle`) is optional, so some accounts do not have one. When a user without a public username signs in, Casdoor generates a stable fallback username of the form `telegram_<user_id>` (for example `telegram_123456789`), derived from the account's numeric Telegram ID. Because the ID is stable, the same person keeps the same generated username across logins.
+
+:::

docs/session/rp-initiated-logout.md

@@ -0,0 +1,73 @@
+---
+title: RP-initiated logout
+description: Log a user out of Casdoor from a relying party using the OIDC RP-Initiated Logout endpoint.
+keywords: [OIDC, RP-initiated logout, end session, logout, id_token_hint, post_logout_redirect_uri]
+authors: [hsluoyz]
+---
+
+## Overview
+
+**RP-Initiated Logout** lets a relying party (RP, i.e. your client application) log the user out of Casdoor and, optionally, redirect the browser back to the application afterward. It follows the [OpenID Connect RP-Initiated Logout 1.0](https://openid.net/specs/openid-connect-rpinitiated-1_0-final.html) specification.
+
+This is the endpoint an OIDC client calls as its "end session" endpoint. It differs from [single sign-out](/docs/session/single-sign-out), which terminates every session in the organization at once.
+
+## Endpoint
+
+```text
+GET  /api/logout
+POST /api/logout
+```
+
+| Parameter | Required | Description |
+|---|---|---|
+| `id_token_hint` | Recommended | The ID token (`id_token`) that Casdoor previously issued to the user. When present, Casdoor uses it to identify and expire the exact token/session. |
+| `post_logout_redirect_uri` | Optional | Where to send the browser after logout. Must be registered in the application's **Redirect URLs** list, otherwise the request is rejected. |
+| `client_id` | Optional | The client ID of the application. Used to resolve the application when `id_token_hint` is omitted and the application cannot be determined from the current session. |
+| `state` | Optional | An opaque value echoed back as a `state` query parameter appended to `post_logout_redirect_uri`. |
+
+:::info
+
+Per the OIDC spec, `id_token_hint` is **RECOMMENDED, not REQUIRED**. Casdoor therefore accepts logout requests without it and falls back to the user's current browser session. Some clients (for example, [Gitea](https://github.com/casdoor/casdoor/issues/5607)) only send `post_logout_redirect_uri` (optionally with `client_id`) — these requests are supported.
+
+:::
+
+## Behavior
+
+Casdoor selects one of two paths depending on whether `id_token_hint` is provided.
+
+### With `id_token_hint`
+
+1. The token identified by `id_token_hint` is expired.
+2. The current browser session is cleared and a back-channel logout notification is sent to other applications.
+3. If `post_logout_redirect_uri` is present and valid for the application, the browser is redirected there (with `state` appended when supplied). Otherwise the endpoint returns `200 OK`.
+
+### Without `id_token_hint`
+
+1. If there is no active session, the endpoint returns `200 OK` and does nothing (the user is already logged out).
+2. Otherwise Casdoor logs out the current session. The application is resolved from the session first, and falls back to the one identified by `client_id` when provided.
+3. The session and its token are cleared and a back-channel logout notification is sent.
+4. If `post_logout_redirect_uri` is present and valid for the application, the browser is redirected there (with `state` appended when supplied).
+5. If no `post_logout_redirect_uri` is given, Casdoor returns `200 OK`, including the application's homepage URL when one is configured (except for the built-in application).
+
+## Redirect URI validation
+
+`post_logout_redirect_uri` is always validated against the target application's registered **Redirect URLs**. If the URI is not in that list — or the application cannot be resolved — Casdoor rejects the request with an error instead of redirecting. This prevents open-redirect abuse. Make sure your post-logout URL is added to the application's Redirect URLs.
+
+## Examples
+
+Log out using the ID token and return to the app:
+
+```text
+GET /api/logout?id_token_hint=<ID_TOKEN>&post_logout_redirect_uri=https://myapp.example.com/logged-out&state=xyz
+```
+
+Log out based on the current session, resolving the app by `client_id` (no `id_token_hint`):
+
+```text
+GET /api/logout?client_id=<CLIENT_ID>&post_logout_redirect_uri=https://myapp.example.com/logged-out
+```
+
+## See also
+
+- [Single sign-out (SSO logout)](/docs/session/single-sign-out) — terminate every session in the organization at once.
+- [Session management](/docs/session/management)

docs/token/overview.md

@@ -62,6 +62,21 @@ The token format options behave as follows:
 
 :::
 
+## Restricting fields with Token fields
+
+The **Token fields** setting on the application (used to pick custom user attributes for the `JWT-Custom` format) also acts as a **whitelist for the `/userinfo` endpoint**.
+
+- When **Token fields is empty**, no whitelist is applied: the token payload and the `/userinfo` response include their full default set of fields. This is the default behavior.
+- When **Token fields lists one or more fields**, only those fields are returned. Any user attribute not in the list is omitted from **both** the `JWT-Custom` token payload and the `/userinfo` response.
+
+The whitelist is matched against the underlying user-property names. For example, to expose the display name, email, and avatar through `/userinfo`, add `Name`, `Email`, and `Avatar` to Token fields. Fields still respect the requested OAuth scopes — for instance `Email` is only returned when the `email` scope is granted, `Location` (the `address` claim) only with the `address` scope, and `Phone` only with the `phone` scope. The `sub` and `aud` claims are always returned regardless of the whitelist.
+
+:::caution
+
+Configuring Token fields restricts `/userinfo`, not only the token. If you previously relied on `/userinfo` returning every field, adding entries here will start filtering that response. Leave Token fields empty to keep the full response.
+
+:::
+
 ## OIDC Address Claim
 
 The [OIDC specification](https://openid.net/specs/openid-connect-core-1_0.html#AddressClaim) defines the `address` claim as a JSON object with the following fields:

docs/webhooks/overview.md

@@ -96,6 +96,23 @@ Example JSON sent to your webhook on login:
 
 Your application should parse this payload and perform necessary actions, such as logging the event or notifying another service.
 
+### Sign-in failure classification
+
+Every sign-in attempt is stored as a record (visible under **Records** in the admin console and delivered with the webhook payload). When a sign-in **fails**, Casdoor fills the record's `detail` field with a stable, machine-readable reason so you can classify failures without parsing localized error messages.
+
+Possible reasons are:
+
+| `detail` | Meaning |
+|---|---|
+| `user-not-found` | No matching user for the supplied identifier. |
+| `account-disabled` | The user account is disabled (forbidden). |
+| `account-frozen` | The user account is frozen/locked. |
+| `wrong-password` | The password did not match. |
+| `password-expired` | The password has expired and must be reset. |
+| `mfa-failed` | Multi-factor authentication verification failed. |
+
+Successful sign-ins leave `detail` empty. Use these values to build audit dashboards, alerting (for example, spikes in `wrong-password`), or lockout logic keyed on a specific failure reason.
+
 ## Testing webhooks
 
 Before production, test with:

sidebars.js

@@ -60,6 +60,7 @@ module.exports = {
         "how-to-connect/sdk",
         "session/single-sign-on",
         "session/single-sign-out",
+        "session/rp-initiated-logout",
         "how-to-connect/vue-sdk",
         {
           type: "category",
@@ -546,6 +547,7 @@ module.exports = {
         "session/management",
         "session/single-sign-on",
         "session/single-sign-out",
+        "session/rp-initiated-logout",
       ],
     },
     {