1. 前言

随着企业的发展，所使用的系统数量逐渐增多，用户在使用不同系统时需要频繁登录，导致用户体验较差。单点登录（Single Sign-On，简称 SSO）正是为了解决这一问题。当用户登录一次后，即可获取所有系统的访问权限，不需要对每个单一系统逐一登录。

目前，SSO 的实现方案常见有以下几种：

基于 JWT：JWT（JSON Web Token）是一种用于在各方之间安全传递信息的开放标准，令牌中包含用户的身份信息和权限。然而，JWT 用于 SSO 时缺乏标准化方案，导致集成复杂，且令牌一旦签发无法撤销，可能影响安全性。
基于 CAS：CAS（Central Authentication Service）是一种基于中间件的开源单点登录解决方案，通常用于大学和大型企业。用户在一处登录后即可无缝访问所有与 CAS 集成的应用。但其实现较为复杂，对系统集成要求较高。
基于 SAML：SAML（Security Assertion Markup Language）是一种协议，用于在应用程序与 SSO 服务之间交换身份验证信息。它使用 XML 来交换用户标识数据，提供高安全性和灵活性，但配置和实施较为复杂，增加了开发和维护成本。
基于 OIDC：OIDC（OpenID Connect）是基于 OAuth 2.0 的身份验证层，允许用户通过多种客户端（如 Web 应用、移动应用等）进行身份验证。OIDC 具有标准化、简单易用、灵活性和安全性等优点，成为许多企业在实现单点登录时的首选。

OIDC 还有广泛第三方服务提供商的支持，如支付宝、钉钉、微信、GitHub 等。例如下图中 Sealos 应用的登录页面，可以跳转 Github，微信和 Google 进行第三方登录，使用的就是 OIDC 身份认证：

Higress 网关作为后端服务所有请求的入口，可以集成 OIDC 实现统一认证服务，所有后端服务不需要各自实现用户认证逻辑，而是统一通过网关进行用户身份的验证。这样简化了系统架构，减少了重复工作，并提高了安全性。用户在网关配置 OIDC 认证鉴权，可以实现对资源的细粒度访问控制。并且可以方便地对接自建的身份认证服务，或者社交媒体账号等其他第三方账户登录，增强了业务的便利性。

基于此，我们实现了 OIDC 插件让用户在 Higress 网关可以零代码实现 SSO 单点登录。

2. OIDC 插件使用

2.1 后端样例服务部署

参考 Istio Bookinfo^[^1]样例在集群中部署后端样例服务，用来调试 OIDC 插件功能，部署好之后可以通过下面的命令验证是否部署成功。

kubectl exec "$(kubectl get pod -l app=ratings -o jsonpath='{.items[0].metadata.name}')" -c ratings -- curl -sS productpage:9080/productpage | grep -o "<title>.*</title>"

2.2 通过自建身份服务使用 OIDC 插件

配置示例

部署 keycloak 身份认证服务

参考 keycloak-getting-started-docker^[^2]使用 docker 快速部署 keycloak 身份认证服务，添加用户并创建 client。

🔔 注：需填写 Valid redirect URIs，Valid post logout URIs，Web origins 配置项，否则 OIDC Provider 会认为用户跳转的重定向 URL 或登出 URL 无效。

Higress 服务配置

在 Higress 服务来源中创建 Keycloak 固定地址服务。

Wasm 插件配置

redirect_url: 'http://foo.bar.com/oauth2/callback'
oidc_issuer_url: 'http://127.0.0.1:9090/realms/myrealm'
client_id: 'XXXXXXXXXXXXXXXX'
client_secret: 'XXXXXXXXXXXXXXXX'
scope: 'openid email'
cookie_secret: 'nqavJrGvRmQxWwGNptLdyUVKcBNZ2b18Guc1n_8DCfY='
service_name: 'keycloak.static'
service_port: 80
service_host: '127.0.0.1:9090'

