ADR-003: Keycloak for Authentication

Decision Analysis and Resolution: SW360 Authentication Provider

Created by: SW360 Architecture Team
Original Decision: 2022
Reformatted: April 2026
Status: Accepted
Estimated read time: 12 minutes

Table of Contents

1. Background
2. Goal
3. Key Principles
4. Key Inputs, Assumptions and Restrictions
5. Options Analysis
   • Option 1 - Spring Security Standalone
   • Option 2 - Auth0
   • Option 3 - Keycloak
   • Option 4 - Okta
   • Option 5 - Custom OAuth2 Server
6. Criteria for Making a Decision
7. Final Decision
8. Contributors
9. Implementation Details

Background

SW360 originally used Liferay Portal’s built-in authentication, which coupled user management to the UI layer. With the migration away from Liferay toward a REST-first architecture, several challenges emerged:

• Liferay Coupling: Authentication was tightly bound to the portal framework
• No API Authentication: REST API needed OAuth2/OIDC support
• Enterprise SSO: Customers required integration with corporate identity providers
• Programmatic Access: CI/CD pipelines needed API tokens
• Centralized Management: User provisioning across multiple SW360 instances

Why This Decision Matters: Authentication is a critical security component that affects every user interaction, API call, and integration point.

Goal

The goal of this decision analysis is to:

1. Decouple authentication from the Liferay portal layer
2. Enable OAuth2/OIDC for modern API authentication
3. Support enterprise SSO with LDAP/AD/SAML identity providers
4. Provide centralized user management
5. Enable API tokens for programmatic access
6. Maintain self-hosted deployment option (no cloud dependency)

Key Principles

Key Inputs, Assumptions and Restrictions

Options Analysis

Option 1 - Spring Security Standalone

Summary

Use Spring Security’s built-in authentication with a custom UserDetailsService connected to SW360’s CouchDB user database. Build OAuth2 authorization server using Spring Authorization Server.

Conceptual View

graph LR
    A[Client] --> B["Spring Security<br/>+ Spring Auth Server"] --> C["CouchDB (users)"]

Impact / Changes Required

• Implement custom UserDetailsService for CouchDB
• Build OAuth2 authorization server endpoints
• Implement token management (issuance, refresh, revocation)
• Build admin UI for user management

SWOT Analysis

Option 2 - Auth0

Summary

Use Auth0, a cloud-based identity-as-a-service platform providing OAuth2/OIDC, SSO, MFA, and user management out of the box.

Conceptual View

graph LR
    A[Client] --> B["Auth0 (Cloud)"] --> C[SW360 REST]

Impact / Changes Required

• Configure Auth0 tenant and application
• Integrate Spring Security with Auth0 JWT validation
• Sync users between Auth0 and SW360 CouchDB
• Configure enterprise connections for LDAP/SAML

SWOT Analysis

Option 3 - Keycloak

Summary

Use Keycloak, an open-source identity and access management solution from Red Hat. Self-hosted with OAuth2/OIDC, SAML, LDAP federation, and customizable user storage providers.

Conceptual View

graph TB
    A[Client] --> B["Keycloak (Self-host)"] --> C[SW360 REST]
    B --> D["PostgreSQL<br/>(KC users)"]
    B --> E["LDAP<br/>(Federation)"]
    B --> F["CouchDB<br/>(SW360)"]

Impact / Changes Required

• Deploy Keycloak with PostgreSQL
• Develop custom user storage provider for CouchDB
• Create event listener for user synchronization
• Configure Spring Security for JWT validation

SWOT Analysis

Option 4 - Okta

Summary

Use Okta, an enterprise identity management platform providing comprehensive IAM capabilities with cloud and on-premises options.

Conceptual View

┌─────────────┐     ┌──────────────┐     ┌──────────────┐
│   Client    │────►│    Okta      │────►│  SW360 REST  │
└─────────────┘     │   (Cloud)    │     └──────────────┘
                    └──────────────┘

Impact / Changes Required

• Purchase Okta subscription
• Configure Okta tenant
• Integrate with Spring Security

SWOT Analysis

Option 5 - Custom OAuth2 Server

Summary

Build a custom OAuth2 authorization server tailored specifically for SW360’s needs, using libraries like Spring Authorization Server or nimbus-jose-jwt.

Conceptual View

