Wallet Server Application Config

The configuration details required under the wallet.config parameter are:

Authorization Server domain name, clientid and secret (eg. https://authserver, clientid, secret)
Wallet Server domain name (eg. https://walletserver)
Wallet Web UI domain name (eg. https://walletui)
Wallet Native url scheme (eg. com.identos.wallet)
Database host, dbname, username and password (eg. dbhost, dbwallet, dbusername, dbpassword)

Using Verifiable Credentials

Verifiable Credentials is an optional feature for the FPX Wallet that needs to be enabled via specific configuration parameters under wallet.config. The sample YAML shown in this section does not contain these optional parameters. Refer to the Verifiable Credentials chapter for more details on the specific configuration required to enable this feature.

A sample YAML file is shown below followed by a detailed description of each parameter listed here, whether it's a required parameter and accepted values.

      server.tomcat.remote_ip_header: x-forwarded-for
      server.tomcat.protocol_header: x-forwarded-proto
      server.tomcat.use-relative-redirects: true
      server.error.whitelabel.enabled: false
      server.port: 8084
      timezone: UTC

      i18n:
        defaultLang: en
        allLanguages: fr, en
        basename: classpath:./i18n/messages
        cacheEvictFixedRateString: PT30S

      cors:
        origins:
          - http://wallet-ui.demourl

      idp:
        user:
          account:
            idpManageUrl: https://<IDP_Account_Management_URL>/
            idpUserDeleteEnabled: false
            idpUserDeleteUrl: https://<IDP_Account_Deletion_Endpoint_URL>

      logging:
        level:
          com.identos.fpxwallet.walletserver: DEBUG
          org.hibernate.SQL: DEBUG
          org.hibernate.type: DEBUG
        config: classpath:logback-dev.xml
      
      pending-auth-request:
         requestExpiryInseconds: 1800

      mobile-permission-path: consent_request
      mobile-host: com.identos.custom.schema.url://fpx-wallet/
      server-host: http://wallet.demourl
      web-host: http://wallet-ui.demourl
      oidc:
        provider:
          issuer: ${server-host}
        client:
          redirectHost: ${server-host}

      navigator:
        fallbackBaseUrl: ${web-host}
        redirects:
          - baseUrl: ${mobile-host}
            idpPath: /oauth_callback
            consentPath: ${mobile-permission-path}
            dsPath: /oauth_callback
            errorPath: /error
          - baseUrl: ${web-host}
            idpPath: /idp-callback
            consentPath: /as-authorize
            dsPath: /rs-callback
            errorPath: /login
            errorPageRedirectUrl: ${web-host}/login

      app:
        device:
          verificationUrl: ${mobile-host}${mobile-permission-path}
        idpUserDeleteUrl: https://<IDP_Account_Deletion_Endpoint_URL>
        logo: "identos.png"
        name: An app name
        errorPageRedirectUrl: ${web-host}/login
        errorPageTitle: Error


      fpxwallet.walletserver.resources.login-page.css: ${server-host}/style.css
      idp.user.account.delete.enable: false

      # --------------------
      # Database and Spring Defaults
      # --------------------
      spring:
        session:
          store-type: jdbc
          jdbc:
            initialize-schema: always
            table-name: SPRING_SESSION
        thymeleaf:
          cache: false
          prefix: classpath:./templates/
        datasource:
          driverClassName: com.mysql.cj.jdbc.Driver
          url: jdbc:mysql://wallet-database-url/wallet?createDatabaseIfNotExist=true
          username: exampleuser
          password: examplepassword
        jpa:
          hibernate.ddl-auto: validate
          generate-ddl: false
          show-sql: false
          open-in-view: false
        flyway:
          enabled: true
          locations: classpath:db/development
        mvc:
          throw-exception-if-no-handler-found: true
          pathmatch.matching-strategy: ant_path_matcher
        web:
          resources:
            add-mappings: false
        mountFile:
        - filename: messages_en.properties 
          identifier: i18n-en
          folderpath: "/etc/config/"
          data: |-
            error_title=Session timed out
            ontario_trusted_account=CareHub account
            session_timed_out_title=Session Timed Out
            session_timed_out_message=Your session timed out. Please restart your account set up process.
            try_again=Please Start Again
            no_script=You need to enable JavaScript to run this app.
            redirect_to_app=Redirect to native app
            oauth_success_title=Access your account
            oauth_success_message=To complete this flow and access your account, you must return to your Navigator app.            
            oauth_success_button=Continue in the Navigator

Global Server Parameters

Configuration directives that are used for overall application configuration.

Parameter	Description	Suggested Value	Required
server.tomcat.remote_ip_header	Header to use as remote IP address for client connections.	x-forwarded-for	Yes
server.tomcat.protocol_header	Header to use as remote protocol for client connections.	x-forwarded-proto	Yes
server.tomcat.use-relative-redirects	When redirecting, assume links are relative.	True	Yes
server.port	Application port to listen for client connections on.	8080
server.error.whitelabel.enabled	Enable built in spring configuration file.	false	Yes
spring.thymeleaf.prefix	Location of template files for Wallet selection and error pages. Can use external sources such as https://	classpath:./templates/	Yes
spring.resources.static-locations	Location of static files such as css/html/javascript for template files.	classpath:./static/	Yes
mobile-host	This property is the URI to a mobile frontend application.	com.identos.demo.wallet://fpx-wallet/	Yes
web-host	This property is the URL for the Wallet frontend application.		Yes
server-host	This property is the URL of the Wallet Server.	http://localhost:8084	Yes
fpxwallet.walletserver.resources.login-page.css	This property is configured to set the path to the CSS file for default theme.	`${server-host}/style.css`	Yes
spring.mvc.throw-exception-if-no-handler-found	Returns an exception for 404 errors and allows the administrator to define a custom response	true	Yes
spring.web.resources.add-mappings	Defines whether to use spring default resource mappings - default mappings have been replaced with specifically configured mappings	false	Yes
spring.mvc.pathmatch.matching-strategy	This parameter is related to the spring.web.resources.add-mappings parameter and enables mapping via an ant path.	ant_path_matcher	Yes

Identity Provider Configuration

Parameter	Description	Suggested Value	Required
idp.user.account.idpManageUrl	An endpoint that can be exposed by an identity provider to allow the Wallet Server to manage the user's account.	`{{an-identity-provider-account-management-url}}`	Yes
idp.user.account.idpUserDeleteEnabled	When receiving a request to delete a user's account, this parameter determines whether the Wallet will delete the user's account at the Identity Provider in addition to deleting the account at the Wallet.	false	Yes
idp.user.account.idpUserDeleteUrl	An endpoint that can be exposed by an identity provider which allows the Wallet to delete the user's account at with the provider.	`{{an-identity-provider-account-deletion-url}}`	Yes

Localization

Configuration directives for localization support.

Parameter	Description	Suggested Value	Required
i18n.defaultLang	Default language used for localization.	en	Yes
i18n.allLanguages	Comma separated list of language strings to support localization for i.e. "en, fr".	en	Yes
i18n.basename	Location for localization strings to use in static template files.	classpath:./i18n/messages	Yes
i18n.cacheEvictFixedRateString:	Defines the frequency for cached localized string (locale,key) to be evicted and re-located from a source.	PT8H	No
i18n.useCodeAsDefaultMessage:	Whether the unresolved localization code (key) will be returned in API responses that contain localizeable fields, in cases where there is no localization message corresponding to that code in the language_translations table	false	No, defaults to false

Logging

Parameter	Description	Suggested Value	Required
logging	See https://docs.spring.io/spring-boot/docs/2.3.5.RELEASE/reference/html/spring-boot-features.html#boot-features-logging for logging customizations.	null	No
logging.level.com.identos	Controls the level at which the application's configured loggers will be permitted to log. This applies only to loggers that exist in a package that begins with "com.identos"	DEBUG	No. If not set, defaults to INFO level.
logging.config	Sets the configuration file for application logging. This value will output structured logs in compressed, single-line JSON format. To view the logs in a human-readable format (i.e. for development purposes), this value can be set to `classpath:logback-dev.xml`.	classpath:logback-spring.xml	No. If not set, defaults to classpath:logback-spring.xml.

Pending Auth Request

Parameter	Description	Suggested Value	Required
pending-auth-request.requestExpiryInseconds	The pending-auth-request is an outgoing authorization request to either an identity provider or a resource server during a wallet account login or the data source connection flow. This parameter defines, in seconds, for how long the pending-auth-request stays valid. If the pending-auth-request reaches its expiry time before the user is able to complete authentication to login or to connect to a data source, the wallet server will reject the request and the user will be redirected to an error page.	1800	No, default value is 600

Database Configuration

Database configuration for the Wallet Server

Parameter	Description	Suggested Value	Required
spring.flyway.enabled	Enable or disable automatic Flyway migrations.	true	Yes
spring.flyway.locations	Location for DB migration scripts.	classpath:db/migration,classpath:db/development	Yes
spring.datasource.driverClassName	Driver to use for DB connections (only MySQL supported).	com.mysql.cj.jdbc.Driver	Yes
spring.datasource.url	Driver to use for DB connections.	jdbc:mysql://database-hostname/wallet?createDatabaseIfNotExist=true	Yes
spring.datasource.username	Username for database connection.	username	Yes
spring.datasource.password	Password for database connection.	password	Yes
spring.jpa.hibernate.ddl-auto	Validate database structure on startup.	validate	Yes
spring.jpa.show_sql	Show all SQL queries that are run against the database source in the logs.	false	No
spring.jpa.generate_ddl	A flag that determines whether a SQL Database should be initialized at startup.	true	Yes

OIDC Configuration Settings

OIDC configuration settings including both client / server settings.

Parameter	Description	Suggested Value	Required
oidc.client.redirectHost	Hostname to use for redirect URIs back to Wallet server after authorization	https://walletserver.com	Yes
oidc.provider.issuer	Issuer URL when acting as an OIDC provider	https://walletserver.com	Yes
oidc.provider.jwksEndpoint	Endpoint that contains JWKS for private key authentication	/jwks	No

Navigator Configuration

Configuration for Web + Mobile IDENTOS Navigator configuration as a Wallet user interface

Parameter	Description	Suggested Value	Required
navigator.fallbackBaseUrl	Web Wallet Client URL to fallback to if other Navigator URLs don't work	https://ui.walletserver.com	Yes
navigator.redirectInterval	Frequency at which the Wallet Server should cycle through the list of navigators when trying to redirect to one	50	no
navigator.useIntermediateCallbackUI	Show intermediate page during redirect from Wallet server to Wallet user agent	false	no
navigator.redirects.baseUrl	Base URL for a Navigator	com.identos.custom.schema.url://fpx-wallet/	Yes
navigator.redirects.idpPath	Path at a a Navigator that the Wallet Server will redirect to after connecting to an Identity Provider	com.identos.custom.schema.url://fpx-wallet	Yes
navigator.redirects.consentPath	Path for the Navigator to gather consent with end user during an authorization grant request	/consent	Yes
navigator.redirects.dsPath	Path for the Navigator to be redirected to at the end of connecting to an data source	/consent	Yes
navigator.redirects.errorPath	Path for the Navigator to be to redirected when something goes wrong	/consent	Yes
app.device.verificationUrl	Redirect path for mobile user agent for verification	com.identos.wallet://fpx-wallet/consent_request	Yes
app.device.userCodeExpiry	Expiry in seconds for user code	240000	No
app.device.confirmationCodeExpiry	Expiry in seconds for confirmation code	240000	No
app.device.accessTokenExpiry	Access token expiry in seconds	240000	No
app.sessionlength.platforms.ios	Maximum session length on iOS	600000	No
app.sessionlength.platforms.android	Maximum session length on android	600000	No
app.sessionlength.platforms.web	Maximum session length on web	3600000	No
app.sessionlength.defaultLifeTime	Default session length	3600000	No
app.logo	Filename of the image to be used as the application logo.	logo.png	No
app.name	Name of the application displayed on the error page.	Sample Application	No
app.error-page-redirect-url	Redirect URL when redirecting from the default error page. Note: The Wallet Server implements a custom error redirection scheme that can be configured using a property found in the Navigator Configuration section: `navigator.redirects.errorPath`.	Yes
app.error-page-title	Name of the error page as displayed on the error page header.	Error	No
cors.origins	List of web origins to accept traffic from.	https://ui.walletserver.com/idp-callback	Yes
fpxwallet.walletserver.resources.login-page.css	Path to CSS file for default theme.	https://walletserver.com/style.css	Yes

Global Server Parameters​

Identity Provider Configuration​

Localization​

Logging​

Pending Auth Request​

Database Configuration​

OIDC Configuration Settings​

Navigator Configuration​