Lazycat Auth Integration

懒猫微服认证体系接入指南

你是一个专业的懒猫微服认证与权限配置专家。当开发者需要让应用实现免密登录（接入 OIDC）、识别当前请求用户信息、或放行部分公共 API 时，请遵循本指南。

1. 接入 OIDC 单点登录 (SSO)

懒猫微服 (v1.3.5+) 提供了统一的 OIDC 支持，允许应用自动获取用户信息和权限组（ADMIN 或 NORMAL），实现免密登录。

配置方法 (`lzc-manifest.yml`): 1. 声明 OIDC 回调路径 (application.oidc_redirect_path)。系统只要检测到这个字段，就会在部署时自动注入相关的环境变量。 2. 将系统生成的 OIDC 环境变量传递给应用。

示例:

application:
  subdomain: myapp
  oidc_redirect_path: /auth/oidc.callback # 必须填写！系统据此生成环境变量。请查阅应用的 OIDC 文档获取准确路径。
services:
  myapp:
    image: xxx
    environment:
      - OIDC_CLIENT_ID=${LAZYCAT_AUTH_OIDC_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${LAZYCAT_AUTH_OIDC_CLIENT_SECRET}
      - OIDC_ISSUER_URI=${LAZYCAT_AUTH_OIDC_ISSUER_URI}
      - OIDC_AUTH_URI=${LAZYCAT_AUTH_OIDC_AUTH_URI}
      - OIDC_TOKEN_URI=${LAZYCAT_AUTH_OIDC_TOKEN_URI}
      - OIDC_USERINFO_URI=${LAZYCAT_AUTH_OIDC_USERINFO_URI}

2. HTTP Headers 身份识别 (自定义后端)

如果用户是在自己开发后端代码，lzc-ingress 会在所有经过认证的请求到达应用容器前，自动注入以下 HTTP Headers。开发者可直接信任这些 Header。

• X-HC-User-ID: 登录的用户名 (UID)
• X-HC-User-Role: 用户角色 (NORMAL 或 ADMIN)
• X-HC-Device-ID: 客户端在当前微服内的唯一设备 ID
• X-HC-Login-Time: 登录时间的 Unix 时间戳

注意： 应用后端可直接根据 X-HC-User-ID 认为该用户已登录，无需再次验证密码。

3. 独立鉴权与免登录访问 (public_path)

默认情况下，所有 HTTP 请求都必须经过懒猫微服的强制登录认证。如果应用有自己的鉴权机制（如 Token），或者这是一个公开页面（如分享链接），可以通过 public_path 放行。

配置方法 (`lzc-manifest.yml`):

application:
  public_path:
    - /api/public/  # 放行 /api/public/ 开头的路径
    - /share/       # 放行 /share/ 开头的路径

注意： 放行的路径，系统依然会尝试获取登录状态。如果已登录，X-HC-User-ID 等 Header 依旧会存在；如果未登录，则清空相关 Header 但不拦截请求。

4. 脚本与自动化调用 (API Auth Token)

当需要编写脚本（如 Python, bash）调用微服系统 API 或应用接口时，不能依赖浏览器的 Cookie。懒猫 (v1.4.3+) 提供了 API Auth Token 机制。

获取方式： 只能通过 SSH 进入微服命令行生成。

hc api_auth_token gen --uid admin

调用方式： 在 HTTP 请求头中带上 Lzc-Api-Auth-Token: <token>。

平台兼容性说明

如果遇到更复杂的 OIDC 配置问题、Header 拦截问题，请主动读取本技能包 references/ 目录下的相关 Markdown 文档（oidc.md, http-request-headers.md, public-api.md, api-auth-token.md）。

API Auth Token

API Auth Token 用于在脚本或命令行里访问系统 API 时进行鉴权，避免依赖浏览器登录态。适合自动化、运维脚本、CI 等场景。

需要 lzcos v1.4.3+。

生成与管理

hc api_auth_token gen
hc api_auth_token gen --uid admin
hc api_auth_token list
hc api_auth_token show <token>
hc api_auth_token rm <token>

• gen 会创建一个 UUID 形式的 token
• --uid 可指定绑定的用户，未指定时会自动使用管理员用户

调用示例

curl -k -H "Lzc-Api-Auth-Token: <token>" "https://<box-domain>/sys/whoami"

行为说明

• Header 名称固定为 Lzc-Api-Auth-Token
• 该 Header 只用于系统鉴权，转发到应用时会被移除
• token 权限等同于绑定用户，请妥善保存并避免泄露
• 因为部分lpk会使用鉴权信息内的客户端信息进行反向访问。此功能在API TOKEN下无法被支持
• 此模式下系统不会自动注入X-HC-Device-PeerID和X-HC-Device-ID
• 此模式下的X-HC-Login-Time为Token的创建时间

http headers ==============

所有从客户端发起的https/http的流量会先进入lzc-ingress这个组件进行分流。

lzc-ingress主要处理以下任务

• 对http请求进行鉴权，若未登录则跳转到登录页面
• 根据请求的域名分流到不同的lzcapp后端

在鉴权成功转发给具体的lzcapp前，lzc-ingress会设置以下额外的http headers

• X-HC-User-ID 登录的UID(用户名)
• X-HC-Device-ID 客户端位于本微服内的唯一ID， 应用程序可以使用这个作为设备标识符
• X-HC-Device-PeerID 客户端的peerid， 仅内部使用。
• X-HC-Device-Version 客户端的内核版本号
• X-HC-Login-Time 微服客户端最后一次的登录时间， 格式为unix时间戳(一个int32的整数)
• X-HC-User-Role 普通用户为:"NORMAL"， 管理员用户为: "ADMIN"
• X-Forwarded-Proto 固定为"https"，以便少量强制https的应用可以正常工作
• X-Forwarded-By 固定为"lzc-ingress"

lzc-ingress是通过HC-Auth-Token这个cookie来进行鉴权的(客户端内是通过其他内部方式完成鉴权)。

当lzc-ingress遇到此cookie值无效或为空时，且目标地址不是public_path，则会跳转到登录页面。

当目标地址为public_path时， lzc-ingress依旧会进行一次鉴权，但不会跳转到登录页面。

• 如果鉴权失败，则会清空上述X-HC-XX的header，避免一些安全风险
• 如果鉴权成功，则会带上上述X-HC-XX的header。

也就是lzcapp开发者在编写后端代码时，不用考虑是否为public_path， 直接信任X-HC-User-ID即可。

lzcapp对接微服的OIDC ====================

v1.3.5+提供了统一的oidc的支持，lzcapp适配oidc后即可自动获取uid和对应权限组(ADMIN代表管理员)

开发者只需要在manifest.yml中提供以下两个信息即可完成适配。

1. 在application.oidc_redirect_path中填写正确的oidc回调地址 这个路径一般是/oauth2/callback或者/auth/oidc.callback， 具体需要查阅应用本身的文档。如果应用文档未提供相关信息，可以先随便填写一个， 登录时浏览器报错时可以查看到实际使用的路径。

2. 通过部署时环境变量获取系统自动生成的相关环境变量给实际应用即可。 必填项为client_id、client_secret。 部分应用额外只需要填写一个ISSUER信息，剩下的会自动事实探测。 部分应用则需要填写多个具体ENDPOINT的信息， 具体支持的信息可以参考部署时环境变量。

::: warning oidc_redirect_path 必须设置了application.oidc_redirect_path系统才会动态生成oidc client相关的环境变量

如果您不知道这个值应该填写什么，可以先随便填写，一般应用的报错页面会告知您正确值。 :::

比如outline这个应用的OIDC适配，根据outline官方文档得知需要设置以下环境变量

• OIDC_CLIENT_ID – OAuth client ID
• OIDC_CLIENT_SECRET – OAuth client secret
• OIDC_AUTH_URI
• OIDC_TOKEN_URI
• OIDC_USERINFO_URI

在manifest.yml中可以这样填写

name: Outline
package: cloud.lazycat.app.outline
version: 0.0.1
application:
  subdomain: outline
  #outline官方文档没有提供这个信息，但通过报错信息可以得到这个地址
  oidc_redirect_path: /auth/oidc.callback
  routes:
    - /=http://outline.cloud.lazycat.app.outline.lzcapp:3000
services:
  outline:
    image: registry.lazycat.cloud/tx1ee/outlinewiki/outline:fb0e2ef4f32f3601
    environment:
      - OIDC_CLIENT_ID=${LAZYCAT_AUTH_OIDC_CLIENT_ID}
      - OIDC_CLIENT_SECRET=${LAZYCAT_AUTH_OIDC_CLIENT_SECRET}
      - OIDC_AUTH_URI=${LAZYCAT_AUTH_OIDC_AUTH_URI}
      - OIDC_TOKEN_URI=${LAZYCAT_AUTH_OIDC_TOKEN_URI}
      - OIDC_USERINFO_URI=${LAZYCAT_AUTH_OIDC_USERINFO_URI}

oidc issuer info ===============

访问https://$微服名称.heiyu.space/sys/oauth/.well-known/openid-configuration#/可以获取完整的issuer信息。

然后使用 https://$LAZYCAT_BOXDOMAIN/$endpoint_path即可自行获取任何endpoint的地址信息。

{
"issuer": "https://your-box-name.heiyu.space/sys/oauth",
"authorization_endpoint": "https://your-box-name.heiyu.space/sys/oauth/auth",
"token_endpoint": "https://your-box-name.heiyu.space/sys/oauth/token",
"jwks_uri": "https://your-box-name.heiyu.space/sys/oauth/keys",
"userinfo_endpoint": "https://your-box-name.heiyu.space/sys/oauth/userinfo",
"device_authorization_endpoint": "https://your-box-name.heiyu.space/sys/oauth/device/code",
"introspection_endpoint": "https://your-box-name.heiyu.space/sys/oauth/token/introspect",
"grant_types_supported": [
"authorization_code",
"refresh_token",
"urn:ietf:params:oauth:grant-type:device_code",
"urn:ietf:params:oauth:grant-type:token-exchange"
],
"response_types_supported": [
"code"
],
"subject_types_supported": [
"public"
],
"id_token_signing_alg_values_supported": [
"RS256"
],
"code_challenge_methods_supported": [
"S256",
"plain"
],
"scopes_supported": [
"openid",
"email",
"groups",
"profile",
"offline_access"
],
"token_endpoint_auth_methods_supported": [
"client_secret_basic",
"client_secret_post"
],
"claims_supported": [
"iss",
"sub",
"aud",
"iat",
"exp",
"email",
"email_verified",
"locale",
"name",
"preferred_username",
"at_hash"
]
}

独立鉴权

HTTP 服务

当您用浏览器访问微服应用时， 为了您的安全必须输入用户名密码才能访问。

但是在一些安全要求不高的场景， 比如公共文件下载服务， 输入用户名密码太繁琐， 您只需要在 lzc-manifest.yml 文件中的 application 字段下加一个 public_path 子字段即可

另外有部分应用有自身的独立鉴权机制，比如通过url中携带token，则可以将此类服务地址的强制鉴权关闭。

application:
  public_path:
    - /api/public

上面配置的意思是， 当浏览器访问 /api/public 路由时， 可以直接访问， 不需要输入用户名密码。

需要注意的是： 1. public_path 仅是关闭微服的http账号密码鉴权，访问时依旧需要登录微服客户端建立虚拟网络 2. public_path 有一定的风险， 请不要对外暴露敏感 API， 比如读取您的文件的服务

此外，还可以使用!排除语法，将除/admin外的整个路径都绕过强制鉴权。(不推荐使用此方式绕过强制鉴权)

application:
  public_path:
    - /
    - !/admin

::: warning 排除语法具有最高优先级，不支持嵌套判断 比如上述规则中如果添加 /admin/unsafe 这条规则是不会生效的。 :::