Environment Variables Configuration

Files:

All settings are contained within apps/backend/.env, or .env-prod when using a Docker production deployment. If no file exists at apps/backend/.env, then environment variables will be used.

Configuration:

Heimdall is configured using a .env config file or environment variables. If any setting described below is not present then a default value will be used.

Recommended:

• PORT: The port that Heimdall starts up on. (Defaults to port 3000)
• 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})
• JWT_SECRET: JSON Web Token Secret, you can quickly generate this by running 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)
• NODE_ENV: The environment you're deploying Heimdall in, for general deployment use production (No default, must be set)
• 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)
• EXTERNAL_URL: The external URL for your Heimdall deployment, for example https://heimdall.mitre.org. When setting up alternate authentication, you should use this host as a valid callback domain. (No default, must be set)
• MAX_FILE_UPLOAD_SIZE: The maximum size for evaluation uploads in megabytes (Defaults to 50)
• HEIMDALL_HEADLESS_TESTS: If integration tests should run in headless mode (Defaults to true)
• REGISTRATION_DISABLED: If public user registration should be allowed, if not then only the administrator user can create users (Defaults to false)

---

Alternate Authentication

Heimdall 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

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

Most strategies has their own values for Client ID, Client Secret, and extras.

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)

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)

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/)

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)

Okta:

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

• 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)

Open ID Connect

Use your own services supporting the Open ID 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)