插件效果演示

访问服务页面，未登陆的话进行跳转。

登陆成功跳转到服务页面。

访问登出跳转到登出页面。

http://foo.bar.com/oauth2/sign_out?rd=http%3A%2F%2F127.0.0.1:9090%2Frealms%2Fmyrealm%2Fprotocol%2Fopenid-connect%2Flogout

访问登出跳转到登出页面（携带 post_logout_redirect_uri 参数跳转指定 uri）。

http://foo.bar.com/oauth2/sign_out?rd=http%3A%2F%2F127.0.0.1:9090%2Frealms%2Fmyrealm%2Fprotocol%2Fopenid-connect%2Flogout%3Fpost_logout_redirect_uri%3Dhttp%3A%2F%2Ffoo.bar.com%2Ffoo

2.3 通过第三方服务提供商使用 OIDC 插件

配置示例

配置阿里云 OAuth 应用

参考 Web 应用登录阿里云^[^3]流程配置 OAuth 应用。

Higress 服务配置

为了让插件能够访问到 OIDC 服务提供商，需要在 Higress 服务来源中创建 Aliyun DNS 服务。

插件参数配置

redirect_url: 'http://foo.bar.com/oauth2/callback'
provider: aliyun
oidc_issuer_url: 'https://oauth.aliyun.com/'
client_id: 'XXXXXXXXXXXXXXXX'
client_secret: 'XXXXXXXXXXXXXXXX'
scope: 'openid'
cookie_secret: 'nqavJrGvRmQxWwGNptLdyUVKcBNZ2b18Guc1n_8DCfY='
service_name: 'aliyun.dns'
service_port: 443

插件效果演示

访问服务页面，未登陆的话进行跳转。

扫码登陆成功跳转到服务页面。

访问登出跳转到登出页面（阿里云登出后会重定向到登录页）。

http://foo.bar.com/oauth2/sign_out?rd=https%3A%2F%2Faccount.aliyun.com%2Flogout%2Flogout.htm

3. OIDC 插件方案选型

3.1 Istio Sidecar 容器方案

Istio 社区提出了使用 Sidecar 容器部署外部授权^[4]，例如 Istio OIDC Authentication with OAuth2-Proxy^[^5]中提到的部署成熟的 oauth2-proxy 方案，但是这种方案的缺陷首先是在外部授权服务与数据面之间会多一层请求调用，导致性能上会差，其次是外部授权服务会占用一定的 CPU 资源和内存资源，并且如果用户的需要配置多个服务提供商，这个方案也需要部署多个外部授权，因此这个方案灵活性不够强。

3.2 Envoy Filter 方案

现有 Envoy 社区开发的 C++ 原生的 OAuth2 Filter^[6]也可以实现 OIDC 身份认证的功能，目前社区正在积极开发中，Envoy 社区的 envoy gateway^[^7]项目使用了该方案，现有的问题是不支持 OIDC 协议标准的 state 参数（Issue 35232^[^8]）导致受 CSRF 攻击威胁，并且不支持对 cookie 中的令牌进行加密（Issue 23508^[^9]），因此这个方案存在安全漏洞导致 OAuth2 Filter 无法在生产环境中使用。

3.3 Wasm 插件方案

开源的 Higress 项目插件开发框架^[^10]提供了多种编程语言包括 Rust，C++，Golang 和 AssemblyScript（TypeScript 的 Wasm 方言）等编写 Wasm 插件，相比于 C++ 的生态，Rust，Go，TypeScript 等语言的开源库生态更丰富，其中开源的实现了 OIDC 功能的项目如下：

Golang：oauth2-proxy^[^11]
Rust：oauth2-rs^[^12]
TypeScript：angular-oauth2-oidc^[1^3]

其中 oauth2-proxy 项目在开源社区中得到了广泛的使用和验证，同时拥有最活跃的社区支持，发布频繁的更新和改进，实现了大部分常见的 OIDC 服务提供商，也是目前 Istio Sidecar 容器方案中推荐的。Wasm 插件方案的优势体现在以下三个方面：

