Configuration
Reference for the Signing Server server.json file, its sections, accepted values and the separate identity provider configuration file.
Signing Server is configured with one JSON file, server.json, and a separate advanced file for identity provider connections, requesters, policies and bindings. This page describes the sections and their rules.
File rules
Section titled “File rules”schema_versionmust be the integer1.- The file is UTF-8 without BOM, at most 65,536 bytes, 12 nesting levels and 512 values.
- Unknown properties, duplicate properties,
nulland wrong types are rejected. - File references are relative to the configuration file, or absolute local paths. URLs, parent traversal, environment interpolation and inline secrets are not accepted.
- Referenced files are not opened by
config-check. A reference to a missing file can pass the offline check and fail atstart.
Sections
Section titled “Sections”| Section | Description |
|---|---|
service |
Selects the service mode. Omitted for DSS human signing. csc-v1 selects the separate CSC service; organization-seal-v1 and timestamp-v1 select the machine modes and are never inferred from missing fields. |
listener |
mode is direct_https or private_proxy. bind_address is a literal IPv4 address, port 1–65535 and external_base_url the public HTTPS origin without user info, query or fragment. Direct mode requires tls with file, password_file and alias. Proxy mode forbids tls and requires a loopback or RFC 1918 bind address. |
database |
engine is postgresql, mariadb or sqlserver. Separate host, port and name, never a JDBC URL. ssl_mode is verify-full, with a required ca_file, or disable. runtime and optional migration each have username and password_file. |
saml_transport |
The PKCS#12 file, password_file and alias for SAML signing, and a distinct encryption_alias for SAML decryption in the same store. |
dss_envelope |
The PKCS#12 identity that signs DSS responses. It must be a different store from TLS and SAML. |
signing |
The DSS/seal document-key selection. Supplied backend is pkcs12, with keystore and credential, or pkcs11, with module_file, module_sha256, configuration_file, token_label, key_label, pin_file and credential. |
access_configuration |
Path to the advanced identity provider file. |
event_log |
Optional CEF event output. Omitted means disabled. |
The database name is an ASCII SQL identifier of up to 63 characters. MariaDB and SQL Server require both a migration and a runtime account, and accept ssl_mode disable only for a database on 127.0.0.1. The server runs migrations with the migration account when present, and otherwise with the runtime account.
At startup the server verifies that the TLS, SAML signing, SAML decryption, DSS envelope and document keys are all different, and checks certificate validity, usage, chains and file permissions before it binds the listener.
Optional issued credentials and CSC
Section titled “Optional issued credentials and CSC”DSS human signing can explicitly select signing.backend="dynamic" with a protected configuration_file and its exact configuration_sha256. A provisioned selection instead uses the activated descriptor and hash. Neither is enabled by omission. See External PKI and certificate issuance.
CSC has a separate closed configuration: service="csc-v1", registered clients, identities and credentials, with a supplied signing selection inside each credential. It does not require a DSS response-envelope key. Use the dedicated CSC configuration schema and CSC guide rather than combining modes in one file.
Identity provider configuration
Section titled “Identity provider configuration”The file referenced by access_configuration contains:
| Part | Description |
|---|---|
connections_file |
The registry of named identity provider connections with pinned metadata. |
policies |
Per-connection policy, such as the message display mode sign_message_display (idp or signing_service) and the required signer attributes and authentication context. |
requesters |
Registered requesters, each with entity_id, an RSA public_key of 2048–4096 bits and an exact HTTPS return_uri. |
bindings |
The explicit mapping of connection, requester and subject to a signing credential. An unknown or cross-mapped combination fails closed. |
A subject reference is saml- followed by the lowercase SHA-256 hex of the UTF-8 string made from the IdP entity ID, a NUL byte, the subject attribute URI, a NUL byte and the RFC 4518 canonical subject. The mapping is an administrator decision and is not authentication.
Optional authentication_redirect_origins lists up to eight exact HTTPS origins that the authentication form may redirect to. It is empty by default and a request can never extend it.
Optional CEF event logging
Section titled “Optional CEF event logging”The optional event_log section, with format set to cef, enables a closed catalog of content-free CEF events. Events go to the application stream or to a separate owned directory. Event output is best effort and does not replace the database audit.