┌─────────────┐     ┌──────────────────────┐     ┌──────────┐
│   Client    │────►│  Custom OAuth2       │────►│ CouchDB  │
└─────────────┘     │  Server              │     │ (users)  │
                    └──────────────────────┘     └──────────┘

Impact / Changes Required

• Design and implement complete OAuth2 server
• Build admin UI
• Implement federation (LDAP, SAML)
• Ongoing security maintenance

SWOT Analysis

Criteria for Making a Decision

T-Shirt Sizing Scale

Weighted Evaluation Matrix

Score Summary

Final Decision

Selected Option: Keycloak

Rationale

Keycloak was selected as the identity provider for SW360 based on:

1. Highest Weighted Score (767.5) - Clear winner when balancing all requirements

2. Self-Hosted (XL) - Critical requirement met:

   • No cloud dependency
   • Full control over user data
   • Compliant with data residency requirements

3. Enterprise SSO (L-XL) - Built-in support for:

   • LDAP/Active Directory federation
   • SAML 2.0 identity providers
   • OpenID Connect
   • Social login providers

4. Open Source (XL) - Apache 2.0 license with Red Hat backing:

   • No vendor lock-in
   • Active community
   • Regular security updates

5. Custom User Storage (L-XL) - Extensible architecture allows:

   • SW360 CouchDB user storage provider
   • Event listeners for user synchronization
   • Custom authentication flows

Implementation Notes

Architecture:

┌─────────┐     ┌──────────┐     ┌──────────────┐
│  User   │────►│ Keycloak │────►│  SW360 REST  │
└─────────┘     └──────────┘     └──────────────┘
                     │                   │
              ┌──────┴──────┐     ┌──────┴──────┐
              │  PostgreSQL │     │   CouchDB   │
              │ (KC users)  │     │(SW360 users)│
              └─────────────┘     └─────────────┘

Custom Providers:

• sw360-keycloak-user-storage-provider.jar - Reads users from CouchDB
• sw360-keycloak-event-listener.jar - Syncs Keycloak events to SW360

Review Triggers

This decision should be revisited if:

• Keycloak project becomes unmaintained
• Cloud-first deployment becomes primary model
• Custom provider maintenance becomes unsustainable
• Alternative open-source IAM with better fit emerges

Contributors

Implementation Details

Spring Security Configuration

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://keycloak:8083/realms/sw360
          jwk-set-uri: http://keycloak:8083/realms/sw360/protocol/openid-connect/certs

For deployments that must trust more than one issuer/JWKS endpoint (for example, Keycloak plus SW360 authorization-server), configure explicit trusted issuers:

sw360:
  security:
    jwt:
      issuers:
        - issuer-uri: https://sw360.example.com/kc/realms/sw360
          jwk-set-uri: https://keycloak-internal:8083/kc/realms/sw360/protocol/openid-connect/certs
        - issuer-uri: http://localhost:8080/authorization

This configuration pattern is supported by both the SW360 resource-server and the authorization-server resource endpoints (for example /authorization/client-management/** when called with Bearer JWT).

Authentication Flow

1. User accesses SW360 UI/API
2. Redirected to Keycloak login
3. Keycloak authenticates (local DB or federated)
4. JWT token issued
5. Token sent to SW360 API
6. SW360 validates token via JWKS endpoint
7. User extracted from token claims

API Token Support

For programmatic access, SW360 also supports API tokens:

rest.apitoken.read.validity.days=90
rest.apitoken.write.validity.days=30
rest.apitoken.hash.salt=$2a$04$Software360RestApiSalt

Consequences Summary

Positive

• ✅ SSO Support—users log in once for multiple applications
• ✅ JWT Tokens—stateless authentication, scalable
• ✅ Federation—connect to existing LDAP/AD directories
• ✅ Security—battle-tested OAuth2/OIDC implementation
• ✅ API Tokens—native support for service accounts
• ✅ Self-hosted—no cloud dependency

Negative

• ⚠️ Additional component to deploy and maintain
• ⚠️ OAuth2 flows can be complex to troubleshoot
• ⚠️ Resource usage—Keycloak requires memory/CPU
• ⚠️ Learning curve for Keycloak administration
• ⚠️ Custom provider maintenance required

Technical Debt Created

• Custom user storage provider must be maintained
• Keycloak version compatibility testing required
• PostgreSQL database added to infrastructure

Revision History