Application Configuration

The application.yml contains the main configuration of the CSC component and needs to be mounted into /opt/cscapi/application.yml of the running container. The configuration is divided into sections.

The complete configuration contains the following:

# CSC API configuration
csc:
  # The name of the CSC component that will be provided in the Info endpoint
  name: CSC API
  # The URI of the image file containing the logo of the remote service which SHALL be published online.
  # The image SHALL be in either JPEG or PNG format and not larger than 256x256 pixels.
  logo: https://csc.example/logo.png
  # The ISO 3166-1 [22] Alpha-2 code of the Country where the remote  service provider is established
  # (e.g. ES for Spain).
  region: CZ
  # SignServer workers configuration file
  workerConfigurationFile: /opt/cscapi/workers.yml
  # Path to the directory containing the certificate management profiles configuration files.
  # The configuration files must be in the YAML format and must be named according to the following pattern:
  # - credential-profiles-[caProviderName].yml - profiles that can be selected for credential management
  # - signature-qualifier-profiles-[caProviderName].yml - profiles that will be used for signatureQualifier requests
  # The [caProviderName] must match the name of the CA provider configured.
  # See the example configuration files for more information.
  profilesConfigurationDirectory: /opt/cscapi/profiles
  # Configuration of the session-based credentials
  # Session is identified by the `sessionId` attribute in the request `clientData` field
  # `sessionId` is a UUID that is generated by the client and is used to identify the session
  signingSessions:
    # Pre-generate session keys according to the specified cron expression on defined key pool profiles
    # The cron expression is in the UN*X definition format: second, minute, hour, day of month, month, and day of week
    generateCronExpression: "30 */1 * * * *"
    # Keep the expired credential sessions for the specified time in ISO 8601 duration format
    # See https://en.wikipedia.org/wiki/ISO_8601#Durations for more information
    expiredSessionsKeepTime: PT1H
    # Run cleanup of expired sessions according to the specified cron expression
    # The cron expression is in the UN*X definition format: second, minute, hour, day of month, month, and day of week
    cleanupCronExpression: "0 0 * * * *"
  # Configuration of the one-time keys
  # One-time keys are pre-generated keys used for signing only once
  # The keys are generated in pools
  oneTimeKeys:
    # Pre-generate one-tim keys according to the specified cron expression on defined key pool profiles
    # The cron expression is in the UN*X definition format: second, minute, hour, day of month, month, and day of week
    generateCronExpression: "0 */1 * * * *"
    # How long will the keys be kept in the pool in ISO 8601 duration format before they are removed
    # See https://en.wikipedia.org/wiki/ISO_8601#Durations for more information
    usedUpKeyKeepTime: PT1H
    # How often will the cleaning of the used-up keys be performed according to the specified cron expression
    # The cron expression is in the UN*X definition format: second, minute, hour, day of month, month, and day of week
    cleanupCronExpression: "0 0 * * * *"

# IDP configuration
idp:
  # Base URL of the IDP OpenID Connect endpoint
  baseUrl: https://idp.example.com/realms/CSC
  # URL of the JWKS endpoint to retrieve and update the public keys
  jwksUri: https://idp.example.com/realms/CSC/protocol/openid-connect/certs
  # URL of the UserInfo endpoint to retrieve user information in exchange for an access token
  # optional, if not provided, the UserInfo endpoint will not be used
  userInfoUrl: https://idp.example.com/realms/CSC/protocol/openid-connect/userinfo
  # Issuer of the IDP token, used for token validation
  issuer: https://idp.example.com/realms/CSC
  # Audience of the IDP token, used for token validation
  audience: cscapi
  # Clock skew in seconds for token validation
  clockSkewSeconds: 5
  # Name of the truststore bundle containing trusted certificates; OPTIONAL
  # truststoreBundle: trustedcertificates
  client:
    # Authentication type for the IDP client operations
    # NONE is used for no authentication
    # CERTIFICATE is used for mutual TLS authentication and requires a client certificate
    authType: NONE
    # Only used when authorization type is CERTIFICATE
    certificate:
      keystoreBundle: idpClient

# Signing provider configuration
signingProvider:
  # SignServer configuration
  signserver:
    # URL of the SignServer
    url: https://signserver.example.com/signserver
    # Name of the truststore bundle containing trusted certificates; OPTIONAL
    # truststoreBundle: trustedcertificates
    client:
      # Authorization type for the client signing operations
      # BASIC is used for basic authentication, and basic username and password are required
      # CERTIFICATE is used for mutual TLS authentication and requires a client certificate
      authType: CERTIFICATE
      # Only used when authorization type is CERTIFICATE
      certificate:
        keystoreBundle: signserverClient
      # Only used when authorization type is BASIC
      basic:
        # Username for basic authentication
        username: admin
        # Password for basic authentication
        password: admin
    # Client keystore configuration for admin operations
    admin:
      # Name of the keystore bundle containing the admin certificate and private key
      keystoreBundle: signserverAdmin

