The configuration of both front-end (web application) and the back-end (RESTful API) were designed to be done solely through environment variables. This allows for the maximum amount of flexibility in deployment options and architectures.
Reading through this guide there are a couple of items to note:
- Boolean values follow the practice of being true when any value is present and false when empty
- The use of curly brackets (the
{and}) signify placeholders in a value - Italics are used to convey something and are not to be misinterpreted as a value
When running the application using the provided docker-compose.yml configuration several of these settings are preconfigured such as database connection information. These may be overridden by specifying the values directly in the .env file.
| Environment Variable | Required | Front-end (web) | Back-end (api) |
|---|---|---|---|
NODE_ENV |
X | X | |
GOLANG_ENV |
X | X | |
LOG_LEVEL |
X | ||
LOG_FILE |
X | ||
LOG_SYSLOG |
X | ||
LOG_SYSLOG_CERT |
X | ||
SESSION_TIMEOUT |
X | X | |
API_REDIRECT |
X | ||
API_BASE_URL |
X | X | X |
PORT |
X | ||
HASH_ROUTING |
X | ||
DB_MIGRATION_TARGET |
X | ||
DATABASE_URI |
X | ||
DATABASE_USER |
X | ||
DATABASE_PASSWORD |
X | ||
DATABASE_NAME |
X | ||
DATABASE_HOST |
X | ||
CORS_ALLOWED |
X | X | |
FLUSH_STORAGE |
X | ||
USPS_API_API_KEY |
X | ||
JWT_SECRET |
X | X | |
BASIC_ENABLED |
X | X | |
SAML_ENABLED |
X | X | |
SAML_PUBLIC_CERT |
X | ||
SAML_PRIVATE_CERT |
X | ||
SAML_IDP_SSO_URL |
X | ||
SAML_IDP_SSO_DESC_URL |
X | ||
SAML_IDP_PUBLIC_CERT |
X | ||
SAML_SIGN_REQUEST |
X | ||
SAML_CONSUMER_SERVICE_URL |
X | ||
DISABLE_2FA |
X | X | |
ALLOW_2FA_RESET |
X | ||
WINDOW_SIZE |
X | ||
TLS_CERT |
X | ||
TLS_KEY |
X | ||
WS_ENABLED |
X | X | |
WS_URL |
X | X | |
WS_KEY |
X | X | |
WS_CALLERINFO_AGENCY_ID |
X | X | |
WS_CALLERINFO_AGENCY_USER_SSN |
X | X | |
WS_CALLERINFO_AGENCY_USER_PSEUDOSSN |
X | X | |
WS_AGENCY_ID |
X | X | |
WS_AGENCY_GROUP_ID |
X | X | |
ATTACHMENTS_ENABLED |
X | X | |
FILE_MAXIMUM_SIZE |
X | X | |
FILE_TYPES |
X | X | |
COOKIE_DOMAIN |
X |
Sets the Node environment to configure the application for a specific uses:
test: used with unit testing and code coveragedevelopment: for use while developing the applicationstaging: environment for various usability tests prior to releasing to productionproduction: minify and optimize all possible assets for optimal use
Target - Front-end (web)
Default - development
Values - test | development | staging | production
Sets the Go environment to configure the application for specific uses:
test: used with unit testing and code coveragedevelopment: for use while developing the applicationstaging: environment for various usability tests prior to releasing to productionproduction: compiled for production use only minimum required assets (does not include test accounts)
Target - Back-end (api)
Default - development
Values - test | development | staging | production
Log level for the back-end API. The default source for logging will be standard outputs (stdout and stderr).
Target - Back-end (api)
Default - warning
Values - debug | info | warning | error | fatal | panic
Path to the local file system log file.
Logging to file may be used in conjunction with other logging sources.
Target - Back-end (api)
Default - not enabled
Connection string for a syslog server such as udp://logserver:514. Both TCP and UDP are supported.
Logging to syslog may be used in conjunction with other logging sources.
Target - Back-end (api)
Default - not enabled
Values - {protocol}://{host}:{port}
Providing a path to the PEM certificate will convert all syslog communication to use TLS. Only TCP + TLS is supported making the connection string tcp://logserver:514.
Logging to syslog may be used in conjunction with other logging sources.
Target - Back-end (api)
Default - not enabled
Session timeout in minutes. Periods of inactivity falling outside of the threshold will be considered invalid and are required to be re-authenticated.
Target - Front-end (web), Back-end (api)
Default - 15
Front-end URL for the back-end to redirect responses to. If this value is not set it will redirect to the same server host but on port 80.
Target - Back-end (api)
Default - {server_protocol}://{server_host}
Back-end URL for the front-end to direct requests to.
Target - Front-end (web), Back-end (api)
Default - {server_protocol}://{server_host}:{server_port}/api
Port to use for back-end API.
Target - Back-end (api)
Default - 3000
Flag to enable hash routing. This should only be used in scenarios where push state is not an option.
Target - Front-end (web)
Default - False: empty
Values - True: 1, False: empty
Target a specific database migration step for example, 20180212130825_account_lock.sql. By specifying a target then when migrations are ran it will try to step down or up until the target is reached. By not providing a value migrations will always attempt to go to the latest version.
Target - Back-end (api)
Default - not enabled
PostgreSQL database connection string. If a value is set do no set other database connection information.
Target - Back-end (api)
Default - none
Values - postgres://{db-username}:{db-password}@{db-host}:5432/{db-name}
PostgreSQL database user name.
Target - Back-end (api)
Default - postgres
PostgreSQL database password.
Target - Back-end (api)
Default - none
PostgreSQL database instance name.
Target - Back-end (api)
Default - postgres
PostgreSQL database host name and port.
Target - Back-end (api)
Default - localhost:5432
Whitelist of address(es) for cross-origin resource sharing (CORS). CORS restricts resources (e.g. fonts, scripts, images) on a web page to be requested from another domain outside of the domain from which it is served.
| Type | Example |
|---|---|
| explicit | http://localhost |
| multiple | http://localhost;https://test\.com |
| wildcard | * |
| regular expression | https?://localhost |
Target - Back-end (api)
Default - empty
Flag to enable flushing of persisted information for an account during the logon process.
Target - Back-end (api)
Default - False: empty
Values - True: 1, False: empty
United States Postal Service (USPS) API key for address validation.
Target - Back-end (api)
Default - not enabled
The HS256 algorithm is used to sign each JavaScript Web Token using a secret random key of at least 256-bits. For example, openssl rand -base64 32 generates an appropriate key. If this value is not specified, one will be automatically generated unique to the instance.
Target - Back-end (api)
Default - none
Flag to enable basic username and password authentication.
Target - Front-end (web), Back-end (api)
Default - False: empty
Values - True: 1, False: empty
Flag to enable SAML authentication.
Target - Front-end (web), Back-end (api)
Default - False: empty
Values - True: 1, False: empty
File path (absolute or relative) to SAML public certificate.
Target - Back-end (api)
Default - not enabled
File path (absolute or relative) to SAML private certificate.
Target - Back-end (api)
Default - not enabled
Endpoint to SAML 2.0 Single Sign-On (SSO) identity provider. The client will be redirected to this URL to complete the authentication process. This value will be provided by the IdAM configuration settings.
Target - Back-end (api)
Default - not enabled
The identity provider's issuer URL. This value will be provided by the IdAM configuration settings.
Target - Back-end (api)
Default - not enabled
File path (absolute or relative) to identity data provider's public certificate (X.509 PEM) used to verify the authentication response signature. This certificate will be provided by the IdAM solution.
Target - Back-end (api)
Default - not enabled
Flag to enable signing of SAML 2.0 requests.
Target - Back-end (api)
Default - False: empty
Values - True: 1, False: empty
Endpoint for assertion consumer service. After authentication is completed the customer will be redirected to this endpoint for local processes to verify and handle the response.
Target - Back-end (api)
Default - {API_BASE_URL}/auth/saml/callback
Flag to disable multiple factor authentication (MFA) authentication.
Target - Front-end (web), Back-end (api)
Default - False: empty
Values - True: 1, False: empty
Flag to allow resetting multiple factor authentication (MFA) association to an account.
Target - Front-end (web), Back-end (api)
Default - False: empty
Values - True: 1, False: empty
Window size used in multiple factor authentication (MFA) authentication. Valid range from 0 to 100 but values beyond 3 through 5 are considered bad security practices.
Target - Back-end (api)
Default - 3
File path (absolute or relative) to TLS public certificate (X.509 PEM) certificate for use with the back-end API.
Target - Back-end (api)
Default - not enabled
File path (absolute or relative) to TLS private key (X.509 PEM) for use the back-end API.
Target - Back-end (api)
Default - not enabled
Determines whether to enabled the submission to the eqip webservice
Target - Back-end (api)
Default - True
Values - True: 1, False: empty
The endpoint for the OPM web service used to submit the package for investigation.
Target - Back-end (api)
Default - not enabled
File path to private certificate key (PKCS#8 DER) used to sign security tokens for the OPM web service.
Target - Back-end (api)
Default - not enabled
Provided by OPM representing the caller's agency.
Target - Back-end (api)
Default - empty
Provided by OPM representing the caller's agency user making the web service call. The value should not be a valid SSN.
Target - Back-end (api)
Default - empty
Flag representing whether or not the caller has an SSN.
Target - Back-end (api)
Default - empty
Values - True: 1, False: 0
Provided by OPM representing the destination agency.
Target - Back-end (api)
Default - empty
Provided by OPM representing the destination agency's group.
Target - Back-end (api)
Default - empty
Flag to enable uploading and management of attachments within the application.
Target - Front-end (web), Back-end (api)
Default - True: 1
Values - True: 1, False: empty
Maximum file size allowed for attachment files. This also needs to be applied to any additional configurations such as proxies or web servers which are in front of the services.
Target - Front-end (web), Back-end (api)
Default - 5000000
Allowed file extensions for attachments.
Target - Front-end (web), Back-end (api)
Default - .tiff;.png;.pdf
The domain to scope the SAML authentication cookie to. Must be setable by the backend and readable by the frontend. A leading . indicates that any subdomains are in scope. For example, .eapp.example.com would allow backend.eapp.example.com to set the cookie and frontend.eapp.example.com to read it.
Target - Back-end (api)
Default - The host component of the API_REDIRECT value