Cognito token exchange: log into Kill Bill with the Bearer token (no KB password) and move the exchange into Kaui
@tungleduyxyz đang làm issue này rồi.
Từ ngày 16/11/2026.
Đánh giá
- Độ khó
- 5/5
- Thời gian dự kiến
- Hơn một tuần
- Mức phù hợp với người mới
- 12/100
- Loại issue
- Tính năng
- Độ rõ ràng
- Khá rõ ràng
- Mức độ hoạt động
- Sôi nổi
- Công nghệ
- ansible, aws, rails, ruby
- Lĩnh vực
- api, authentication, backend
Hướng nghiên cứu
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.
Do mô hình lập chỉ mục viết ra từ nội dung của issue.
Mô tả
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.
- Ngôn ngữ chính
- HTML
- Star
- 70
- Fork
- 76
- Merge trung bình
- 1 ngày 23 giờ
- Pull request đã merge (30 ngày)
- 5
Chuẩn bị môi trường
- Không có Dockerfile hay tệp Docker Compose
- Không có mẫu pull request
- Đọc hướng dẫn đóng góp
Bắt đầu từ đâu
- Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
- Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
- Fork repository và làm thay đổi trên một nhánh.
- Mở pull request có tham chiếu số hiệu của issue.
Issue khác của killbill/killbill-admin-ui
-
Show invoice amount and balance on the account invoices page without losing paginationCó thể đã có người làm @tungleduyxyz đã nhận 15 ngày trước. Đang mở
Độ khó 4/5 3-5 ngày Mức phù hợp với người mới 55/100
killbill/killbill-admin-ui#678 · 1 bình luận · 1 người được giao ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 50/100
killbill/killbill-admin-ui#663 · 1 bình luận ·
-
Độ khó 3/5 1-2 ngày Mức phù hợp với người mới 55/100
killbill/killbill-admin-ui#662 ·
-
Kaui 4.0.1 - viewing catalogCó thể làm lại được @tungleduyxyz đã nhận 367 ngày trước và không có pull request nào đang mở. Đang mởenhancement
killbill/killbill-admin-ui#556 · 5 bình luận · 1 người được giao ·
-
Độ khó 5/5 Hơn một tuần Mức phù hợp với người mới 15/100
killbill/killbill-admin-ui#86 · 1 bình luận ·
Tất cả issue của killbill/killbill-admin-ui
Issue tương tự
-
parity: scripting.net's net-http row fails on macOS with errno 61 where the BDS golden has 111Đang mởBug Tests
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 78/100
JSPrismarine/JSPrismarine#3384 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
difficulty: easy enhancement quality
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 84/100
Maintainer thường phản hồi trong vòng 2 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 68/100
blowhorn-ai/blowhorn-mcp#70 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 84/100
Automattic/data-liberation-agent#2175 ·
Maintainer thường phản hồi trong vòng 1 ngày
-
bug
Độ khó 2/5 1-3 giờ Mức phù hợp với người mới 85/100
Serial-ATA/lofty-rs#789 ·
Maintainer thường phản hồi trong vòng 1 ngày