Environment Variables Configuration

Configuration:

All settings are contained within a .env file. If doing a local/development deployment, then this file should be in the ./apps/backend/. If doing a Docker production deployment, the file should be in the root directory for Heimdall (.). Locally declared environment variables will take precedence over variables defined in the .env file. If any setting described below is not present in either the .env file or in local environment variables, then a default value will be used if applicable.

Tip

Please see the setup-dev-env.(sh/bat) and setup-docker-env.(sh/bat) scripts use to build a partial .env basic configuration file.

Services

Frontend

Heimdall is able to display a classification banner.

• CLASSIFICATION_BANNER_TEXT: If a sensitivity classification banner should be shown to users, for example FOUO (if nothing is provided, no banner is shown)
• CLASSIFICATION_BANNER_TEXT_COLOR: The color of the text on the sensitivity classification banner, if enabled (defaults to white)
• CLASSIFICATION_BANNER_COLOR: The color of the sensitivity classification banner, if enabled (defaults to red)

Backend

Node and environment

• NODE_ENV: The environment you're deploying Heimdall in, for general deployment use production (No default, must be set)
• PORT: The port that Heimdall starts up on. (Defaults to port 3000)

Default administrator

• ADMIN_EMAIL: Email for default admin user (if nothing is provided, defaults to [email protected])>
• ADMIN_USES_EXTERNAL_AUTH: If the default admin user uses alternative/external authentication (if nothing is provided, defaults to false)
• ADMIN_PASSWORD: To specify an administrator password that will be used during initial setup. (Will generate a random password by default, it will only be shown to you during the initial setup)

User account

• LOCAL_LOGIN_DISABLED: If internal user login should be allowed, if not then only alternative authentication providers can be used, (if nothing provided, defaults to false)
• REGISTRATION_DISABLED: If public user registration should be allowed, if not then only the administrator user can create users (defaults to false)
• ONE_SESSION_PER_USER: If users are only allowed to be logged in on one browser (defaults to false)
• JWT_SECRET: JSON Web Token Secret, you can quickly generate this by running openssl rand -hex 128 (No default, must be set)
• JWT_EXPIRE_TIME: How long you want each user session to last (e.g 30m, 1h, 1d. Default is 60s)

API

• API_KEY_SECRET: API Key Token Secret (no default, API keys are disabled if this is not set)
• MAX_FILE_UPLOAD_SIZE: The maximum size for evaluation uploads in megabytes (Defaults to 50)

Database

• DATABASE_HOST: The host where your PostgreSQL instance is running (Defaults to 127.0.0.1)
• DATABASE_PORT: The host where your PostgreSQL instance is running (Defaults to 5432)
• DATABASE_USERNAME: Username to authenticate to the database (Defaults to postgres)
• DATABASE_PASSWORD: Password to authenticate to the database (Defaults to no password)>
• DATABASE_NAME: Name of the database (Defaults to heimdall-server-{$NODE_ENV})
• DATABASE_SSL: Whether or not to use SSL certificate authentication (if nothing is provided, defaults to false)
• DATABASE_SSL_INSECURE: Whether or not to ignore SSL issues (security risk if enabled, if nothing is provided, defaults to false)
• DATABASE_SSL_KEY: Full path to SSL key OR the key itself (no default, must be set if using SSL)
• DATABASE_SSL_CERT: Full path to SSL certificate OR the certificate itself (no default, must be set if using SSL)
• DATABASE_SSL_CA: Full path to SSL certificate authority OR the certificate authority itself (no default, must be set if using SSL)

Reverse proxy

• NGINX_HOST: Templated out as the 'server_name' for the NGINX configuration (no default, must be set if using the provided example NGINX configuration)

---

External Interfaces

Heimdall is capable of connecting to external interfaces for the purposes of retrieving scans. Due to the Content Security Policy implemented by Heimdall Server it is necessary to provide the external host URL for each specific interface on the appropriate environment variable. The following variables are used for external interfaces:

• SPLUNK_HOST_URL: The full Uniform Resource Locator (URL) without the port for the Splunk host.
• TENABLE_HOST_URL: The full Uniform Resource Locator (URL) without the port for the Tenable.SC host.

Example SPLUNK_HOST_URL=https://my.splunk.com TENABLE_HOST_URL=https://tenable.myorganiztion.org

Note

If trying to access services from another domain and the URL variable is not set, the request is blocked because it violates the content security policy directive.

Important

If the browser being used has CORS enable, it is necessary to disabled, references Tenable.SC CORS Configuration for instruction on how to disable CORS on the browser.

---

Authentication

Heimdall Server supports multiple methods of authentication, currently we support:

• Local Authentication
• LDAP/Active Directory
• Google OAuth
• GitHub (Public/Enterprise) OAuth
• GitLab OAuth
• Okta OAuth
• OpenID Connect

Using alternative authentication providers will create a local user that will automatically update user information on every login. Users will not be able to update their information, instead they will be presented with the message "Some of the settings are managed by your identity provider".

If you would like support for another system, please open a feature request here.

Important

Most strategies has their own values for Client ID, Client Secret, and extras (detailed below). However, when setting up alternate authentication, the EXTERNAL_URL (see example below) variable is require.

• EXTERNAL_URL: The external URL for your Heimdall deployment, for example https://heimdall.mitre.org. (No default, must be set)

LDAP:

The default values are centered towards Active Directory, but Heimdall will work with most standard LDAP setups.

