Heimdall Authentication Methods

Heimdall supports multiple authentication methods:

• External URL
• LDAP
• OAuth Client ID (Google, GitHub, Okta Domain)
• Custom OIDC Service
• Password-based authentication (Local Authentication)

Local Authentication

Local authentication is the minimal and lowest level of authentication, it is accomplished via username password. Strong passwords are enforced. Passwords are encrypted and stored on the application database (only applicable if deployed in server mode).

NOTE: Password encryption is being changed to a FIPS compliant algorithm, for this reason current deployment of Heimdall that make use of Local Authentication must ensure that all users change their passwords during the transition period.

External Authentication Only

Heimdall Server supports disabling local user logins via environment variables. This means only external authentication providers (such as OpenID Connect or LDAP) can be used to login to the server.

To use this feature set the following environment variables:

• LOCAL_LOGIN_DISABLED=true
• ADMIN_USES_EXTERNAL_AUTH=true
• ADMIN_EMAIL=<Your admin's email address>

Instead of the standard prompt, you will be given this message and the option to login with your configured authentication providers:

Testing

Testing Heimdall Server Integration with Okta

NOTE: This integration was tested with the MITRE network disabled and did not operate successfully behind the MITRE network. Consider this when testing. Okta is an enterprise service which does not have open source testing servers. To test the Heimdall - Okta integration:

1. Make a Dev account with Okta that provides a development Okta server. Login or Sign Up Here
2. Make sure you login to the admin console of your Okta developer edition account. It should have a URL like https://dev-39038161-admin.okta.com/admin/getting-started.
3. Follow these instructions from the Okta documentation to create a Heimdall app integration. If you are doing development, this will likely be integrated with your local Heimdall build. Most importantly, the Client ID and Client Secret will be needed as environment variables in the Heimdall deployment and the callback will need to be set appropriately in the Okta integration. NOTE: The Heimdall deployment needs to be SSL enabled, meaning an https build. One way to build Heimdall with https is to use the docker build.

Example Screenshots of Okta integration for local Heimdall app build.

4. Store the client id, client secret, external url, and Okta domain as env variables for Heimdall. Make sure the Okta domain is written without the https:// because the code appends this on. Additionally, make sure the Okta domain is not that for the admin.

Example environment variables:

Most notably are the environment variables required for the Okta integration - OKTA_DOMAIN, OKTA_CLIENTID, OKTA_CLIENTSECRET, and EXTERNAL_URL.

DATABASE_PASSWORD=********************************************************************
JWT_EXPIRE_TIME=1d
JWT_SECRET=********************************************************************
API_KEY_SECRET=********************************************************************
NGINX_HOST=localhost
OKTA_DOMAIN=dev-39038161.okta.com
OKTA_CLIENTID=0oagcmm1noUVRKMxo5d7
OKTA_CLIENTSECRET=********************************************************************
EXTERNAL_URL=https://localhost

5. Build Heimdall, for example, using the docker build to allow for https (http does not work with the Okta integration)
6. Create users in Okta and assign them to the Heimdall application. Users must have a username for it to work correctly.

Example Okta Users: