Cognito token exchange: log into Kill Bill with the Bearer token (no KB password) and move the exchange into Kaui
@tungleduyxyz 已经在做这个了。
开始于 2026年11月16日。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 12/100
- Issue 类型
- 功能
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- ansible, aws, rails, ruby
- 领域
- api, authentication, backend
调研方向
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!):
- Verify the Cognito ID token (JWKS,
iss, a singleaudfromkaui.cognito.client_id,token_use,email). - Require
kb_username/kb_passwordfrom 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. - Store the KB session id in
kaui_users, keyed bykb_username(defaults to the token's email). - Select the tenant from
kaui_allowed_users/kaui_allowed_user_tenants, keyed bykb_username(tenant_namedisambiguates).
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/exchangeas an alias so existing clients keep working. killbill/managedthen removes its copies ofsso_aviate_controller.rb,cognito_jwt_verifier.rb,kb_cognito_authenticatable.rband the route injection. Its demo-onlygetting_startedcontrollers stay inmanagedand 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_passwordpresent → basic, unchanged.kb_passwordabsent → bearer:Kaui::User.find_permissions(bearer: token).killbill-client-rubyalready sendsAuthorization: Bearerfor thebearer:option (Kaui's Auth0 strategy uses it). Kill Bill creates the session on/1.0/kb/security/permissionsas for Basic; later Kaui calls useJSESSIONIDas today.- KB answers 401 (no Cognito realm on that Kill Bill) → return
401with 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_usernameasX-Killbill-CreatedBy, so audit logs showcognito:[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:
- Finds the tenant in
kaui_tenantsbyapi_keyand checks the secret againstencrypted_api_secret. Prerequisite: the tenant is known to Kaui (row inkaui_tenants), as today. - Unknown tenant or wrong secret →
403with a clear error; no tenant is selected. - Match → select the tenant in the session, and create (idempotently) the
kaui_allowed_usersrow for the principal plus thekaui_allowed_user_tenantslink, 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_usernameiscognito:<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/exchangestill works on the managed sandbox.
- 主要语言
- HTML
- 星标
- 70
- 派生
- 76
- 平均合并
- 1 天 23 小时
- 30 天内合并 PR
- 5
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 没有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
killbill/killbill-admin-ui 的其他 Issue
-
Show invoice amount and balance on the account invoices page without losing pagination可能已有人在做 @tungleduyxyz 于 15 天前认领。 未关闭
难度 4/5 3-5 天 新手友好度 55/100
killbill/killbill-admin-ui#678 · 1 条评论 · 已指派 1 人 ·
-
难度 3/5 1-2 天 新手友好度 50/100
killbill/killbill-admin-ui#663 · 1 条评论 ·
-
难度 3/5 1-2 天 新手友好度 55/100
killbill/killbill-admin-ui#662 ·
-
Kaui 4.0.1 - viewing catalog可能重新可做 @tungleduyxyz 于 367 天前认领,目前没有进行中的 PR。 未关闭enhancement
killbill/killbill-admin-ui#556 · 5 条评论 · 已指派 1 人 ·
-
难度 5/5 一周以上 新手友好度 15/100
killbill/killbill-admin-ui#86 · 1 条评论 ·
查看 killbill/killbill-admin-ui 的全部 Issue
相似的 Issue
-
bug ready-for-human
难度 2/5 1-3 小时 新手友好度 72/100
BoardGamesEmpire/board-games-empire-backend#1452 · 1 条评论 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 76/100
维护者通常 1 天内回复
-
Bug Tests
难度 2/5 1-3 小时 新手友好度 78/100
JSPrismarine/JSPrismarine#3384 ·
维护者通常 1 天内回复
-
difficulty: easy enhancement quality
难度 2/5 1-3 小时 新手友好度 84/100
维护者通常 2 天内回复
-
难度 2/5 1-3 小时 新手友好度 68/100
blowhorn-ai/blowhorn-mcp#70 ·
维护者通常 1 天内回复