Authentication

Energy SOAR Base supports multiple authentication methods, configured in /etc/energysoar/application.conf.d/authentication.conf. Methods are tried in order; the first that succeeds grants access.

Default configuration

auth {
  providers = [
    {
      name: session
      inactivity: 60 minutes
      warning: 10 minutes
    }
    {name: basic, realm: thehive}
    {name: local}
    {name: key}
  ]
  defaultUserDomain: "energysoar.local"
  multifactor.issuer: "Energy SOAR"
}

Authentication methods

session

Handles HTTP session cookies. inactivity closes the session after the specified period of user inactivity. warning triggers a warning in the UI before the session expires.

basic

HTTP Basic Auth. The realm value appears in the browser authentication prompt. Passwords are checked against the local user database.

local

Validates login and password, or API key, against the local user database stored in Energy Logserver.

key

Authenticates API requests using a Bearer token in the Authorization header:

Authorization: Bearer <api-key>

API keys cannot be used to log in to the web interface.

Active Directory

To enable Active Directory authentication, add an ad block to authentication.conf:

auth {
  providers = [
    {name: session, inactivity: 60 minutes, warning: 10 minutes}
    {name: basic, realm: thehive}
    {name: ad}
    {name: local}
    {name: key}
  ]
}

ad {
  dnsDomain = "mydomain.local"
  winDomain = "MYDOMAIN"
  hosts = ["ad1.mydomain.local", "ad2.mydomain.local"]
  useSSL = true
}

Parameters:

dnsDomain — Windows domain name in DNS format. Used to discover domain controllers if hosts is not set.
winDomain — Windows domain name in short (NetBIOS) format.
hosts — Explicit list of domain controller addresses. Optional.
useSSL — Connect to domain controllers over SSL. The JVM trust store is used to validate the remote certificate.

LDAP

To enable LDAP authentication, add an ldap block:

auth {
  providers = [
    {name: session, inactivity: 60 minutes, warning: 10 minutes}
    {name: basic, realm: thehive}
    {name: ldap}
    {name: local}
    {name: key}
  ]
}

ldap {
  hosts = ["ldap.mydomain.local:389"]
  bindDN = "cn=energysoar,ou=services,dc=mydomain,dc=local"
  bindPW = "password"
  baseDN = "ou=users,dc=mydomain,dc=local"
  filter = "(cn={0})"
  useSSL = true
}

Parameters:

hosts — LDAP server addresses. Use host:port syntax.
bindDN — Distinguished name of the service account used to search for users.
bindPW — Password of the service account.
baseDN — Base DN where user entries are located.
filter — Search filter. {0} is replaced with the login entered by the user.
useSSL — Connect over SSL. The JVM trust store validates the certificate.

OAuth2 / OpenID Connect

To enable OAuth2 or OIDC authentication, add oauth2 and sso blocks:

auth {
  providers = [
    {name: session, inactivity: 60 minutes, warning: 10 minutes}
    {name: basic, realm: thehive}
    {name: oauth2}
    {name: local}
    {name: key}
  ]
}

auth.oauth2 {
  clientId = "client-id"
  clientSecret = "client-secret"
  redirectUri = "https://energysoar.example.com/api/ssoLogin"
  responseType = "code"
  grantType = "authorization_code"
  authorizationUrl = "https://auth.example.com/OAuth/Authorize"
  tokenUrl = "https://auth.example.com/OAuth/Token"
  userUrl = "https://auth.example.com/api/User"
  scope = ["openid", "profile"]
}

auth.sso {
  autocreate = false
  autoupdate = false
  autologin = false
  mapper = simple
  attributes {
    login = "user"
    name = "name"
    roles = "roles"
    organization = "org"
  }
  defaultRoles = ["read"]
  defaultOrganisation = "csirt"
}

auth.sso parameters:

autocreate — Create user accounts on first SSO login if the user does not exist locally.
autoupdate — Update user profile and roles on each SSO login.
autologin — Redirect unauthenticated users to the SSO provider automatically.
mapper — Role mapping strategy. simple maps roles from a user attribute; group maps from a group membership attribute.

Multi-factor authentication

MFA is enabled by default. The issuer name shown in authenticator apps is controlled by:

multifactor.issuer: "Energy SOAR"

Users enroll their authenticator from the account settings page in the web interface.