Configuring authentication

This page describes StackState version 4.0.

The StackState 4.0 version range is End of Life (EOL) and no longer supported. We encourage customers still running the 4.0 version range to upgrade to a more recent release.

Go to the documentation for the latest StackState release.

Out of the box, StackState is configured with file-based authentication, which authenticates users against a file on the server. In addition to this mode, StackState can also authenticate users against the following authentication servers:

When a user is authenticated, the user has one of two possible roles in StackState:

guest users - able to see information but make no changes
administrators - able to see and change all configuration

StackState uses the file etc/application_stackstate.conf in the StackState installation directory for authentication configuration. After changing this file restart StackState for any changes to take effect.

Default username and password

StackState is configured by default with the following administrator account:

username: admin
password: topology-telemetry-time

Turning off authentication

If StackState runs without authentication, anyone who has access to the StackState URL will be able to use the product without any restrictions.

To turn off authentication completely, use the following configuration setting:

stackstate.api.authentication.enabled = false

Note that in the HOCON configuration format this has exactly the same meaning as:

stackstate { api { authentication { enabled = false } } }

Configuring file-based authentication

Here is an example of authentication that configures a user admin/password and a user guest/password. Place it within the stackstate { api { block of the etc/application_stackstate.conf. Make sure to remove the line authentication.enabled = false to authentication.enabled = false in the application_stackstate.conf file. Restart StackState to make the change take effect.

authentication {
  enabled  = true

  basicAuth = false

  # Amount of time to keep a session when a user does not log in
  sessionLifetime = 7d

  authServer {
    authServerType = "stackstateAuthServer"

    stackstateAuthServer {
      # echo -n "password" | md5sum
      # Open http://www.md5.net/md5-generator/
      # Enter your password and press submit, you will get an MD5 Hash
      # Set the MD5 Hash into `auth.password`
      logins = [
        { username = "admin", password: "5f4dcc3b5aa765d61d8327deb882cf99", roles = ["stackstate-admin"] }
        { username = "guest", password: "5f4dcc3b5aa765d61d8327deb882cf99", roles = ["stackstate-guest"] }
      ]
    }
  }
  adminGroups = ["stackstate-admin"]
  guestGroups = ["stackstate-guest"]
}

Configuration field explanation:

sessionLifeTime - when users log into StackState, they start a session with StackState during which they can access the system. This setting controls the duration of those sessions.
authServer - configures the authentication server StackState uses. It's configuration is specified below.
password - the user's password in MD5 hash format.
roles - the list of roles the user is a member of.
adminGroups - the list of groups whose members StackState grants administrative privileges.
guestGroups - the list of groups whose members have guest access privileges(read-only) in StackState.

Configuring the LDAP authentication server

Here is an example of an authentication configuration that uses a localhost LDAP server. Place it within the stackstate { api { block of the etc/application_stackstate.conf. Make sure to change the line authentication.enabled = false to authentication.enabled = true in the application_stackstate.conf file. Restart StackState to make the change take effect.

authentication {
  enabled  = true

  basicAuth = false

  # Amount of time to keep a session when a user does not log in
  sessionLifetime = 7d

  authServer {
    authServerType = "ldapAuthServer"

    ldapAuthServer {
      connection {
        host = localhost
        port = 8000
        # ssl {
        #    sslType = ssl
        #    trustCertificatesPath = "/var/lib/ssl/sts-ldap.pem"
        #    trustStorePath = "/var/lib/ssl/cacerts"
        # }
        bindCredentials {
           dn = "cn=Ldap bind user,ou=management,o=stackstate,cn=people,dc=example,dc=com"
           password = "password"
         }
      }
      userQuery {
        parameters = [
          { ou : management }
          { o : stackstate }
          { cn: people }
          { dc : example }
          { dc : com }
        ]
        usernameKey = cn
      }
      groupQuery {
        parameters = [
          { ou : groups }
          { o : stackstate }
          { cn: people }
          { dc : example }
          { dc : com }
        ]
        rolesKey = cn
        groupMemberKey = member
      }
    }
  }
  guestGroups = ["stackstate-guest"]
  adminGroups = ["stackstate-admin"]
}

Configuration field explanation:

sessionLifeTime - when users log into StackState, they start a session with StackState during which they can access the system. This setting controls the duration of those sessions.
authServer - configures the authentication server StackState uses. It's configuration is specified below.
ldapAuthServer - LDAP configuration requires information about connecting to the LDAP server and how to query the server for users.
- query, userQuery and groupQuery - The set of parameters inside correspond to the base dn of your LDAP for where users and groups can be found. The first one is used for authenticating users in StackState, while the second is used for retrieving the group of that user to determine if the user is an admin or a guest.
- sslType - the type of LDAP secure connection ssl | startTls
- trustCertificatesPath - optional, path to the trust store on the StackState server. Formats PEM, DER and PKCS7 are supported.
- trustStorePath - optional, path to the trust store on the StackState server.
- (if both trustCertificatesPath and trustStorePath are specified, trustCertificatesPath takes precedence)
- bindCredentials - optional, used to authenticate StackState to LDAP server if the LDAP server does not support anonymous LDAP searches.
- usernameKey - the name of the attribute that stores the username, value is matched against the username provided on the login screen.
- groupMemberKey - the name of the attribute that indicates whether a user is a member of a group. The constructed LDAP filter follows this pattern: ({groupMemberKey}=email=admin@sts.com,ou=management,o=stackstate,cn=people,dc=example,dc=com).
- rolesKey - the name of the attribute that stores the group name.
adminGroups - the list of roles whose members StackState grants administrative privileges.
guestGroups - the list of groups whose members have guest access privileges(read-only) in StackState.

Please note that StackState can check for user files in LDAP main directory as well as in all subdirectories. To do that StackState LDAP configuration requires bind credentials configured. Bind credentials are used to authenticate StackState to LDAP server, only after that StackState passes the top LDAP directory name for the user that wants to login to StackState.

After editing the config file with the required LDAP details, move on to the subject configuration doc. With subjects created, you can start setting up roles.

Configuring the KeyCloak OIDC Authentication Server

In order to configure StackState to authenticate to an KeyCloak OIDC authentication server, you will need to configure both of them to be able to talk to each other. The following sections describe the respective setups.

Configuring StackState to authenticate against a KeyCloak OIDC Authentication Server

Here is an example of an authentication configuration that uses a running KeyCloak server. Place it within the stackstate { api { block of the etc/application_stackstate.conf. Make sure to change the line authentication.enabled = false to authentication.enabled = true in the application_stackstate.conf file. Restart StackState to make the change take effect.

authentication {
  enabled  = true

  basicAuth = false

  authServer {
    authServerType = "keycloakAuthServer"

    keycloakAuthServer {
      clientId = stackstate
      secret = 8051a2e4-e367-4631-a0f5-98fc9cdc564d
      keycloakBaseUri = "http://keycloak.acme.com:8011/auth"
      realm = acme
      redirectUri = "http://stackstate.acme.com:7070/loginCallback"
      authenticationMethod = "client_secret_basic"
      jwsAlgorithm = "RS256"
    }
  }
  guestGroups = ["stackstate-guest"]
  adminGroups = ["stackstate-admin"]
}

Configuration field explanation:

clientId - The ID of the KeyCloak client as configured in KeyCloak
secret - The secret attached to the KeyCloak client, which is used to authenticate this client to KeyCloak
keycloakBaseUri - The base URI for the KeyCloak instance
realm - The KeyCloak realm to connect to
redirectUri - The URI where the login callback endpoint of StackState is reachable
authenticationMethod - Set this to client_secret_basic which is the only supported value for now
jwsAlgorithm - Set this to RS256, which is the only supported value for now

The KeyCloak specific values can be obtained from the client configuration in KeyCloak.

Configuring a KeyCloak client for use with StackState

In order to connect StackState to KeyCloak, you need to add a new client configuration to the KeyCloak Authentication Server. The necessary settings for the client are:

Client ID - This is the ID of the client that is connecting, we recommend naming this stackstate
Client Protocol - Set this to openid-connect
Access Type - Set this to confidential, so that a secret is used to establish the connection between KeyCloak and StackState
Standard Flow Enabled - This should be Enabled
Implicit Flow Enabled - This should be Disabled
Root URL - This should point to the root location of StackState
Valid redirect URIs - This shoud be /loginCallback/*
Base URL - This should point to the root location of StackState

REST API authentication

If you use StackState's REST API directly (as opposed to via the GUI) you can also enable authentication. The REST API supports basic authentication for authenticating users. StackState authenticates the user against either the configuration file or LDAP server as described above.

authentication {
      enabled  = true

      basicAuth = false

      ...


    }

basicAuth - turn on or off basic authentication for the StackState REST API. Turn this setting on if you use the REST API from external scripts that can not use the HTML form-based login.

PreviousStackState images NextConfiguring a reverse proxy

Last updated 3 years ago