生产可用性：OIDC 协议涉及身份认证，稳定性和安全性至关重要。基于成熟的开源项目二次开发的插件，通常具有更高的可靠性
可扩展性：不同企业实现 OIDC 协议时不一定会完全遵循标准，企业用户可以基于开源的插件代码进行二次开发，实现企业定制化的需求。
安全性：插件运行在严格的沙箱虚拟环境中，即使代码出现异常也不会使得 Envoy 崩溃。

因此基于以上优势并考虑到前两个方案的灵活性不够强和安全漏洞问题，选择开发 Wasm 插件实现 OIDC 功能。

4. OIDC 插件原理

OIDC 插件基于 oauth2-proxy 项目的核心流程实现，由于在 Envoy 插件中发起外部请求需要通过异步调用，因此将 oauth2-proxy 项目的主流程中的同步调用改为跟 Envoy 中外部服务的异步调用，在回调函数中对响应进行处理，具体的代码参考 Higress 中的 OIDC 插件^[14]，OIDC 插件的请求响应流程如图所示。

1. 模拟用户访问对应服务 api。

curl --url "foo.bar.com/headers"

2. Higress 重定向到 OIDC Provider 登录页同时携带 client_id、response_type、scope 等 OIDC 认证的参数并设置 csrf cookie 防御 CSRF 攻击。

curl --url "https://dev-o43xb1mz7ya7ach4.us.auth0.com/authorize"\
  --url-query "approval_prompt=force" \
  --url-query "client_id=YagFqRD9tfNIaac5BamjhsSatjrAnsnZ" \
  --url-query "redirect_uri=http%3A%2F%2Ffoo.bar.com%2Foauth2%2Fcallback" \
  --url-query "response_type=code" \
  --url-query "scope=openid+email+offline_access" \
  --url-query "state=nT06xdCqn4IqemzBRV5hmO73U_hCjskrH_VupPqdcdw%3A%2Ffoo" \
  --header "Set-Cookie: _oauth2_proxy_csrf=LPruATEDgcdmelr8zScD_ObhsbP4zSzvcgmPlcNDcJpFJ0OvhxP2hFotsU-kZnYxd5KsIjzeIXGTOjf8TKcbTHbDIt-aQoZORXI_0id3qeY0Jt78223DPeJ1xBqa8VO0UiEOUFOR53FGxirJOdKFxaAvxDFb1Ok=|1718962455|V1QGWyjQ4hMNOQ4Jtf17HeQJdVqHdt5d65uraFduMIU=; Path=/; Expires=Fri, 21 Jun 2024 08:06:20 GMT; HttpOnly"

3. 用户在登录页进行登录。

4. 携带授权重定向到 Higress 并携带了 state 参数用于验证 CSRF Cookie，授权 code 用于交换 Token。

curl --url "http://foo.bar.com/oauth2/callback" \
  --url-query "state=nT06xdCqn4IqemzBRV5hmO73U_hCjskrH_VupPqdcdw%3A%2Ffoo" \
  --url-query "code=0bdopoS2c2lx95u7iO0OH9kY1TvaEdJHo4lB6CT2_qVFm"

5. 利用授权交换 id_token 和 access_token。

curl -X POST \
  --url "https://dev-o43xb1mz7ya7ach4.us.auth0.com/oauth/token" \
  --data "grant_type=authorization_code" \
  --data "client_id=YagFqRD9tfNIaac5BamjhsSatjrAnsnZ" \
  --data "client_secret=ekqv5XoZuMFtYms1NszEqRx03qct6BPvGeJUeptNG4y09PrY16BKT9IWezTrrhJJ" \
  --data "redirect_uri=http%3A%2F%2Ffoo.bar.com%2Foauth2%2Fcallback" \
  --data "code=0bdopoS2c2lx95u7iO0OH9kY1TvaEdJHo4lB6CT2_qVFm" \

