Heimdall Authentication Methods

Heimdall supports multiple authentication methods, please references the Authentication Methods in the Environment Variables Configuration help page.

Warning

Heimdall only supports authentication using the authentication protocol OIDC (OpenID Connect). Currently SAML (Security Assertion Markup Language) is not supported.

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:

External Authentication Methods - Configuration

LDAP

Review the necessary environment variables required for setting up:

• LDAP Authentication
• Google Authentication
• GitHub Authentication
• GitLab Authentication
• Okta Authentication (OpenID)
• Keycloak Authentication (OpenID)
• Any Authentication Method that uses OpenID Protocol

External Authentication Methods - Testing

Testing Heimdall Server Integration with Okta

Note

This integration was tested without a network proxy and may not operate successfully behind a network proxy. Consider this when testing.

Okta is an enterprise service which does not have open source testing servers. To test the Heimdall - Okta integration follow these steps:

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.

Warning

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 what the regular user would need to login rather than the admin domain used for updating the configuration. For example, the Okta domain should be set to something like dev-39038161.okta.com.

Finding the Okta domain

This domain name can be found in the admin console under the user profile:

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: