SW360 Configurations

Introduction

SW360 configurations are divided into two main categories: Non-changeable (File-based) and Changeable (Database-backed).

Applicable Property Files:

• sw360.properties (Core configurations)
• couchdb.properties (CouchDB and Lucene connectivity)
• orgmapping.properties (Organization mapping features)
• couchdb-test.properties (CouchDB test purpose)
• authorization/application.yml (Authorization server settings)
• rest/application.yml (Resource server settings)

Database Configurations:

Most of the SW360-related properties (UI settings and backend features) are now moved to a database and are accessible via a REST endpoint. These are divided into two containers:

• SW360_CONFIGURATION (Backend)
• UI_CONFIGURATION (Frontend)

More details can be found in the Database Configurations section below.

SW360.properties (/etc/sw360/sw360.properties)

The sw360.properties file contains properties that are considered non-changeable via the UI and require a Tomcat restart to take effect after updating.

couchdb.properties (/etc/sw360/couchdb.properties)

CouchDB and Lucene search configuration properties.

orgmapping.properties (/etc/sw360/orgmapping.properties)

This configuration file is used to activate the sw360 orgmapping feature.

couchdb-test.properties (/etc/sw360/couchdb-test.properties)

This file is used solely for the purpose of CouchDB database connectivity during testing.

authorization/application.yml (/etc/sw360/authorization/application.yml)

The Authorization Server handles OAuth2 tokens and client credentials.

server:
  port: 8090

couchdb:
  url: http://localhost:5984
  database: sw360oauthclients
  username: sw360
  password: sw360fossie

jwt:
  secretkey: sw360SecretKey

spring:
  jackson:
    serialization:
      indent_output: true
  security:
    oauth2:
      resourceserver:
        jwt:
          # Optional single-issuer fallback.
          issuer-uri: ${AUTH_RESOURCE_SERVER_ISSUER_URI:}

security:
  customheader:
    headername:
      enabled: false
      intermediateauthstore: custom-header-auth-marker
      email: authenticated-email
      extid: authenticated-extid
  oauth2:
    resource:
      id: sw360-REST-API
  accesstoken:
    validity: 30

sw360:
  cors:
    allowed-origin: ${SW360_CORS_ALLOWED_ORIGIN:#{null}}
  security:
    jwt:
      issuers:
        - issuer-uri: https://sw360.example.com/authorization
          jwk-set-uri: https://authorization-internal:8090/authorization/oauth2/jwks
        - issuer-uri: https://sw360.example.com/kc/realms/sw360
          jwk-set-uri: https://keycloak-internal:8083/kc/realms/sw360/protocol/openid-connect/certs
logging:
  level:
    org.springframework.security: DEBUG

Getting a REST API Token via client_credentials

Clients created in the SW360 Authorization Server can request REST API access tokens via the OAuth2 client_credentials grant. Use the client ID and the one-time client secret shown when the client was created.

AUTH_URL=http://localhost:8080/authorization
CLIENT_ID='<client-id>'
CLIENT_SECRET='<client-secret>'

# Read-only token: usable for GET requests and read-side permission checks.
READ_TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'scope=READ' \
  "$AUTH_URL/oauth2/token" | jq -r '.access_token')

# Read/write token: required for POST, PUT, PATCH, and DELETE requests.
WRITE_TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'scope=READ WRITE' \
  "$AUTH_URL/oauth2/token" | jq -r '.access_token')

Use the token against the Resource Server with the standard Bearer scheme:

# Standalone Resource Server: http://localhost:8091/api
# Tomcat/WAR deployment:     http://localhost:8080/resource/api
RESOURCE_API_URL=http://localhost:8091/api

curl -i \
  -H "Authorization: Bearer $READ_TOKEN" \
  "$RESOURCE_API_URL/projects?page=0&page_entries=5"

The token scope limits HTTP method access at the Resource Server:

User roles are still evaluated separately. For example, a read-only token for an admin user can access admin-restricted read endpoints, but it still cannot use write HTTP methods unless the token also contains WRITE scope.

For a more detailed REST API flow description, see API Access and REST API. For Keycloak-issued client-credentials tokens, see Keycloak Token.

rest/application.yml (/etc/sw360/rest/application.yml)

The Resource Server provides the SW360 REST API.

server:
  servlet:
    context-path: /

management:
  endpoints:
    web:
      base-path: /
      exposure:
        include: health,info
      path-mapping:
        health: /api/health
        info: /api/info
  endpoint:
    health:
      show-details: always
      enabled: true
    info:
      enabled: true
  security:
    enabled: true
  health:
    diskspace:
      enabled: true    # Disable to hide sensitive system information
    ping:
      enabled: true
    ssl:
      enabled: false   # Disabled as not used

spring:
  profiles:
    active: SECURITY_MOCK
  application:
    name: resource
  servlet:
    multipart:
      max-file-size: 500MB
      max-request-size: 600MB
  security:
    oauth2:
      resourceserver:
        jwt:
          # Optional single-issuer fallback.
          issuer-uri: ${AUTH_RESOURCE_SERVER_ISSUER_URI:}