返回的请求里包含了 id_token，access_token，refresh_token 用于后续刷新 access_token。

{
    "access_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiaXNzIjoiaHR0cHM6Ly9kZXYtbzQzeGIxbXo3eWE3YWNoNC51cy5hdXRoMC5jb20vIn0..WP_WRVM-y3fM1sN4.fAQqtKoKZNG9Wj0OhtrMgtsjTJ2J72M2klDRd9SvUKGbiYsZNPmIl_qJUf81D3VIjD59o9xrOOJIzXTgsfFVA2x15g-jBlNh68N7dyhXu9237Tbplweu1jA25IZDSnjitQ3pbf7xJVIfPnWcrzl6uT8G1EP-omFcl6AQprV2FoKFMCGFCgeafuttppKe1a8mpJDj7AFLPs-344tT9mvCWmI4DuoLFh0PiqMMJBByoijRSxcSdXLPxZng84j8JVF7H6mFa-dj-icP-KLy6yvzEaRKz_uwBzQCzgYK434LIpqw_PRuN3ClEsenwRgIsNdVjvKcoAysfoZhmRy9BQaE0I7qTohSBFNX6A.mgGGeeWgugfXcUcsX4T5dQ",
    "refresh_token": "GrZ1f2JvzjAZQzSXmyr1ScWbv8aMFBvzAXHBUSiILcDEG",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6Imc1Z1ExSF9ZbTY0WUlvVkQwSVpXTCJ9.eyJlbWFpbCI6IjE2MDExNTYyNjhAcXEuY29tIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJpc3MiOiJodHRwczovL2Rldi1vNDN4YjFtejd5YTdhY2g0LnVzLmF1dGgwLmNvbS8iLCJhdWQiOiJZYWdGcVJEOXRmTklhYWM1QmFtamhzU2F0anJBbnNuWiIsImlhdCI6MTcxOTE5ODYzOCwiZXhwIjoxNzE5MjM0NjM4LCJzdWIiOiJhdXRoMHw2NjVkNzFlNzRjMTMxMTc3YmU2NmU2MDciLCJzaWQiOiJjdDJVOF9ZUS16VDdFOGkwRTNNeUstejc5ZGlWUWhhVSJ9.gfzXKJ0FeqzYqOUDLQHWcUG19IOLqkpLN09xTmIat0umrlGV5VNSumgWH3XJmmwnhdb8AThH3Jf-7kbRJzu4rM-BbGbFTRBTzNHeUajFOFrIgld5VENQ_M_sXHkTp0psWKSr9vF24kmilCfSbvC5lBKjt878ljZ7-xteWuaUYOMUdcJb4DSv0-zjX01sonJxYamTlhji3M4TAW7VwhwqyZt8dBhVSNaRw1wUKj-M1JrBDLyx65sroZtSqVA0udIrqMHEbWYb2de7JjzlqG003HRMzwOm7OXgEd5ZVFqgmBLosgixOU5DJ4A26nlqK92Sp6VqDMRvA-3ym8W_m-wJ_A",
    "scope": "openid email offline_access",
    "expires_in": 86400,
    "token_type": "Bearer"
}

6. 将获得的 id_token 和 access_token 加密存储在 Cookie _oauth2_proxy 中，用于后续用户登录状态的验证，同时清除 Cookie _oauth2_proxy_csrf。

