Cognito token exchange: log into Kill Bill with the Bearer token (no KB password) and move the exchange into Kaui
@tungleduyxyz ci sta già lavorando.
Dal 16/11/2026.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 12/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Attiva
- Stack tecnologico
- ansible, aws, rails, ruby
- Ambito
- api, authentication, backend
Direzione di ricerca
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.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
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.
- Lingua principale
- HTML
- Stelle
- 70
- Fork
- 76
- Merge medio
- 1g 23h
- PR unite (30g)
- 5
Preparare l'ambiente
- Nessun Dockerfile né file Docker Compose
- Nessun modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di killbill/killbill-admin-ui
-
Show invoice amount and balance on the account invoices page without losing paginationForse già presa @tungleduyxyz l’ha presa 15 giorni fa. Aperta
Difficoltà 4/5 3-5 giorni Idoneità per principianti 55/100
killbill/killbill-admin-ui#678 · 1 commento · 1 assegnatario ·
-
Difficoltà 3/5 1-2 giorni Idoneità per principianti 50/100
killbill/killbill-admin-ui#663 · 1 commento ·
-
Difficoltà 3/5 1-2 giorni Idoneità per principianti 55/100
killbill/killbill-admin-ui#662 ·
-
Kaui 4.0.1 - viewing catalogForse di nuovo libera @tungleduyxyz l’ha presa 367 giorni fa e non c’è nessuna pull request aperta. Apertaenhancement
killbill/killbill-admin-ui#556 · 5 commenti · 1 assegnatario ·
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 15/100
killbill/killbill-admin-ui#86 · 1 commento ·
Tutte le issue di killbill/killbill-admin-ui
Issue simili
-
A voting window past about 69.9 million hours stores a deadline that reads back as no deadlineApertabug ready-for-human
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
BoardGamesEmpire/board-games-empire-backend#1452 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 1 giorno
-
parity: scripting.net's net-http row fails on macOS with errno 61 where the BDS golden has 111ApertaBug Tests
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
JSPrismarine/JSPrismarine#3384 ·
I maintainer di solito rispondono entro 1 giorno
-
difficulty: easy enhancement quality
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
I maintainer di solito rispondono entro 2 giorni
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
blowhorn-ai/blowhorn-mcp#70 ·
I maintainer di solito rispondono entro 1 giorno