版本提示

本文记录的是 2025 年写作时的懒猫微服开发环境。lzc-cli 命令、lzc-build.yml / lzc-manifest.yml 字段、基础镜像、OIDC 环境变量、路由方式和应用商店流程都可能随系统与 SDK 更新而变化。动手前请先对照当前官方开发文档，并以本机命令帮助、实际日志和最终生成的配置为准。

OpenID Connect（OIDC）是一个基于 OAuth 2.0 的身份认证协议，允许用户使用一个账号（如 Google、微信、Microsoft 账号）登录多个不同的网站或应用，而无需重复注册。我们经常把它和 OAuth 2.0 混为一谈。

它主要用于 身份认证（Authentication），而 OAuth 2.0 主要用于 授权（Authorization）。简单来说：

  • OAuth 2.0 → 让应用能访问你的数据（如获取微信头像），还要自己做用户管理。
  • OIDC → 让应用能确认“你是谁”（如用微信账号登录）

下面以我的懒猫 ENV 查看器为例，来讲解这个登录流程。

当你在应用里点击登录时，浏览器会重定向到登录中心，我们通常把它叫作身份提供商（IdP）。在其他软件里，对应入口可能是 “使用 Google 登录” 或 “微信登录”。

image-20250702210408529

跳转到认证中心后，一般都会提示你确认登录，并说明应用将获取哪些信息。在懒猫微服里直接点击 Grant Access 即可；在其他 IdP 中，通常需要先输入账号密码，再同意该网站访问邮箱、昵称等基本信息。

image-20250702210333539

在授权码模式下，IdP 验证完用户身份后，会先向应用返回一次性授权码。应用后端再用授权码换取 Access Token 和 ID Token，其中 ID Token 通常采用 JWT（JSON Web Token） 格式。应用验证 JWT 后即可确认用户身份。调试时也可以使用 jwt.io 或 jwt.ms 查看 Token 中的声明，但不要上传真实的生产 Token。

我解码了其中一个 ID Token，可以看到签名算法、签发者、过期时间和用户信息等声明。

image-20250702212449226

这和常见的 Token 登录流程有些相似：应用完成登录后获得 Token，后续请求再携带 Bearer Token 访问受保护资源。OIDC 在此基础上还规定了身份声明、发现端点和 Token 校验方式。

7aed62612920d1042f175cb87c1f049e

在 OIDC 流程中，通常会遇到三种 Token：id_token、access_token 和 refresh_token。

  1. Access Token 用于访问受保护的资源 API。用户完成认证和授权后，IdP 会向应用签发 Access Token，应用随后携带 Access Token 请求资源 API。

  2. ID Token 相当于用户的身份凭证，开发者的前端访问后端接口时可以携带 ID Token，开发者服务器可以校验用户的 ID Token 以确定用户身份，验证通过后返回相关资源。

Access Token 和 ID Token 的有效时间通常较短。用户访问资源时需要携带 Access Token；Access Token 过期后，应用需要获取新的 Access Token。Access Token 是否采用 JWT 格式取决于 IdP 的实现，不能一概而论。

  1. Refresh Token 用于在 Access Token 过期后申请新的 Token。这样既可以缩短 Access Token 的有效期，又不必频繁要求用户重新登录。是否签发 Refresh Token，以及刷新时会返回哪些 Token，取决于 IdP 配置和授权范围。

简单来说，Access Token 用于访问资源，ID Token 用于表达用户身份，Refresh Token 用于申请新的 Token。三者用途不同，不能混用。

在懒猫微服上使用 OIDC 有一个好处就是，不用在 IDP 上填写申请信息，在程序运行过程中可以直接注入相应的环境变量，这样我们直接用就可以了。相当于传统 IDP 需要填写应用名称，做分组控制而言，这个自动注入的 OIDC 开箱即用很方便。

一般是有这几个信息：

  1. CLIENT_ID：从我的 App 来看，这个就是包名
  2. CLIENT_SECRET：这个是随机生成的
  3. ISSUER_URI：https://微服域名/sys/oauth
  4. TOKEN_URI：https://微服域名/sys/oauth/token
  5. USERINFO_URI：https://微服域名/sys/oauth/userinfo

先说 ISSUER_URI，这是 OIDC 的入口。通过 .well-known/openid-configuration 可以获取各类端点 URL；即使环境变量没有直接提供，也可以在这里查询，例如用于校验 JWT 的 jwks_uri。

