BFF Configuration Reference

Database Configuration

MariaDB Container Configuration

The following variables configure the BFF's MariaDB database container:

Variable	Type	Default	Description
MARIADB_USER	string	-	MariaDB user
MARIADB_PASSWORD	string	-	MariaDB password
MARIADB_DATABASE	string	-	MariaDB database name
MARIADB_ROOT_PASSWORD	string	-	MariaDB root password

Database Connection Variables

The BFF uses the following variables to construct the database connection. These should reference the MariaDB container values above:

Variable	Type	Default	Description
MYSQL_HOST	string	-	MySQL/MariaDB hostname
MYSQL_DB	string	-	MySQL/MariaDB database name (must match MARIADB_DATABASE)
MYSQL_USER	string	-	MySQL/MariaDB username (must match MARIADB_USER)
MYSQL_PASSWORD	string	-	MySQL/MariaDB password (must match MARIADB_PASSWORD)

Spring Database Configuration

Spring Boot uses these variables to establish database connections, typically referencing the MYSQL_* variables above:

Variable	Type	Default	Description
spring.datasource.url	string	-	Database connection URL (format: jdbc:mysql://${MYSQL_HOST}:port/${MYSQL_DB})
spring.datasource.username	string	-	Database username (typically references ${MYSQL_USER})
spring.datasource.password	string	-	Database password (typically references ${MYSQL_PASSWORD})
spring.datasource.hikari.connectionTimeout	integer	30000	Maximum time (ms) to wait for connection from pool
spring.datasource.hikari.maximumPoolSize	integer	10	Maximum number of connections in the pool
spring.flyway.enabled	boolean	true	Enable/disable Flyway database migrations
spring.flyway.locations	string	classpath:db/migration	Location of Flyway migration scripts
spring.jpa.hibernate.ddl-auto	string	-	Hibernate DDL auto mode (for example, validate, update, create)
spring.jpa.open-in-view	boolean	true	Enable Open Session in View pattern

Server and HTTP Settings

Variable	Type	Default	Description
server.port	integer	8080	HTTP port for the application server
server.tomcat.accessLogEnabled	boolean	false	Enable Tomcat access logging
server.tomcat.accessLogPattern	string	-	Pattern for Tomcat access logs (for example, "%a %t %r %s %b")
server.tomcat.relaxed-query-chars	string	-	Characters allowed in URL query strings without encoding
spring.mvc.async.request-timeout	integer	-	Async request timeout in milliseconds (30 minutes recommended for large CSV exports)

Secure Token Service (STS)

Variable	Type	Default	Description
sts.enableManagementEndpoints	boolean	-	Enable STS management endpoints
sts.enableTokenEndpoint	boolean	-	Enable STS token issuance endpoint
sts.token.iss	string	-	Token issuer URL (typically your IAM URL with port)
sts.token.privateKey	string	-	Private key for signing tokens
sts.token.maxTokenValidity	integer	-	Maximum token validity period
sts.token.aud	string	-	Token audience claim

Identity and Access Management (IAM)

Variable	Type	Default	Description
sts.iam.adminRole	string	-	IAM role of BFF admin users
sts.iam.rolePath	string	-	JSON path to roles claim in IAM token
sts.iam.usernamePath	string	-	JSON path to username claim in IAM token
sts.iam.givenNamePath	string	-	JSON path to given name claim in IAM token
sts.iam.familyNamePath	string	-	JSON path to family name claim in IAM token
sts.iam.emailPath	string	-	JSON path to email claim in IAM token
sts.iam.defaultLanguage	string	-	Default language for users
sts.iam.defaultHomepage	string	-	Default homepage URL after login
sts.iam.loginCredential.clientId	string	-	OAuth client ID for IAM login
sts.iam.loginCredential.clientSecret	string	-	OAuth client secret for IAM login
sts.iam.tokenValidation.aud	string	-	Expected audience for IAM token validation
sts.iam.tokenValidation.iss	string	-	Expected issuer for IAM token validation (for example, Keycloak realm URL)
sts.iam.tokenValidation.jwksUri	string	-	JWKS endpoint URL for IAM token verification
jwt.secret	string	-	Secret key for JWT signing/verification

Keycloak Integration

Variable	Type	Default	Description
keycloak.url	string	-	Keycloak server URL (used in development; production deployments may use alternative IAM)
keycloak.realm	string	-	Keycloak realm name

Service Integration

Core Integration

All BFF deployments require integration with the Procivis One Core service.

Variable	Type	Default	Description
core.enabled	boolean	-	Enable Core service integration
core.url	string	-	Core service base URL
core.api.authentication	string	-	Authentication mode: UNSAFE_NONE, UNSAFE_STATIC, or STS
core.api.staticToken	string	-	Static authentication token if using UNSAFE_STATIC mode (must match Core's app.authToken or ONE_app__authToken)
core.history.export.entryLimit	integer	-	Maximum number of entries for history export operations

Frontend Integration

Variable	Type	Default	Description
frontend.url	string	-	Client-facing frontend domain URL
frontend.logoutUrl	string	-	URL to redirect after logout
frontend.walletEnabled	boolean	-	Enable/disable organizational/business wallet endpoints
frontend.walletProviderEnabled	boolean	-	Enable/disable wallet provider (WUA/WAA) endpoints
frontend.profilesEnabled	boolean	-	Enable/disable country profiles feature
frontend.profilesPath	string	-	File path to country profiles JSON configuration
frontend.announcementEnabled	boolean	-	Enable/disable announcement banner
frontend.announcementPath	string	-	File path to announcement JSON configuration
frontend.supportFeatureEnabled	boolean	-	Enable/disable support links feature
frontend.history.enabled	boolean	-	Enable/disable history feature
frontend.history.pagesEnabled	array	-	List of enabled history pages (for example, CREDENTIAL_SCHEMA , PROOF, WALLET_RELYING_PARTY)
frontend.reissueEnabled	boolean	-	Enable/disable credential reissuance feature

Bridge and WRPR Integration

Bridge and WRPR are optional services depending on your deployment requirements.

Variable	Type	Default	Description
bridge.enabled	boolean	-	Enable Bridge service integration
bridge.url	string	-	Bridge service base URL
bridge.api.authentication	string	-	Authentication mode: UNSAFE_NONE, UNSAFE_STATIC, or STS
bridge.api.staticToken	string	-	Static authentication token (must match Bridge's auth.staticToken if using UNSAFE_STATIC mode)
bridge.api.discoveryUrl	string	-	Bridge discovery endpoint URL
wrpr.enabled	boolean	-	Enable WRPR service integration
wrpr.url	string	-	WRPR service base URL
wrpr.api.authentication	string	-	Authentication mode: UNSAFE_NONE, UNSAFE_STATIC, or STS
wrpr.api.staticToken	string	-	Static authentication token (must match WRPR's auth.staticToken if using UNSAFE_STATIC mode)

Session Management

Variable	Type	Default	Description
REDIS_HOST	string	-	Redis server hostname
REDIS_PORT	integer	6379	Redis server port
REDIS_DB	integer	0	Redis database number
REDIS_PASSWORD	string	-	Redis authentication password

Authentication and Login

Variable	Type	Default	Description
login.url	string	-	Login page URL (e.g., ${frontend.url}/login)
forgot.password.url	string	-	Forgot password page URL
forgot.password.pauseTime	integer	-	Cooldown period between password reset requests

Login with Credential

This optional feature allows users to issue themselves a login credential within the Desk UI and use it for authentication.

Variable	Type	Default	Description
login.verification.protocol	string	-	Verification protocol identifier to use for login
login.credential.enabled	boolean	-	Enable/disable user login with verifiable credential
login.credential.issuerDid	string	-	DID to use for issuing login credentials
login.credential.exchange	string	-	Issuance protocol to use for login credentials
login.credential.credentialSchemaId	string	-	Credential schema ID for login credentials
login.credential.organisationId	string	-	Organization UUID for issuing login credentials
login.credential.emailPath	string	-	Claim path for user's email address (typically "email")

Mobile App Integration

Variable	Type	Default	Description
appLink.url	string	-	Base URL for mobile app deep links
appLink.wallet.android.packageName	string	-	Android wallet app package name
appLink.wallet.android.sha256CertFingerPrint	string	-	SHA-256 certificate fingerprint for Android wallet app
appLink.wallet.ios.appId	string	-	iOS wallet app identifier
appLink.verifier.android.packageName	string	-	Android verifier app package name
appLink.verifier.android.sha256CertFingerPrint	string	-	SHA-256 certificate fingerprint for Android verifier app
appLink.verifier.ios.appId	string	-	iOS verifier app identifier

History Configuration

Variable	Type	Default	Description
history.type	string	-	History storage backend type, only REMOTE_REST supported
history.enabled	boolean	-	Enable/disable history; pushes to Core history endpoint

Email Configuration

Variable	Type	Default	Description
spring.mail.host	string	-	SMTP server hostname
spring.mail.port	integer	-	SMTP server port
spring.mail.username	string	-	SMTP authentication username
spring.mail.password	string	-	SMTP authentication password
spring.mail.properties.mail.smtp.auth	boolean	-	Enable SMTP authentication
spring.mail.properties.mail.smtp.starttls.enable	boolean	-	Enable STARTTLS encryption
email.sender	string	-	From address for outgoing emails
email.connection	string	-	Email connection type
email.provider	string	-	Email provider (for example, smtp)

Management and Monitoring

Variable	Type	Default	Description
management.endpoints.access.default	string	-	Default access level for management endpoints
management.endpoint.health.probes.enabled	boolean	-	Enable Kubernetes health probes
management.endpoint.health.access	string	-	Access level for health endpoint (for example, unrestricted)
management.endpoint.info.access	string	-	Access level for info endpoint (for example, unrestricted)
management.endpoint.prometheus.access	string	-	Access level for Prometheus metrics endpoint (for example, unrestricted)
management.health.mail.enabled	boolean	-	Enable mail health check (only if SMTP is configured)

API Documentation (Springdoc)

Variable	Type	Default	Description
springdoc.show-actuator	boolean	-	Include Spring Boot Actuator endpoints in API docs
springdoc.api-docs.version	string	-	OpenAPI specification version (for example, openapi_3_1)
springdoc.packages-to-scan	string	-	Package names to scan for API documentation
springdoc.paths-to-match	string	-	Path patterns to include in API documentation (comma-separated)
springdoc.cache.disabled	boolean	-	Disable API documentation caching
springdoc.swagger-ui.operations-sorter	string	-	Operation sorting method in Swagger UI (for example, alpha)

Application Configuration

Variable	Type	Default	Description
spring.config.import	string	-	Import additional configuration files (for example, environment-specific properties)
spring.profiles.active	string	-	Active Spring profile(s)
spring.main.banner-mode	string	console	Spring Boot banner display mode
app.version	string	-	Application version identifier
app.stacktrace.enabled	boolean	-	Enable/disable stacktrace in error responses
type	string	-	Deployment environment type (for example, localdev)

Data Serialization

Variable	Type	Default	Description
spring.jackson.serialization.write_dates_as_timestamps	boolean	false	Serialize dates as timestamps vs ISO-8601 strings
spring.jackson.default-property-inclusion	string	-	Default property inclusion strategy (for example, NON_NULL)

Logging

Variable	Type	Default	Description
logging.level.org.springframework.security	string	-	Log level for Spring Security (for example, DEBUG, INFO, WARN)

Development and Testing

Variable	Type	Default	Description
test.server.url	string	-	Base URL for test server