• LDAP_ENABLED: If you want to enable LDAP login (Defaults to false)
• LDAP_HOST: Your LDAP target server (No default, must be set if using LDAP)
• LDAP_PORT: Your LDAP target port (Defaults to 389)
• LDAP_BINDDN: The Dn of the user you will use for lookups (No default, must be set if using LDAP)
• LDAP_PASSWORD: The password for the previously specified BindDN (No default, must be set if using LDAP)
• LDAP_SEARCHBASE: The organizational unit you want to search for users in (If using standard AD configuration you probably want "OU=Users, DC=<yourdomain>, DC=local". No default, must be set if using LDAP)
• LDAP_SEARCHFILTER: Your LDAP search filter (Defaults to sAMAccountName={{username}} for AD users)
• LDAP_NAMEFIELD: The field that contains your LDAP users' full name. (Defaults to name for AD users)
• LDAP_MAILFIELD: The field that contains your LDAP users' email address. (Defaults to mail for AD users)
• LDAP_SSL: Whether or not to use SSL certificate authentication (if nothing is provided, defaults to false)>
• LDAP_SSL_INSECURE: Whether or not to ignore SSL issues (security risk if enabled, if nothing is provided, defaults to false)>
• LDAP_SSL_CA: Full path to SSL certificate authority OR the certificate authority itself (no default, must be set if using SSL)>

Google:

Create a Google Cloud Platform project and enable Oauth 2.0. For more instructions see this.

• GOOGLE_CLIENTID: Your application's client ID (Looks like xxxxxxx.apps.googleusercontent.com. No default, must be set if using Google login)
• GOOGLE_CLIENTSECRET: Your application's client secret (No default, must be set if using Google Login)

Note

Your callback URL should be https://<your.heimdall.instance>/authn/google/callback

Tip

Make sure to set the EXTERNAL_URL variable to the correct domain that is hosting the Heimdall server.

GitHub:

You can use a GitHub OAuth App for this. Generate one here.

• GITHUB_CLIENTID: Your application's client ID (No default, must be set if using GitHub login)
• GITHUB_CLIENTSECRET: Your application's client secret (No default, must be set if using GitHub login)
• GITHUB_ENTERPRISE_INSTANCE_BASE_URL: GitHub Enterprise Instance Base URL (Defaults to https://github.com/)
• GITHUB_ENTERPRISE_INSTANCE_API_URL: GitHub Enterprise Instance API URL (Defaults to https://api.github.com/)

Note

Your callback URL should be https://<your.heimdall.instance>/authn/github/callback

Tip

Make sure to set the EXTERNAL_URL variable to the correct domain that is hosting the Heimdall server.

GitLab:

Use a GitLab application for this, generate one here.

• GITLAB_CLIENTID: Your application's client ID (No default, must be set if using GitLab login)
• GITLAB_CLIENTSECRET: Your application's client secret (No default, must be set if using GitLab login)
• GITLAB_BASEURL: The base URL for your Gitlab instance (Defaults to https://gitlab.com)

Note

Your callback URL should be https://<your.heimdall.instance>/authn/gitlab/callback

Tip

Make sure to set the EXTERNAL_URL variable to the correct domain that is hosting the Heimdall server.

Okta:

Create an OAuth 2.0 app in Okta. For more instructions see this.

Okta integration is only successful with SSL enabled Heimdall deployments, i.e. https://<your-heimdall-instance>. Okta integration is also only available using OIDC - OpenID Connect as the Sign-in method.

During the process of adding a client application (Heimdall) to use the Okta APIs the Client Id and Client Secret values are generated.

• OKTA_DOMAIN: Your assigned Okta domain (No default, must be set if using Okta login)
• OKTA_CLIENTID: Your application's client ID (No default, must be set if using Okta login)
• OKTA_CLIENTSECRET: Your application's client secret (No default, must be set if using Okta login)

Note

Your callback URL should be https://<your.heimdall.instance>/authn/okta/callback

Tip

Make sure to set the EXTERNAL_URL variable to the correct domain that is hosting the Heimdall server.

To test development for Okta integration, reference this wiki.

OpenID Connect

Use your own services supporting the OpenID Connect Standard.

• OIDC_NAME: What you want your authentication method to be named within Heimdall (No default, must be set if using OIDC login)
• OIDC_ISSUER: Your OIDC base URL, for example: https://sample.us.auth0.com (No default, must be set if using OIDC login)
• OIDC_AUTHORIZATION_URL: Your OIDC authorization endpoint, for example: https://sample.us.auth0.com/authorize (No default, must be set if using OIDC login)
• OIDC_TOKEN_URL: Your OIDC token endpoint, for example: https://sample.us.auth0.com/oauth/token (No default, must be set if using OIDC login)
• OIDC_USER_INFO_URL: Your OIDC user info endpoint, for example: https://sample.us.auth0.com/userinfo (No default, must be set if using OIDC login)
• OIDC_CLIENTID: Your OIDC Client ID (No default, must be set if using OIDC login)
• OIDC_CLIENT_SECRET: Your OIDC Client Secret (No default, must be set if using OIDC login)
• OIDC_EXTERNAL_GROUPS: Synchronize user groups from external OIDC provider; Groups are not created automatically, users are only mapped into existing groups - true or false (defaults to false if not provided). NOTE: Not recommended if you have any other authentication methods enabled.

Note

Your callback URL should be https://<your.heimdall.instance>/authn/oidc/callback

Tip

Make sure to set the EXTERNAL_URL variable to the correct domain that is hosting the Heimdall server.

Important

All user emails must be "verified" by your OIDC provider to prevent unauthorized access. With Keycloak for example, this is a field on the user's page in settings.**