Cognito token exchange: log into Kill Bill with the Bearer token (no KB password) and move the exchange into Kaui

未关闭
#682 0 条评论 0 个 reaction 已指派 1 人 在 GitHub 查看

@tungleduyxyz 已经在做这个了。

开始于 2026年11月16日。

评估

难度
5/5
预计耗时
一周以上
新手友好度
12/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
活跃
技术栈
ansible, aws, rails, ruby

调研方向

Start with the current exchange overlay in killbill/managed: ansible/files/kaui/controllers/sso_aviate_controller.rb, services/kb_cognito_authenticatable.rb and services/cognito_jwt_verifier.rb, plus the route injection. Trace authenticate_kb_user! to see the Basic login path. This is a multi-part design change, so agree the scope with maintainers before coding. Done means both the basic and bearer modes pass the acceptance list.

由索引模型根据 Issue 内容生成。

描述

Context

An external web application whose users sign in with AWS Cognito can open Kaui for the user without a second login through a token exchange endpoint, POST /sso/aviate/exchange. The client sends the user's Cognito ID token; Kaui logs the user into Kill Bill, stores the Kill Bill session, selects the tenant and returns a redirect URL.

Today this endpoint is not part of Kaui: it is an overlay in killbill/managed (ansible/files/kaui/controllers/sso_aviate_controller.rb, services/kb_cognito_authenticatable.rb, services/cognito_jwt_verifier.rb) that Ansible copies into the installed Kaui WAR and wires into routes.rb. It therefore only exists on the Kaui instances deployed by managed (sandbox, demo), not on stock Kaui.

