lazycat-auth-integration

LazyCat Microservices authentication integration

First confirm the target lzcos and lzc-cli versions; before writing configuration you must read references/spec-sync.md, and follow the process therein to verify the official source text on site. The LPK V2 example requires lzcos >= 1.5.0、lzc-cli >= 2.0.0; older targets cannot be applied directly.

Choose the mechanism first

Requirement	Mechanism	Minimum system version	Required reading
Application uses unified login	OIDC	1.3.5+	references/oidc.md
Backend identifies platform user	Ingress injects Header	Subject to the official documentation for the target version	references/http-request-headers.md
Script accesses system API	API Auth Token	1.4.3+	references/api-auth-token.md
A very small number of paths bypass platform HTTP login	public_path	Subject to the official documentation for the target version	references/public-api.md
Application accesses its own/other applications on behalf of the current user	.lzcx + delegated ticket	1.5.2+	references/app-interconnect.md

OIDC minimal flow

1. Confirm from upstream application documentationaccuratecallback path.
2. In lzc-manifest.yml set application.oidc_redirect_path; without this field, OIDC environment variables will not be generated.
3. Pass only the OIDC variables the application needs to the corresponding service, preferring issuer discovery.
4. Do not write the dynamically generated client secret into images, databases, or documentation.

The following follows the official Outline image and callback, showing only the OIDC-related fragment; the database, Redis, storage, and other environment variables required by Outline must still be configured according to its deployment documentation, and this fragment cannot be started independently.

# package.yml（LPK V2 静态元数据片段）
package: cloud.lazycat.app.outline
version: 0.0.1
name: Outline

# lzc-manifest.yml（OIDC 相关运行配置片段）
application:
  subdomain: 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}

The variable names on the left come from Outline's official integration requirements; when adapting to other applications, they must be adjusted according to that application's documentation. On the right, LAZYCAT_AUTH_OIDC_* is a platform variable.

Boundaries of identity Headers

• Only when the request is certain to pass through the platform Ingress trust boundary should the platform-generated X-HC-* be treated as the basis for identity; do not trust values of the same name passed in by the client itself.
• Ordinary logged-in client requests usually include user and device context;API Auth Token does not inject X-HC-Device-ID/X-HC-Device-PeerID, and delegated requests also do not carry the full client device context。
• public_path when authentication fails, the platform will clear the identity Header. Therefore the code must first check whether X-HC-User-ID exists, and must not treat "the path is accessible" as "the user is logged in".

Correct semantics of API Auth Token

The request uses Lzc-Api-Auth-Token: ${LZC_API_TOKEN} to doplatform authentication, and this sensitive Header will be removed before being forwarded to the application. Removing the Token does not mean that an authenticated request cannot reach the application; it only means that the backend does not receive that Token. If the application API also has its own business authentication, the caller must satisfy it separately and must not treat the platform Token as a business Token.

public_path Least privilege principle

By default, do not configure. When entry points such as webhooks or shared downloads are truly needed, allow only precise narrow paths that have passed a risk review, and verify signatures, one-time tokens, or equivalent credentials at the application layer; do not unconditionally open /, administrative interfaces, file read interfaces, or debug interfaces.

Delivery check

• package.yml and lzc-manifest.yml have been separated according to LPK V2, and the fields match the target version.
• The OIDC callback path exactly matches the application's actual callback, and the issuer/endpoints are not concatenated out of thin air.
• No real Token, client secret, weak password, or real device domain name.
• The Header trust boundary is clear, and it can safely degrade when the device Header is missing.
• public_path has been reduced to the minimum scope, with application-layer authentication and unauthenticated testing.
• Inter-application access only requests self_delegate/user_delegate the one item actually needed.