Cognito token exchange: log into Kill Bill with the Bearer token (no KB password) and move the exchange into Kaui
@tungleduyxyz ya está trabajando en esto.
Desde el 16/11/2026.
Evaluación
- Dificultad
- 5/5
- Tiempo estimado
- Más de una semana
- Aptitud para principiantes
- 12/100
- Tipo de issue
- Nueva funcionalidad
- Claridad
- Bastante claro
- Estado de actividad
- Activo
- Stack tecnológico
- ansible, aws, rails, ruby
- Área
- api, authentication, backend
Línea de trabajo
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.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
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.
- Lenguaje dominante
- HTML
- Estrellas
- 70
- Forks
- 76
- Merge medio
- 1 d 23 h
- PR fusionados (30 d)
- 5
Preparar el entorno
- Sin Dockerfile ni archivo de Docker Compose
- Sin plantilla de pull request
- Leer la guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de killbill/killbill-admin-ui
-
Show invoice amount and balance on the account invoices page without losing paginationPosiblemente ocupada @tungleduyxyz la tomó hace 15 días. Abierto
Dificultad 4/5 3-5 días Aptitud para principiantes 55/100
killbill/killbill-admin-ui#678 · 1 comentario · 1 asignado ·
-
Dificultad 3/5 1-2 días Aptitud para principiantes 50/100
killbill/killbill-admin-ui#663 · 1 comentario ·
-
Dificultad 3/5 1-2 días Aptitud para principiantes 55/100
killbill/killbill-admin-ui#662 ·
-
Kaui 4.0.1 - viewing catalogQuizá libre de nuevo @tungleduyxyz la tomó hace 367 días y no hay ningún pull request abierto. Abiertoenhancement
killbill/killbill-admin-ui#556 · 5 comentarios · 1 asignado ·
-
Dificultad 5/5 Más de una semana Aptitud para principiantes 15/100
killbill/killbill-admin-ui#86 · 1 comentario ·
Todos los issues de killbill/killbill-admin-ui
Issues similares
-
A voting window past about 69.9 million hours stores a deadline that reads back as no deadlineAbiertobug ready-for-human
Dificultad 2/5 1-3 horas Aptitud para principiantes 72/100
BoardGamesEmpire/board-games-empire-backend#1452 · 1 comentario ·
Los mantenedores suelen responder en 1 día
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 76/100
Los mantenedores suelen responder en 1 día
-
parity: scripting.net's net-http row fails on macOS with errno 61 where the BDS golden has 111AbiertoBug Tests
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
JSPrismarine/JSPrismarine#3384 ·
Los mantenedores suelen responder en 1 día
-
difficulty: easy enhancement quality
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100
Los mantenedores suelen responder en 2 días
-
Dificultad 2/5 1-3 horas Aptitud para principiantes 68/100
blowhorn-ai/blowhorn-mcp#70 ·
Los mantenedores suelen responder en 1 día