"Set-Cookie": [
    "_oauth2_proxy_csrf=; Path=/; Expires=Mon, 24 Jun 2024 02:17:39 GMT; HttpOnly",
    "_oauth2_proxy=8zM_Pcfpp_gesKFe4SMg08o5Iv0A8WAOQOmG1-vZBbQ56UggYVC0Cu-gFMEoxJZU5q1O5vqRlVBizlLetgVjRCksGVbttwl8tQ7h5YiyIubbbtvF1T4JzLh3QfzUUrwbB-VznOkh8qLbjAhddocecjBt4rMiDyceKXqMr4eO5TUEMx4vHtJYnTYalMeTYhGXk5MNSyrdZX9NnQnkdrCjiOQM13ggwob2nYwhGWaAlgzFSWkgkdtBy2Cl_YMWZ8_gKk9rDX289-JrJyGpr5k9O9RzRhZoY2iE3Mcr8-Q37RTji1Ga22QO-XkAcSaGqY1Qo7jLdmgZTYKC5JvtdLc4rj3vcbveYxU7R3Pt2vEribQjKTh4Sqb0aA03p4cxXyZN4SUfBW1NAOm4JLPUhKJy8frqC9_E0nVqPvpvnacaoQs8WkX2zp75xHoMa3SD6KZhQ5JUiPEiNkOaUsyafLvht6lLkNDhgzW3BP2czoe0DCDBLnsot0jH-qQpMZYkaGr-ZnRKI1OPl1vHls3mao5juOAW1VB2A9aughgc8SJ55IFZpMfFMdHdTDdMqPODkItX2PK44GX-pHeLxkOqrzp3GHtMInpL5QIQlTuux3erm3CG-ntlUE7JBtN2T9LEb8XfIFu58X9_vzMun4JQlje2Thi9_taI_z1DSaTtvNNb54wJfSPwYCCl4OsH-BacVmPQhH6TTZ6gP2Qsm5TR2o1U2D9fuVkSM-OPCG9l3tILambIQwC3vofMW6X8SIFSmhJUDvN7NbwxowBiZ6Y7GJRZlAk_GKDkpsdrdIvC67QqczZFphRVnm6qi-gPO41APCbcO6fgTwyOhbP3RrZZKWSIqWJYhNE3_Sfkf0565H7sC7Hc8XUUjJvP3WnjKS9x7KwzWa-dsUjV3-Q-VNl-rXTguVNAIirYK-qrMNMZGCRcJqcLnUF0V_J2lVmFyVsSlE3t0sDw2xmbkOwDptXFOjQL5Rb4esUMYdCBWFajBfvUtcZEFtYhD0kb6VcbjXO3NCVW5qKh_l9C9SRCc7TG1vcRAqUQlRXHacTGWfcWsuQkCJ3Mp_oWaDxs1GRDykQYxAn5sTICovThWEU2C6o75grWaNrkj5NU-0eHh3ryvxLmGLBOXZV9OQhtKShWmUgywSWMxOHOuZAqdAPULc8KheuGFjXYp-RnCbFYWePJmwzfQw89kSkj1KUZgMYwKEjSz62z2qc9KLczomv76ortQzvo4Hv9kaW6xVuQj5R5Oq6_WMBOqsmUMzcXpxCIOGjcdcZRBc0Fm09Uy9oV1PRqvAE4PGtfyrCaoqILBix8UIww63B07YGwzQ-hAXDysBK-Vca2x7GmGdXsNXXcTgu00bdsjtHZPDBBWGfL3g_rMAXr2vWyvK4CwNjcaPAmrlF3geHPwbIePT0hskBboX1v1bsuhzsai7rGM4r53pnb1ZEoTQDa1B-HyokFgo14XiwME0zE1ifpNzefjpkz1YY2krJlqfCydNwoKaTit4tD2yHlnxAeFF9iIrxzSKErNUFpmyLa7ge7V33vhEH-6k5oBTLE2Q2BrC6aAkLCcPwU9xv_SzBDQPRY0MEYv3kGF03Swo1crRbGh-aifYX9NiHDsmG6r1vAnx0MAOw2Jzuz2x6SSdfBrzlcoWBlrwiZzd9kAKq75n1Uy9uzZ8SRnkBrEZySHBwEbu196VklkRE0jqwC-e3wWNNuviSOfwkVeX-7QdOoO10yw9VK2sW52lFvIEf4chv_ta7bGfAZOWBjpktG6ZLD81SE6A88zpqG2SysSyNMp9hl-umG-5sFsjCn_c9E8bDvwkUOUVb9bNqhBDsZgR0BNPawiOZjmyfhzmwmWf-zgFzfFSV6BvOwNRi3sCOHTsWcuk9NBQ_YK8CpNkVl3WeIBSDfidimuC_QV9UWKs1GPk35ZRkM4zKtLY2JsBFWKaDy_P80TcOzcMBoP8gIBClXZ-WUqfE8s1yyc4jrq-qL1_wJ24ef1O9FktsbyZiDKXw2vnqsT8-g_hCeG-unrT1ZFscf8oNdqczARHX-K4vKH2k3uIqEx1M=|1719199056|2rsgdUIClHNEpxBLlHOVRYup6e4oKensQfljtmn4B80=; Path=/; Expires=Mon, 01 Jul 2024 03:17:36 GMT; HttpOnly"
]

