Skip to content

Identity Strategy — Keycloak + WSO2 IS

Two identity systems, one source of truth. Decision: Keycloak is the authoritative IdP for all human users (internal platform + admin); WSO2 IS is the identity broker for API consumers (apps calling WSO2-managed APIs). WSO2 IS federates up to Keycloak for end-user authentication.

The two-IdP model

flowchart TB
    subgraph Users["Humans"]
        Admin["Platform admins,<br/>developers, operators"]
        Customer["API consumers<br/>(end users via partner apps)"]
    end

    subgraph Keycloak["🔑 Keycloak (RHBK)<br/>on OpenShift hub"]
        KC["Realm: brac-poc<br/>• MFA required<br/>• Federates to AD/LDAP<br/>  (for Phase 2)"]
    end

    subgraph WSO2IS["🔐 WSO2 IS<br/>on VM tier"]
        IS["Identity federation<br/>(trusts Keycloak)<br/>+ OAuth2 token issuance<br/>for WSO2 APIM"]
    end

    subgraph Resources["Protected resources"]
        OCP["OCP Console,<br/>ArgoCD, ACS, Keycloak,<br/>GitLab, Jenkins, Nexus,<br/>AWX, Terrakube, SigNoz,<br/>Splunk, Grafana, n8n"]
        API["WSO2 APIM<br/>APIs"]
    end

    Admin -->|OIDC login| KC
    KC --> OCP

    Customer -->|OIDC login| IS
    IS -->|federated IdP<br/>(brokers to)| KC
    IS -->|issues access token| API

Rationale

Why two IdPs?

  • WSO2 APIM's key manager expects WSO2 IS as its native identity broker (or another OIDC provider; Keycloak via federation works). Keeping WSO2 IS as the API-consumer gateway matches the standard WSO2 enterprise pattern BRAC expects to evaluate.
  • Keycloak is the platform user authority: cluster admins, DevOps, developers. This aligns with the Red Hat platform story (RHBK is Red Hat's enterprise IdP).
  • Federation avoids double user management: an employee gets one Keycloak identity that works across both internal tools and (via federation) any external APIs they consume.

Why not just one (Keycloak)?

  • WSO2 APIM has tight coupling with WSO2 IS's OAuth2 endpoints, scopes, and application lifecycle. Using Keycloak as the primary for APIM would bypass WSO2's native key-management workflows that BRAC wants to see demonstrated.
  • WSO2 IS offers API-consumer-specific features (self-service portal, developer accounts, API subscription management) that Keycloak doesn't.

Why not just WSO2 IS?

  • Keycloak (RHBK) is a Red Hat product and fits the Red Hat-only operator posture for OCP cluster access.
  • Keycloak has better K8s/OpenShift integration (native OIDC provider for OCP OAuth CR).
  • Better UX for non-API admin scenarios (OCP console login, ACS login, etc.).

Who uses which

User class Primary IdP Example
OCP cluster admin (operators, SREs) Keycloak Logging into OCP console, ArgoCD, ACS
Platform tools admin (DevOps, security) Keycloak Logging into AWX, Terrakube, GitLab, Jenkins, Nexus, Splunk, SigNoz, Grafana
Developer (writing apps that call APIs) Keycloak (federated into WSO2 IS) Logging into WSO2 DevPortal to create an application
End user of a partner app (indirect) WSO2 IS (which federates to Keycloak for human auth) Hitting an API through a partner app; OAuth2 token issued by WSO2 IS
External API consumer (machine-to-machine, no human) WSO2 IS direct (client credentials grant) A partner bank's backend calling a BRAC API

Keycloak realm configuration

Realm: brac-poc

Clients: - openshift-brac — for all 4 OCP clusters' OAuth CR (Decision #017) - gitlab — GitLab OIDC login - jenkins — Jenkins OIDC plugin - nexus — Nexus SAML/OIDC - awx — AWX social auth / OIDC - terrakube — Terrakube OIDC - splunk — Splunk SAML - signoz — SigNoz OIDC - argocd — ArgoCD Dex passthrough - wso2-is — the federation client: WSO2 IS uses Keycloak as its external IdP

Federated identities: Phase 2 could broker to BRAC's real AD/LDAP. For POC, local users.

Groups/roles: - platform-admins (cluster-admin on all OCP clusters) - devops (access to GitLab, Jenkins, Nexus, AWX, Terrakube) - developers (WSO2 DevPortal, GitLab read) - security (ACS, Compliance, Splunk, Falco-ish-via-ACS) - observability-read (SigNoz, Grafana, Loki UI, Tempo)

MFA enforced for all groups (TOTP via Keycloak built-in).

WSO2 IS configuration

  • Identity provider: "Keycloak" (federated) — trusts Keycloak's OIDC discovery endpoint
  • Local accounts: disabled for human users (must federate); enabled for M2M service accounts
  • Resident identity provider: issues OAuth2 tokens for WSO2 APIM gateway
  • Claim mapping: Keycloak claims (preferred_username, email, groups) → WSO2 IS internal attributes
  • Session: single sign-out back to Keycloak on logout

WSO2 APIM integration

  • APIM Key Manager (dedicated profile wso2-apim-km-vm1-dc/dr) points at WSO2 IS for token issuance
  • Developer Portal: developers log in via IS → federated to Keycloak → Keycloak MFA → token issued → developer can create apps + subscribe to APIs
  • Gateway: validates access tokens against IS (introspection endpoint or JWT validation)
  • Rate-limit policies: tied to IS-issued subscription tiers

Bootstrap order (relative to DEPLOYMENT-ORDER.md)

  1. Phase 6: Keycloak on hub-dc via RHBK operator (GitOps). Realm brac-poc created via KeycloakRealmImport CR.
  2. Phase 4.2 (reordered after Phase 6): WSO2 IS VMs provisioned + config'd to federate with Keycloak
  3. Phase 4.3: WSO2 APIM profiles provisioned + configured against WSO2 IS as the key manager
  4. All other platform tools' clients created in Keycloak via declarative config (Keycloak CR ClientScopes, Roles, etc.) committed to openshift-platform-gitops/components/_base/keycloak-realm-brac-poc/

Non-goals for POC

  • No integration with a real corporate AD/LDAP (Phase 2)
  • No multi-realm (single brac-poc realm is sufficient)
  • No social login (Google, GitHub) — not needed for bank POC
  • No SCIM provisioning (Phase 2)

Sign-off flow demo (Day-6 demo)

  1. Mgr opens OCP console → redirected to Keycloak → logs in with MFA → back to OCP console (shows openshift-cluster-admin group assignment)
  2. Dev opens WSO2 DevPortal → redirected to WSO2 IS → IS shows "Login with Keycloak" → Keycloak MFA → back to DevPortal authenticated as developer role
  3. Dev creates app, subscribes to API, gets token from IS, calls the API through WSO2 Gateway — token validated, rate-limit applied, request passes to backend
  4. Logout from OCP console → single-sign-out propagates to all Keycloak-federated systems (GitLab, SigNoz, ArgoCD, etc.)

Created: 2026-04-24 · Owner: Security Lead + Integration Lead · Decision: #032