# CA provider configuration
caProvider:
  # EJBCA configuration
  ejbca:
    # URL of the EJBCA
    url: https://ejbca.example.com/ejbca
    # Name of the truststore bundle containing trusted certificates; OPTIONAL
    # truststoreBundle: trustedcertificates
    # Admin keystore configuration for RA operations
    admin:
      # Name of the keystore bundle containing the admin certificate and private key
      keystoreBundle: ejbcaAdmin

# TLS/mTLS configuration, disabled by default
server:
  # Configuration of the keystore with server certificate and private key
  ssl:
    # Enable or disable TLS
    enabled: false
    # Key store type, allowed values: JKS, PKCS12, recommended: PKCS12
    key-store-type: PKCS12
    # Absolute path to the keystore file, containing the server certificate and private key
    key-store: /opt/cscapi/keystore.p12
    # Key store password
    key-store-password: password
    # Alias of the server certificate with private key in the keystore
    key-alias: server
    # Private key password, if different from the keystore password
    # key-password: password
    # Client authentication mode, allowed values: NONE, WANT, NEED
    # NEED = mandatory mTLS, WANT = optional mTLS, NONE = no mTLS
    client-auth: WANT
    # Trust store type, allowed values: JKS, PKCS12, recommended: PKCS12
    trust-store-type: PKCS12
    # Absolute path to the truststore file, containing trusted certificates
    trust-store: /opt/cscapi/truststore.p12
    # Trust store password
    trust-store-password: password

# Spring configuration
spring:
  # Jackson configuration, DO NOT CHANGE if you are not familiar with Jackson
  jackson:
    default-property-inclusion: NON_NULL
  # Configuration of SSL context for the REST and Web Services clients
  ssl:
    bundle:
      # Sample configuration of a truststore using PEM encoded certificate or certificate chain
      # pem:
      # trustedcertificates:
      #    truststore:
      #        certificate: /opt/cscapi/trusted-ca-certs.pem
      jks:
        # Sample configuration of keystore using PKCS12 keystore
        # ejbcaAdmin: # Name of the keystore bundle
        #     keystore:
        #         type: "PKCS12" # Keystore type, allowed values: JKS, PKCS12
        #         location: /opt/cscapi/admin-keystore.p12 # Absolute path to the keystore file
        #         password: password # Keystore password
        idpClient:
          keystore:
            type: "PKCS12"
            location: /opt/cscapi/idp/client-keystore.p12
            password: password
        ejbcaAdmin:
          keystore:
            type: "PKCS12"
            location: /opt/cscapi/ejbca/admin-keystore.p12
            password: password
        signserverAdmin:
          keystore:
            type: "PKCS12"
            location: /opt/cscapi/signserver/admin-keystore.p12
            password: password
        signserverClient:
          keystore:
            type: "PKCS12"
            location: /opt/cscapi/signserver/client-keystore.p12
            password: password
  # Datasource configuration
  datasource:
    # JDBC URL of the database
    # for PostgreSQL use: jdbc:postgresql://localhost:5432/cscdb
    # for MySQL use: jdbc:mysql://localhost:3306/cscdb
    url: jdbc:postgresql://localhost:5432/cscdb
    # Username to connect to the database
    username: 'cscuser'
    # Password to connect to the database
    password: 'your-strong-password'
    # Driver class name of the database
    # for PostgreSQL use: org.postgresql.Driver
    # for MySQL use: com.mysql.cj.jdbc.Driver
    driver-class-name: 'org.postgresql.Driver'
  flyway:
    table: "csc_schema_history"
    schemas: "csc"
    locations: "classpath:db/migration,classpath:db/specific/{vendor}"
  threads:
    virtual:
      enabled: true

# Logging configuration
logging:
  level:
    # Logging level for the CSC API, allowed values: TRACE, DEBUG, INFO, WARN, ERROR
    com.czertainly.csc: INFO

# Springdoc configuration, DO NOT CHANGE if you are not familiar with Springdoc
springdoc:
  swagger-ui:
    disable-swagger-default-url: true
    configUrl: /openapi/swagger-config
    url: /openapi
  api-docs:
    path: /openapi

Application profiles

Running instances of the CSC component can be configured with different application profiles. The profiles are used to define different roles of the instances, especially when running multiple instances of the CSC component in a cluster.

Active profiles are defined using environment variable SPRING_PROFILES_ACTIVE or spring.profiles.active property in the application.yml. By default, no profiles are active. The following profiles are available:

Profile Name	Description
keys-generator	The instance is used to generate short-lived and session keys according to the Profiles and Workers configuration. It is used to pre-generate keys for the signing services and is not used to sign requests.
one-time-keys-cleaner	The instance is used to clean up the short-lived keys that are no longer used and were not successfully destroyed after the signing operation and are no longer needed.

Active profiles can be combined, for example, keys-generator,one-time-keys-cleaner will run the instance that will generate short-lived and session keys and clean up the short-lived keys that are no longer used.