#logging:
#  level:
#    org.springframework.security: DEBUG
#    org.springframework.security.oauth2: DEBUG
#    org.springframework.security.oauth2.provider.endpoint: DEBUG
#    org.springframework.security.oauth2.provider.error: DEBUG
#    org.springframework.security.oauth2.provider.token: DEBUG
#    org.springframework.security.oauth2.provider.token.store: DEBUG
#    org.springframework.security.oauth2.provider.token.store.jwk: DEBUG

jwt:
  auth:
    converter:
      principle-attribute: email

sw360:
  thrift-server-url: ${SW360_THRIFT_SERVER_URL:http://localhost:8080}
  base-url: ${SW360_BASE_URL:http://localhost:8080}
  test-user-id: admin@sw360.org
  test-user-password: 12345
  couchdb-url: ${SW360_COUCHDB_URL:http://localhost:5984}
  cors:
    allowed-origin: ${SW360_CORS_ALLOWED_ORIGIN:#{null}}
  security:
    http-basic:
      enabled: true
    jwt:
      issuers:
        - issuer-uri: http://localhost:8080/authorization
        - issuer-uri: https://sw360.example.com/kc/realms/sw360
          jwk-set-uri: http://keycloak-internal:8083/kc/realms/sw360/protocol/openid-connect/certs

blacklist:
  sw360:
    rest:
      api:
        endpoints:

springdoc:
  api-docs:
    enabled: true
    path: /v3/api-docs
    security:
      oauth2:
        enabled: true
  swagger-ui:
    enabled: true
    path: /index.html
    security:
      oauth2:
        enabled: true
  default-consumes-media-type: application/json
  default-produces-media-type: application/hal+json

Multi-Issuer JWT Setup

The Resource Server can trust JWTs from more than one issuer. This is useful when the deployment accepts tokens from both:

• the SW360 Authorization Server, for SW360-managed OAuth clients and client_credentials tokens; and
• Keycloak, for browser login and externally managed OIDC clients.

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

When the identity provider sits behind a reverse proxy with a self-signed or privately-issued certificate, fetching the JWKS via the public URL forces the Resource Server through that reverse proxy and requires either a publicly trusted certificate or a JVM truststore import on every certificate rotation.

You can provide an optional jwk-set-uri that points directly at the JWKS endpoint over a loopback or internal URL. When jwk-set-uri is set, OpenID Connect discovery is skipped entirely; the issuer claim in incoming tokens is still validated against issuer-uri, so external clients keep using the public issuer URL unchanged.

Behaviour summary:

• When jwk-set-uri is omitted, discovery against issuer-uri is used.
• When jwk-set-uri is set, JWKS is fetched directly from that URL and the discovery is skipped.

If sw360.security.jwt.issuers is not configured, the Resource Server falls back to the single Spring Boot issuer property:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8080/authorization

After changing issuer configuration, restart the Resource Server. Once the trusted issuers are configured, switching between SW360 Authorization Server tokens and Keycloak tokens does not require another Resource Server restart.

HTTP Basic authentication is controlled by sw360.security.http-basic.enabled. The example above keeps the development default (true). For production hardening guidance, including disabling Basic auth via the prod profile or an explicit property override, see Disable HTTP Basic Authentication.

Database Configurations

A significant portion of SW360’s configuration is now stored in the database. These settings are dynamic and can be managed via REST API endpoints without requiring a full system restart in most cases.

The configurations are partitioned into two containers:

1. SW360_CONFIGURATION: Backend and core logic settings.
2. UI_CONFIGURATION: Frontend and UI-specific settings (categories, roles, platforms, etc.).

SW360 Container (Backend)

UI Container (Frontend)

Configuration Management via the UI

Since these configurations are accessible over REST API, they can be manipulated directly from the frontend.

From an ADMIN account, goto the frontend, under Admin section, you’d find Configurations tab, which allows you to manage these configurations. There will be 2 tabs for each container defined bellow which helps you mainpulate these configurations directly from the UI.

Configuration Management via REST API

Configurations can be retrieved and updated using the following endpoints provided by the Resource Server.

Retrieve Configurations

• Get All Configurations: GET /configurations?changeable=<bool>
  • changeable=true: Returns keys managed in the database.
  • changeable=false: Returns keys defined in sw360.properties.
• Get Container-Specific Configurations: GET /configurations/container/{configFor}?changeable=<bool>
  • configFor: SW360_CONFIGURATION (Backend) or UI_CONFIGURATION (Frontend).

Update Configurations

• Update Database Configs: PATCH /configurations/container/{configFor}
  • Content-Type: application/json
  • Description: Updates one or more keys in the specified container.

Reloading Policy

• Database Configs (Changeable): Updates are applied immediately upon successful PATCH operation.
• File Configs (Non-changeable): Updates must be made by editing the sw360.properties file on the server. A Tomcat restart is required to load the new values.