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 the oauth2 provider and configure it under auth.defaults.oauth2:

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

auth.defaults.oauth2 {
  clientId = "client-id"
  clientSecret = "client-secret"
  redirectUri = "https://energysoar.example.com/api/ssoLogin"
  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"]
  userIdField = "email"
  authorizationHeader = "Bearer"
  # Optional
  organisationField = "org"
  defaultOrganisation = "csirt"
}

auth.defaults.oauth2 parameters:

clientId / clientSecret — Credentials issued by the identity provider. Required.
redirectUri — Callback URL registered with the provider. It must end with /ssoLogin. Required.
grantType — OAuth2 grant type. Only authorization_code is supported. Required.
authorizationUrl — Provider endpoint that issues the authorization code. Required.
tokenUrl — Provider endpoint that exchanges the code for an access token. Required.
userUrl — Provider endpoint that returns the authenticated user’s profile. Required.
scope — List of scopes requested from the provider. Required.
userIdField — Field in the userUrl response used as the login. Required.
authorizationHeader — Scheme prefix sent with the token to userUrl, for example Bearer. Required.
organisationField — Optional. Field in the userUrl response naming the user’s organisation.
defaultOrganisation — Optional. Organisation used when organisationField is absent from the response.

Note

The response type is always code. There is no responseType setting.

To create accounts automatically on first SSO login, enable auto-provisioning in the user block:

user {
  autoCreateOnSso = true
  profileFieldName = "profile"
  organisationFieldName = "organisation"
  defaults {
    profile = "analyst"
    organisation = "csirt"
  }
}

user parameters:

autoCreateOnSso — Create a user account on first SSO login when it does not exist locally. Defaults to false.
profileFieldName — Field in the SSO user profile naming the security profile to assign.
organisationFieldName — Field in the SSO user profile naming the organisation to assign.
defaults.profile — Profile assigned when profileFieldName is missing from the response.
defaults.organisation — Organisation assigned when organisationFieldName is missing from the response.

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.