请求 GET https://<微服域名>/sys/oauth/.well-known/openid-configuration，结果如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "issuer": "https://<name>.heiyu.space/sys/oauth",
  "authorization_endpoint": "https://<name>.heiyu.space/sys/oauth/auth",
  "token_endpoint": "https://<name>.heiyu.space/sys/oauth/token",
  "jwks_uri": "https://<name>.heiyu.space/sys/oauth/keys",
  "userinfo_endpoint": "https://<name>.heiyu.space/sys/oauth/userinfo",
  "device_authorization_endpoint": "https://<name>.heiyu.space/sys/oauth/device/code",
  "introspection_endpoint": "https://<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"
  ]
}

至于回调 URL，这是需要自己设置的部分。不同应用的回调 URL 可能不同。相对于在 IdP 中填写信息，在懒猫微服的 lzc-manifest.yml 中加这么一行即可。只有设置了 application.oidc_redirect_path，才能使用 OIDC 相关的环境变量。

1
application.oidc_redirect_path: /callback

可以看看我的懒猫 ENV 查看器配置：通过 oidc_redirect_path 设置回调地址，再使用 environment 字段声明需要的环境变量。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
lzc-sdk-version: 0.1
name: 懒猫ENV查看器
package: xu.deploy.env
version: 0.0.2
description:
license: https://choosealicense.com/licenses/mit/
homepage:
author: xu
application:
  subdomain: env
  oidc_redirect_path: /callback
  routes:
    - /=exec://5005,./lzcapp/pkg/content/run.sh
  environment:
    - LAZYCAT_AUTH_OIDC_CLIENT_ID=${LAZYCAT_AUTH_OIDC_CLIENT_ID}
    - LAZYCAT_AUTH_OIDC_CLIENT_SECRET=${LAZYCAT_AUTH_OIDC_CLIENT_SECRET}
    - LAZYCAT_AUTH_OIDC_AUTH_URI=${LAZYCAT_AUTH_OIDC_AUTH_URI}
    - LAZYCAT_AUTH_OIDC_TOKEN_URI=${LAZYCAT_AUTH_OIDC_TOKEN_URI}
    - LAZYCAT_AUTH_OIDC_USERINFO_URI=${LAZYCAT_AUTH_OIDC_USERINFO_URI}
    - LAZYCAT_AUTH_OIDC_ISSUER_URI=${LAZYCAT_AUTH_OIDC_ISSUER_URI}

然后我们来看 OIDC 的几种授权模式。

应用类型授权模式
有后端的 Web 应用授权码模式
SPA / 原生应用授权码模式 + PKCE
服务器之间Client Credentials

早期资料经常介绍隐式模式，但现在的 Web 应用通常优先使用授权码模式；不能安全保存客户端密钥的 SPA 或原生应用，则应配合 PKCE。后面的回调 URL 带有一次性 code，也能看出懒猫微服使用的是授权码模式。

根据客户端类型、源码可见性和终端用户选择 OAuth 2.0 授权模式

懒猫微服使用的也是授权码模式，所以跳转时抓取浏览器请求会看到：

1
https://url/callback?code=xxxx

其实一个良好的 OIDC 流程是这样的：

  1. 当访问没有权限的路由的时候，在路由守卫中重定向到登录页面。

  2. 当用户登录时，浏览器会跳转到对应的 IdP 页面，由 IdP 验证用户凭证。

  3. 认证通过后，IdP 会向应用的回调地址返回一次性 code。

  4. 应用后端使用授权码 code 换取 Access Token、ID Token，以及可能签发的 Refresh Token。授权码模式把真正的 Token 留在后端交换，只在浏览器重定向中暴露一次性授权码，从而降低 Token 泄露和被滥用的风险。

  5. 最后再使用 Access Token 访问受保护资源。

OIDC 授权码流程：用户授权、Code 换取 Token，再访问受保护资源

以上是懒猫微服 OpenID Connect（OIDC）的理论部分，后面会继续实操，创建一个能够接入 OIDC 的应用。

备注：关于部分 OIDC 的图文来自 Authing 文档。

https://docs.authing.cn/v2/concepts/oidc/choose-flow.html

忘机山人二维码

扫码关注「忘机山人」