Environment Variables Configuration - mitre/heimdall2 GitHub Wiki
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.
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)
Node and environment
-
NODE_ENV
: The environment you're deploying Heimdall in, for general deployment useproduction
(No default, must be set) -
PORT
: The port that Heimdall starts up on. (Defaults to port3000
)
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 tofalse
) -
JWT_SECRET
: JSON Web Token Secret, you can quickly generate this by runningopenssl 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 is60s
)
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 to50
)
-
DATABASE_HOST
: The host where your PostgreSQL instance is running (Defaults to127.0.0.1
) -
DATABASE_PORT
: The host where your PostgreSQL instance is running (Defaults to5432
) -
DATABASE_USERNAME
: Username to authenticate to the database (Defaults topostgres
) -
DATABASE_PASSWORD
: Password to authenticate to the database (Defaults to no password)> -
DATABASE_NAME
: Name of the database (Defaults toheimdall-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)
-
NGINX_HOST
: Templated out as the 'server_name' for the NGINX configuration (no default, must be set if using the provided example NGINX configuration)
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.
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 examplehttps://heimdall.mitre.org
. (No default, must be set)
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 tosAMAccountName={{username}}
for AD users) -
LDAP_NAMEFIELD
: The field that contains your LDAP users' full name. (Defaults toname
for AD users) -
LDAP_MAILFIELD
: The field that contains your LDAP users' email address. (Defaults tomail
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)>
Create a Google Cloud Platform project and enable Oauth 2.0. For more instructions see this.
-
GOOGLE_CLIENTID
: Your application's client ID (Looks likexxxxxxx.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.
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 tohttps://github.com/
) -
GITHUB_ENTERPRISE_INSTANCE_API_URL
: GitHub Enterprise Instance API URL (Defaults tohttps://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.
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 tohttps://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.
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.
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.**