Current flow (KbCognitoAuthenticatable#authenticate_kb_user!):

  1. Verify the Cognito ID token (JWKS, iss, a single aud from kaui.cognito.client_id, token_use, email).
  2. Require kb_username/kb_password from the client and log into Kill Bill with Basic auth (Kaui::User.find_permissions(username:, password:)). The token only proves "a signed-in user"; what the user can do comes from the KB credentials.
  3. Store the KB session id in kaui_users, keyed by kb_username (defaults to the token's email).
  4. Select the tenant from kaui_allowed_users / kaui_allowed_user_tenants, keyed by kb_username (tenant_name disambiguates).

Kill Bill now has a Cognito realm (killbill/killbill#2333): Authorization: Bearer <Cognito ID token> is accepted on /1.0/kb/**, the principal is cognito:<claim>, and the permissions come from the token's role claim mapped to a KB role (roles_permissions). The role is kept in the principal collection, so it survives in the KB session (JSESSIONID). This lets users who have no Kill Bill username/password (e.g. members of an organization, SSO users) open Kaui with their own permissions.

Use cases

The client decides per user which mode applies, and Kaui accepts both:

Mode Who Exchange request
basic Users with their own KB username/password, or KB instances without the Cognito realm Bearer ID token + kb_username/kb_password (today's behaviour, unchanged)
bearer Users without KB credentials, on KB instances with the Cognito realm Bearer ID token + tenant api key/secret, no KB username/password

Changes

1. Move the exchange into Kaui

Move the controller and services from killbill/managed into Kaui (killbill-admin-ui) as an optional feature, disabled unless configured (kaui.cognito.issuer + client ids). Otherwise the handoff only works on TBP's own sandbox, not for Kaui deployed by users (AWS Marketplace, self-hosted).

  • Generic route, e.g. POST /sso/cognito/exchange; keep /sso/aviate/exchange as an alias so existing clients keep working.
  • killbill/managed then removes its copies of sso_aviate_controller.rb, cognito_jwt_verifier.rb, kb_cognito_authenticatable.rb and the route injection. Its demo-only getting_started controllers stay in managed and reuse the shared authentication from Kaui (KbCognitoAuthenticatable), so they get the bearer mode for free.
2. Bearer login to Kill Bill

In authenticate_kb_user!:

  • kb_password present → basic, unchanged.
  • kb_password absent → bearer: Kaui::User.find_permissions(bearer: token). killbill-client-ruby already sends Authorization: Bearer for the bearer: option (Kaui's Auth0 strategy uses it). Kill Bill creates the session on /1.0/kb/security/permissions as for Basic; later Kaui calls use JSESSIONID as today.
  • KB answers 401 (no Cognito realm on that Kill Bill) → return 401 with a clear error ("Cognito authentication is not enabled on this Kill Bill"), not a 500.
3. Kaui user key = the Kill Bill principal

For bearer users, key kaui_users (and kaui_allowed_users) by the principal Kill Bill reports (GET /1.0/kb/security/subject), e.g. cognito:[email protected], not by the bare email.

  • Prevents a bearer user [email protected] from sharing the Kaui row, KB session and tenant access of a basic KB user with the same name.
  • The prefix is set by the Kill Bill realm, not by Kaui: Kaui stores whatever principal KB returns, so another realm needs no Kaui change.
  • Kaui uses kb_username as X-Killbill-CreatedBy, so audit logs show cognito:[email protected].
4. Multiple audiences

Accept a list of Cognito app client ids (e.g. kaui.cognito.client_ids, comma-separated; keep reading kaui.cognito.client_id for compatibility). ruby-jwt's aud: option accepts an array. Today tokens from a second app client (e.g. an SSO client) are rejected.

5. Tenant selection from the tenant api key/secret

In bearer mode the client sends the tenant api key + api secret (the user already holds them to call Kill Bill). Kaui:

  1. Finds the tenant in kaui_tenants by api_key and checks the secret against encrypted_api_secret. Prerequisite: the tenant is known to Kaui (row in kaui_tenants), as today.
  2. Unknown tenant or wrong secret → 403 with a clear error; no tenant is selected.
  3. Match → select the tenant in the session, and create (idempotently) the kaui_allowed_users row for the principal plus the kaui_allowed_user_tenants link, so Kaui's tenant screen (TenantsController#index) shows the tenant instead of redirecting to tenant creation.

Basic mode keeps today's selection (kaui_allowed_users by kb_username, tenant_name to disambiguate).

6. JWKS refresh

CognitoJwtVerifier caches the JWKS forever (@jwks_keys ||=), so a Cognito key rotation breaks every exchange until Kaui restarts. Refetch the JWKS when the kid is unknown (rate-limited).

7. Kaui admin screens

Kaui's own admin pages (allowed users, tenants, KB roles) assume KB users. For bearer users, show them only when the KB permissions allow it (e.g. a *:* owner role); menus otherwise follow the KB permissions through CanCan with no change.

Open item: KB session expiry

The KB session expires after 30 minutes of inactivity. Kaui's after_set_user check then sends the user to Kaui's username/password login page, which a bearer user cannot use.

Default behaviour for this issue: for bearer users (principal from the Cognito realm), show a "Your session has expired, reopen Kaui from the application you came from" page instead of the login form.

To decide later: redirect back to the client for a silent re-exchange instead (needs a return URL into the client and a client-side route that repeats the exchange).

Acceptance

  • Basic exchange (token + KB username/password) behaves as today, on the managed sandbox and on stock Kaui with the feature configured.
  • Bearer exchange (token + tenant key/secret) on a KB with the Cognito realm: user lands in Kaui on the right tenant, menus and allowed actions match the role's KB permissions, kaui_users.kb_username is cognito:<email>, audit logs show it.
  • A bearer user and a basic KB user with the same email get separate Kaui rows and sessions.
  • Wrong tenant secret or unknown tenant → 403; KB without the Cognito realm → 401 with a clear message.
  • Tokens from every configured client id are accepted; tokens from other clients are rejected.
  • Cognito key rotation does not require a Kaui restart.
  • After KB session expiry, a bearer user sees the "reopen Kaui" page, not the login form.
  • Feature disabled when not configured; /sso/aviate/exchange still works on the managed sandbox.
主要语言
HTML
星标
70
派生
76
平均合并
1 天 23 小时
30 天内合并 PR
5

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

killbill/killbill-admin-ui 的其他 Issue

查看 killbill/killbill-admin-ui 的全部 Issue

相似的 Issue

更多 Backend & API Design Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。