@onaio/akuko-embed-sdk 0.1.0

package/docs/sso-path-d-brokering.md

@@ -0,0 +1,156 @@
+# Path D — Keycloak Identity Brokering
+
+**Use this recipe when:** your users authenticate via an identity provider other than Akuko's Keycloak realm. Examples:
+- Another Keycloak realm (e.g., `onadata-realm`, either on the same Keycloak instance as Akuko or a different one)
+- Auth0 / Azure AD / Microsoft Entra ID / Okta / Google Workspace / AWS Cognito
+- Your own OIDC-compliant identity server
+- A SAML 2.0 enterprise IdP (ADFS, Ping, etc.)
+
+Path D works cross-domain by design (uses OIDC redirects, not cookie sharing), so your app and Akuko can live on entirely separate domains.
+
+> **Ops engineers:** for an automated reference of these exact Keycloak steps (idempotent `kcadm.sh` commands you can adapt to your realm), see [`../examples/keycloak-path-d-setup.sh`](../examples/keycloak-path-d-setup.sh) in this package.
+
+## What you don't need to change
+
+- **No code changes in Akuko** — Path D is entirely Keycloak configuration.
+- **No code changes in your host app** — your existing OIDC/SAML login flow keeps working unchanged.
+- **No need to share cookies, domains, or Keycloak instances.**
+
+## One-time setup (Akuko side, per client)
+
+An admin with access to Akuko's Keycloak realm (`akuko-realm`) registers your IdP as a brokered provider.
+
+### Step 1: Add the Identity Provider
+
+1. In `akuko-realm` admin console → Identity Providers → Add Provider → **OpenID Connect v1.0** (or **SAML v2.0** for SAML clients).
+2. **Alias** — a short identifier, e.g., `onadata`, `acme-auth0`, `customer-azure`.
+3. **Redirect URI** — copy this; you'll give it to the upstream IdP in Step 2.
+
+### Step 2: Register the discovery
+
+**For OIDC providers:**
+- Paste your IdP's issuer URL (`https://your-idp.example/realms/your-realm` or `https://your-tenant.auth0.com/` etc.).
+- Keycloak auto-discovers endpoints from `/.well-known/openid-configuration`.
+- Client ID and Client Secret — create an OIDC client on your IdP with the redirect URI from Step 1; supply the credentials here.
+
+**For SAML providers:**
+- Paste the upstream IdP's SAML metadata URL (or upload the metadata XML).
+- Keycloak configures request signing and response validation from the metadata.
+
+### Step 3: Configure claim mappers
+
+For OIDC (similar idea for SAML with attribute mappers):
+
+**Email** (essential):
+- Add an "Attribute Importer" mapper.
+- Claim: `email` (or the equivalent attribute in SAML).
+- User attribute: `email`.
+- Sync mode: `Force` (refresh on every login).
+
+Without this, users will log in but Akuko won't know their email, and RLS rules won't match.
+
+**Groups** (optional, enables group-based RLS):
+- Add a "Claim to Group" mapper (or "Attribute to Group" for SAML).
+- Claim: `groups` (Auth0, Azure AD, Keycloak realms all support this with configuration).
+- Configure how upstream group names translate to akuko-realm groups — either by name match or explicit mapping.
+
+If your IdP doesn't emit groups, skip this — user-level RLS rules still work.
+
+### Step 4: Enable auto-link on email (essential for pre-invited users)
+
+1. Authentication → Flows → duplicate the "First Broker Login" flow so you can edit it.
+2. In the copy, find the **"Detect Existing Broker User"** step.
+3. Set its requirement to **REQUIRED** (or at least ALTERNATIVE that auto-links on a confirmed email match, depending on your security posture).
+4. Attach the copy to your brokered IdP → "First Login Flow" setting.
+
+Effect: when a user arrives via brokering and an `akuko-realm` user with the same email already exists (e.g., because an Akuko admin pre-invited them), Keycloak links the brokered identity to that existing account instead of creating a duplicate.
+
+Without this step, every invited user will become a separate user in `akuko-realm` from their brokered identity, breaking RLS matching.
+
+### Step 5: Tell the SDK which IdP alias to use
+
+The IdP alias you configured in Step 1 ("Alias" field — e.g., `onadata`, `acme-auth0`) is what your host code passes to the SDK as `idpHint`. The SDK appends it to the iframe URL; Akuko's embed page forwards it to Keycloak as `kc_idp_hint`.
+
+Example (React):
+
+```tsx
+<AkukoDashboard
+  dashboardId="..."
+  idpHint="onadata"   // matches the alias from Step 1
+/>
+```
+
+Example (vanilla):
+
+```js
+import { AkukoDashboard } from "@onaio/akuko-embed-sdk";
+
+new AkukoDashboard({
+  container: '#mount',
+  dashboardId: '...',
+  idpHint: 'onadata',
+});
+```
+
+With `idpHint` set, a first-time user never sees a broker-selection UI — they go straight from their host app → Akuko iframe → onadata-realm → back → dashboard. Silent federation.
+
+If your host has multiple user populations (some come from Auth0, some from Azure), pass a different `idpHint` value per user based on your own context.
+
+### Step 6: Test
+
+1. Open a private/incognito browser window.
+2. Hit an Akuko dashboard URL where your test user should have RLS rules.
+3. Expect: a redirect flash to your IdP → immediate return to Akuko (your IdP has an active session, or prompts for login).
+4. Verify the dashboard renders with filters applied.
+
+## Per-client configuration checklist
+
+When onboarding a new integrating client, confirm all these:
+
+- [ ] OIDC or SAML provider registered in `akuko-realm`
+- [ ] Email claim mapper configured and set to `Force` sync mode
+- [ ] (Optional) Groups claim mapper configured and tested
+- [ ] "Detect Existing Broker User" enabled on the First Broker Login flow
+- [ ] Test login from upstream IdP succeeds and lands in Akuko as the expected user
+- [ ] (If pre-invited) invited user account is linked, not duplicated
+- [ ] (If group rules exist) test user with group membership sees group-scoped data
+
+## Example: onadata + Akuko (same Keycloak, different realms)
+
+Given `onadata-realm` and `akuko-realm` on the same Keycloak instance at `https://keycloak.example.internal`:
+
+- **Issuer URL:** `https://keycloak.example.internal/realms/onadata`
+- **Client ID / Secret:** create an OIDC client in `onadata-realm` named e.g. `akuko-broker-client`; supply credentials.
+- **Email claim:** `email` (Keycloak emits this by default if the realm's OIDC client has `email` in its Default Client Scopes).
+- **Groups claim:** requires `onadata-realm` to emit a `groups` claim — configure the client's protocol mapper if not present.
+- **Auto-link:** enable per Step 4.
+
+After this, an onadata user signs in to their onadata app normally, and when they open an Akuko dashboard from there they're authenticated silently (one redirect flash, no password prompt).
+
+For an automated reference of these exact Keycloak steps (creating the IdP, the email Attribute Importer, and the auto-link First Broker Login flow), see [`../examples/keycloak-path-d-setup.sh`](../examples/keycloak-path-d-setup.sh) in this package and adapt it to your realm.
+
+## Example: external SaaS using Auth0
+
+Given a customer runs their app on Auth0 at `https://customer.auth0.com`:
+
+- **Issuer URL:** `https://customer.auth0.com/`
+- **Client ID / Secret:** create an Application in Auth0 of type "Regular Web Application"; get the credentials; add Akuko's redirect URI to Auth0's allowed callback URLs.
+- **Email claim:** `email` (Auth0 emits by default with the `openid email` scopes).
+- **Groups claim:** if their Auth0 emits groups via a custom rule or the Authorization extension, map the `groups` claim.
+- **Auto-link:** enable per Step 4.
+
+Same flow as onadata from there.
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| User lands on Akuko but RLS rules don't apply | Email claim mapper not configured or not in `Force` sync mode; Akuko sees empty email |
+| Brokered user shows up as a new user every login | "Detect Existing Broker User" not enabled on First Broker Login flow |
+| User gets a password prompt instead of silent redirect | Upstream IdP session expired or cookies blocked; not a brokering bug |
+| Group rules don't apply for brokered users | Groups claim not emitted by upstream, or claim mapper missing/misconfigured |
+| Infinite redirect loop | Client credentials wrong, or redirect URI mismatch in upstream IdP's allow-list |
+
+## Scope boundary
+
+Path D is the responsibility of whoever administers Akuko's Keycloak. Individual dashboard owners don't need to understand any of this — once the broker is set up for a given client, that client's users show up as regular users in Akuko's Share modal (searchable by email), and RLS configuration for them works identically to native users.

package/examples/keycloak-path-d-setup.sh

@@ -0,0 +1,173 @@
+#!/usr/bin/env bash
+#
+# Reference only — adapt to your Keycloak. This is a sanitized, parameterized
+# walkthrough of the Path D identity-brokering setup described in
+# ../docs/sso-path-d-brokering.md, expressed as idempotent `kcadm.sh` calls.
+#
+# It configures Akuko's Keycloak realm to trust an UPSTREAM OIDC identity
+# provider (your IdP) so users who authenticate there can open embedded Akuko
+# dashboards via silent federation (the SDK's `idpHint` option). It:
+#   1. authenticates to the Akuko Keycloak admin API
+#   2. clones the "First Broker Login" flow with the verification pages disabled
+#   3. creates an OIDC Identity Provider aliased "$IDP_ALIAS"
+#   4. attaches an email Attribute Importer mapper (Force sync)
+#   5. adds the idp-auto-link authenticator so brokered users auto-link to an
+#      existing Akuko user by matching email — no confirm/verify page (those
+#      can't render inside the cross-origin analytics iframe)
+#
+# Do NOT run this as-is. Fill in the placeholders below for your environment.
+# Akuko's own local development wires an equivalent broker automatically via a
+# make target, so this script is only a reference for external operators.
+#
+set -euo pipefail
+
+# ── Configure these for your environment ───────────────────────────────────
+# Akuko Keycloak admin API + realm:
+KC_ADMIN_URL="${KC_ADMIN_URL:?set to your Akuko Keycloak base URL, e.g. https://keycloak.example.com}"
+KC_ADMIN_USER="${KC_ADMIN_USER:?Keycloak admin username}"
+KC_ADMIN_PASS="${KC_ADMIN_PASS:?Keycloak admin password}"
+AKUKO_REALM="${AKUKO_REALM:-akuko}"
+
+# The brokered IdP, as the SDK's `idpHint` value:
+IDP_ALIAS="${IDP_ALIAS:?short alias for the brokered IdP, e.g. onadata}"
+
+# Upstream OIDC provider (your IdP). The issuer is required; the per-endpoint
+# URLs default to standard Keycloak conventions derived from it. For a NON-
+# Keycloak IdP (Auth0, Azure AD, Okta, …) override each from your IdP's
+# /.well-known/openid-configuration.
+UPSTREAM_ISSUER_URL="${UPSTREAM_ISSUER_URL:?upstream IdP issuer, e.g. https://idp.example.com/realms/your-realm}"
+UPSTREAM_AUTH_URL="${UPSTREAM_AUTH_URL:-$UPSTREAM_ISSUER_URL/protocol/openid-connect/auth}"
+UPSTREAM_TOKEN_URL="${UPSTREAM_TOKEN_URL:-$UPSTREAM_ISSUER_URL/protocol/openid-connect/token}"
+UPSTREAM_USERINFO_URL="${UPSTREAM_USERINFO_URL:-$UPSTREAM_ISSUER_URL/protocol/openid-connect/userinfo}"
+UPSTREAM_JWKS_URL="${UPSTREAM_JWKS_URL:-$UPSTREAM_ISSUER_URL/protocol/openid-connect/certs}"
+UPSTREAM_LOGOUT_URL="${UPSTREAM_LOGOUT_URL:-$UPSTREAM_ISSUER_URL/protocol/openid-connect/logout}"
+
+# OIDC client you created on the upstream IdP, with redirect URI
+#   $KC_ADMIN_URL/realms/$AKUKO_REALM/broker/$IDP_ALIAS/endpoint
+BROKER_CLIENT_ID="${BROKER_CLIENT_ID:?OIDC client id registered on the upstream IdP}"
+BROKER_CLIENT_SECRET="${BROKER_CLIENT_SECRET:?the secret for that OIDC client}"
+
+# kcadm.sh must be on PATH (ships in the Keycloak distribution under bin/).
+KCADM="${KCADM:-kcadm.sh}"
+FBL_FLOW="first broker login - ${IDP_ALIAS}"
+
+# kcadm flow paths need spaces percent-encoded.
+enc_spaces() { printf '%s' "$1" | sed 's/ /%20/g'; }
+
+# ── Step 0: authenticate ───────────────────────────────────────────────────
+"$KCADM" config credentials --server "$KC_ADMIN_URL" \
+  --realm master --user "$KC_ADMIN_USER" --password "$KC_ADMIN_PASS"
+
+# ── Step 1: clone "First Broker Login" (before IdP create — Keycloak validates
+# firstBrokerLoginFlowAlias against existing flows at create time) ──────────
+if "$KCADM" get authentication/flows -r "$AKUKO_REALM" \
+    --fields alias --format csv --noquotes 2>/dev/null | grep -qx "$FBL_FLOW"; then
+  echo "  cloned flow exists already"
+else
+  "$KCADM" create "authentication/flows/first%20broker%20login/copy" \
+    -r "$AKUKO_REALM" -s "newName=$FBL_FLOW"
+  echo "  cloned First Broker Login → '$FBL_FLOW'"
+fi
+
+# ── Step 2: create or update the OIDC Identity Provider ────────────────────
+IDP_PAYLOAD=$(cat <<JSON
+{
+  "alias": "$IDP_ALIAS",
+  "displayName": "$IDP_ALIAS",
+  "providerId": "oidc",
+  "enabled": true,
+  "trustEmail": true,
+  "firstBrokerLoginFlowAlias": "$FBL_FLOW",
+  "config": {
+    "clientId": "$BROKER_CLIENT_ID",
+    "clientSecret": "$BROKER_CLIENT_SECRET",
+    "clientAuthMethod": "client_secret_post",
+    "issuer": "$UPSTREAM_ISSUER_URL",
+    "authorizationUrl": "$UPSTREAM_AUTH_URL",
+    "tokenUrl": "$UPSTREAM_TOKEN_URL",
+    "userInfoUrl": "$UPSTREAM_USERINFO_URL",
+    "jwksUrl": "$UPSTREAM_JWKS_URL",
+    "logoutUrl": "$UPSTREAM_LOGOUT_URL",
+    "defaultScope": "openid profile email",
+    "syncMode": "FORCE",
+    "useJwksUrl": "true"
+  }
+}
+JSON
+)
+if "$KCADM" get "identity-provider/instances/$IDP_ALIAS" -r "$AKUKO_REALM" >/dev/null 2>&1; then
+  echo "  IdP '$IDP_ALIAS' exists; updating"
+  "$KCADM" update "identity-provider/instances/$IDP_ALIAS" -r "$AKUKO_REALM" -f - <<<"$IDP_PAYLOAD"
+else
+  echo "  creating IdP '$IDP_ALIAS'"
+  "$KCADM" create identity-provider/instances -r "$AKUKO_REALM" -f - <<<"$IDP_PAYLOAD"
+fi
+
+# ── Step 3: email Attribute Importer mapper (Force sync) ────────────────────
+# Essential — Akuko matches brokered users to existing accounts by email.
+EMAIL_MAPPER=$(cat <<JSON
+{
+  "name": "email",
+  "identityProviderAlias": "$IDP_ALIAS",
+  "identityProviderMapper": "oidc-user-attribute-idp-mapper",
+  "config": { "claim": "email", "user.attribute": "email", "syncMode": "FORCE" }
+}
+JSON
+)
+if ! "$KCADM" create "identity-provider/instances/$IDP_ALIAS/mappers" \
+    -r "$AKUKO_REALM" -f - <<<"$EMAIL_MAPPER" 2>/dev/null; then
+  echo "  (email mapper exists)"
+fi
+
+# ── Step 4: disable verification pages in the cloned flow ──────────────────
+# Review Profile + Handle Existing Account render HTML that cannot display in a
+# cross-origin embed iframe; disable them so brokered login proceeds to silent
+# linking. Create User If Unique stays ALTERNATIVE so new users are still made.
+EXEC_PATH="authentication/flows/$(enc_spaces "$FBL_FLOW")/executions"
+ROWS="$("$KCADM" get "$EXEC_PATH" -r "$AKUKO_REALM" \
+  --format csv --fields id,displayName --noquotes 2>/dev/null || true)"
+while IFS=',' read -r exec_id display_name; do
+  [[ -z "$exec_id" || "$exec_id" == "id" ]] && continue
+  lower="$(printf '%s' "$display_name" | tr '[:upper:]' '[:lower:]')"
+  requirement=""
+  case "$lower" in
+    *"review profile"*)          requirement="DISABLED" ;;
+    *"handle existing account"*) requirement="DISABLED" ;;
+    *"create user if unique"*)   requirement="ALTERNATIVE" ;;
+  esac
+  if [[ -n "$requirement" ]]; then
+    "$KCADM" update "$EXEC_PATH" -r "$AKUKO_REALM" \
+      -b "{\"id\":\"$exec_id\",\"requirement\":\"$requirement\"}" </dev/null 2>/dev/null \
+      && echo "  flow: '$display_name' → $requirement" \
+      || echo "  flow: '$display_name' update FAILED (continuing)"
+  fi
+done <<<"$ROWS"
+
+# ── Step 5: add idp-auto-link so brokered users link by email silently ─────
+LINK_SUBFLOW="authentication/flows/$(enc_spaces "$FBL_FLOW User creation or linking")/executions/execution"
+if "$KCADM" get "$EXEC_PATH" -r "$AKUKO_REALM" --fields providerId 2>/dev/null | grep -q "idp-auto-link"; then
+  echo "  flow: 'Automatically set existing user' present already"
+else
+  "$KCADM" create "$LINK_SUBFLOW" -r "$AKUKO_REALM" \
+    -b '{"provider":"idp-auto-link"}' </dev/null 2>/dev/null \
+    && echo "  flow: added idp-auto-link" \
+    || echo "  flow: add idp-auto-link FAILED (continuing)"
+fi
+# idp-auto-link lands DISABLED on create — promote it to ALTERNATIVE.
+AUTO_LINK_ID="$("$KCADM" get "$EXEC_PATH" -r "$AKUKO_REALM" \
+  --format csv --fields id,providerId --noquotes 2>/dev/null \
+  | awk -F',' '$2=="idp-auto-link"{print $1}' | head -1)"
+if [[ -n "$AUTO_LINK_ID" ]]; then
+  "$KCADM" update "$EXEC_PATH" -r "$AKUKO_REALM" \
+    -b "{\"id\":\"$AUTO_LINK_ID\",\"requirement\":\"ALTERNATIVE\"}" </dev/null 2>/dev/null \
+    && echo "  flow: idp-auto-link → ALTERNATIVE" \
+    || echo "  flow: idp-auto-link requirement update FAILED (continuing)"
+fi
+
+cat <<EOF
+✓ Path D broker configured.
+  Akuko realm  : $AKUKO_REALM
+  IdP alias    : $IDP_ALIAS   (pass to the SDK as idpHint="$IDP_ALIAS")
+  redirect URI : $KC_ADMIN_URL/realms/$AKUKO_REALM/broker/$IDP_ALIAS/endpoint
+                 (must be allow-listed on the upstream IdP's OIDC client)
+EOF

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@onaio/akuko-embed-sdk",
+  "version": "0.1.0",
+  "description": "Framework-agnostic embed SDK for Akuko dashboards",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Ona (https://ona.io)",
+  "homepage": "https://github.com/onaio/akuko-app/tree/develop/packages/embed-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onaio/akuko-app.git",
+    "directory": "packages/embed-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/akuko-embed-sdk.umd.cjs",
+  "module": "./dist/akuko-embed-sdk.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "examples",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "@vitest/coverage-v8": "4.0.18",
+    "eslint": "^8.57.1",
+    "jsdom": "^26.1.0",
+    "typescript": "^5.7.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --max-warnings 0"
+  }
+}