7. 携带 Authorization 的标头对应 access_token 访问对应 api。

curl --url "foo.bar.com/headers"  
--header "Authorization: Bearer eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiaXNzIjoiaHR0cHM6Ly9kZXYtbzQzeGIxbXo3eWE3YWNoNC51cy5hdXRoMC5jb20vIn0..WP_WRVM-y3fM1sN4.fAQqtKoKZNG9Wj0OhtrMgtsjTJ2J72M2klDRd9SvUKGbiYsZNPmIl_qJUf81D3VIjD59o9xrOOJIzXTgsfFVA2x15g-jBlNh68N7dyhXu9237Tbplweu1jA25IZDSnjitQ3pbf7xJVIfPnWcrzl6uT8G1EP-omFcl6AQprV2FoKFMCGFCgeafuttppKe1a8mpJDj7AFLPs-344tT9mvCWmI4DuoLFh0PiqMMJBByoijRSxcSdXLPxZng84j8JVF7H6mFa-dj-icP-KLy6yvzEaRKz_uwBzQCzgYK434LIpqw_PRuN3ClEsenwRgIsNdVjvKcoAysfoZhmRy9BQaE0I7qTohSBFNX6A.mgGGeeWgugfXcUcsX4T5dQ"

8. 后端服务根据 access_token 获取用户信息并返回对应的 Http 响应。

{
    "email": "******",
    "email_verified": false,
    "iss": "https://dev-o43xb1mz7ya7ach4.us.auth0.com/",
    "aud": "YagFqRD9tfNIaac5BamjhsSatjrAnsnZ",
    "iat": 1719198638,
    "exp": 1719234638,
    "sub": "auth0|665d71e74c131177be66e607",
    "sid": "ct2U8_YQ-zT7E8i0E3MyK-z79diVQhaU"
}

5. 总结

本文对 Higress 中开源的 OIDC Wasm 插件进行了介绍，现在 Higress 项目中 Wasm 插件支持使用 Go、C++、Rust、AssemblyScript 等语言编写，后续会支持更多的编程语言，有着更低的开发门槛，同时 Wasm 插件运行在隔离的沙箱环境中，具有更高的安全性，而 Wasm 本身作为一种高性能的可移植二进制指令格式不断的有新的进展和技术革新，未来网关场景的更多功能均可以考虑在 Wasm 插件中实现。

本文中的 OIDC Wasm 插件已在 Higress 项目中开源

欢迎大家在 github 社区提出宝贵的建议，或者在 Higress 社区交流群（钉钉群号：30735012403）里一起沟通。

相关链接：

[1] Istio Bookinfo

[2] keycloak-getting-started-docker

[3] Web 应用登录阿里云

[4] 外部授权

[5] Istio OIDC Authentication with OAuth2-Proxy

[6] OAuth2 Filter

[7] envoy gateway

[8] Issue 35232

[9] Issue 23508