Configuration

All settings are contained within a .env file when using a Docker production deployment. The file should exist in the root directory for Heimdall^©. If no file exists at .env, then local environment variables will be used. 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.

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 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_KEY_SECRET: API Key Token Secret (no default, API keys are disabled if this is not set)
NODE_ENV: The environment you're deploying Heimdall^© in, for general deployment use production (No default, must be set)
HEIMDALL_HEADLESS_TESTS: Run integration tests in a headless browser (defaults to true)
ADMIN_EMAIL: Email for default admin user (if nothing is provided, defaults to admin@heimdall.local)>
ADMIN_USES_EXTERNAL_AUTH: If the default admin user uses alternative 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)
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)
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)
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)
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)
MAX_FILE_UPLOAD_SIZE: The maximum size for evaluation uploads in megabytes (Defaults to 50)

Alternate 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.

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) **Note: Make sure you set EXTERNAL_URL properly as well.

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)

Your callback URL should be https://<your.heimdall.instance>/authn/google/callback **Note: Make sure you set EXTERNAL_URL properly as well.

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

Your callback URL should be https://<your.heimdall.instance>/authn/github/callback **Note: Make sure you set EXTERNAL_URL properly as well.

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)

Your callback URL should be https://<your.heimdall.instance>/authn/gitlab/callback **Note: Make sure you set EXTERNAL_URL properly as well.

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)

Your callback URL should be https://<your.heimdall.instance>/authn/okta/callback **Note: Make sure you set EXTERNAL_URL properly as well.

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

Your callback URL should be https://<your.heimdall.instance>/authn/oidc/callback **Note: Make sure you set EXTERNAL_URL properly as well.

Note: 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.

Environment Variables Configuration