Controllers (Config)

Controllers: Basics | Use | Config | Service Requests | Users & Tokens

Overview

For security, all controller configuration is static (more).

Client controllers

Warning: Override configuration should only be used in development as it bypasses the normal login procedures! Care should also be taken not to introduce development users (created for override purposes) into production / staging environments.

Auht0

When a client controller is to delegate requests to a service controller (such as a workflow engine):

• An authorization code grant is needed. The parameters grantType, backendClientID and backendGrantType are used for that purpose.
• For each route/resource/URI that a service provides, an API needs to be created in Auth0 (APIs -> Create API) and a Non Interactive client for that API (if not created automatically: Clients -> Create Client -> Non Interactive Clients)

Parameter	Found In (Auth0 management)
Client Settings	Clients -> <SOME_AUTH0_CLIENT_NAME> -> Settings

| clientSecret | Client Settings -> Client Secret clientSecretAlgo | Must be AES jwtAlgo | Client Settings -> Advanced Settings -> OAuth -> JsonWebToken Signature Algorithm domain | Client Settings -> Domain callbackURI | Client Settings -> Allowed Callback URLs (should be on list; see notes) logoutReturnURI | Client Settings -> Allowed Logout URLs (should be on list; see notes) clientId | Client Settings -> Client ID grantType | Must be "authorization_code" backendClientID | Client Settings -> Advanced Settings -> OAuth -> Allowed APPs / APIs (see notes) backendGrantType | Must be "urn:ietf:params:oauth:grant-type:jwt-bearer" localTokenExpiration | Defined by app but should probably match JWT expiration (see notes) scope | Defined by app, but usually "openid mail" | override.username | The user to authenticate as (must be in the specified Auth0 connection) override.password | The password for the specified user (if needed) override.connection | The Auth0 connection to use (Connections -> <connection type> -> <connection name>)

Parameter	Notes
callbackURI	The application/developer defines what the callback route should be
grantType	Used for getting access API tokens (more)
backednClientID	This is the API's client ID (Clients -> <SOME_AUTH0_API_NAME> -> Client ID)
localTokenExpiration	This parameter is set in minutes; the Auth0 JWT Expiration option is in seconds
scope	Info

server.static {
 
  ...

  security {
    authentication {
      clients {
        SOME_AUTH0_CLIENT_NAME {
          clientSecret = "<some secret>"
          clientSecretAlgo = "AES"
          jwtAlgo = "HS256"
          domain = "<some domain>"
          callbackURI = "https://localhost:9000/some_callback"
          clientId = "<some ID>"
          grantType = "authorization_code"
          backendClientID = "<some backend client ID>"
          backendGrantType = "urn:ietf:params:oauth:grant-type:jwt-bearer"
          localTokenExpiration = 15 //in minutes
          scope = "openid email"

          //Override credentials to be used for automatic user login meant for simplifying the development process.
          //Warning: Should only be used during development!
          override {
            username = "<some user>"
            password = "<some password>"
            connection = "<some connection>"
          }
        }
      }
    }
  }
}

Local

Notes:

• The parameters instanceSalt, passwordIterations and keyLength must be consistent between all clients and services that use the same credentials store (DB).
• Updating any of the above parameters will cause the existing credentials to fail all authentication attempts until all passwords are reset or the original settings are restored.
• The override user must exist in the credentials store (DB).

server.static {
 
  ...

  security {
    authentication {
      clients {
        //Can be used for configuring client & service controllers
        SOME_LOCAL_CLIENT_NAME {
          //Warning: Updating any of the following values will invalidate all existing user credentials!
          //These parameters need to be shared between all applications accessing the same authentication database.
          instanceSalt = "<some random salt>"
          passwordIterations = 15000
          keyLength = 128

          //The following values can be updated at any time and will not affect the stored user credentials
          placeholderPasswordSize = 96
          saltSize = 96
          sessionTokenSize = 130
          localTokenExpiration = 15 //in minutes


          //Override credentials to be used for automatic user login meant for simplifying the development process.
          //Warning: Should only be used during development and is ignored by service controllers!
          override {
            userID = "<some user ID>"
            password = "<some password>"
          }
        }
      }
    }
  }
}

Service controllers

Note: Service controllers do not support override configuration.

Auht0

Service Parameter	Found In (Auth0 management)
API Settings	APIs -> <SOME_AUTH0_API_NAME> -> Settings

| id | API Settings -> Id identifier | API Settings -> Identifier secret | API Settings -> Signing Secret secretAlgo | Must be "AES" jwtAlgo | API Settings -> Signing Algorithm localUserTokenExpiration | Defined by app but should probably match Token Expiration

API Client Parameter	Found In (Auth0 management)
Client Settings	Clients -> <SOME_AUTH0_API_CLIENT_NAME> -> Settings

| clientSecret | Client Settings -> Client Secret clientSecretAlgo | Must be "AES" jwtAlgo | Client Settings -> Advanced Settings -> OAuth -> JsonWebToken Signature Algorithm domain | Client Settings -> Domain

server.static {
  
  ...

  security {
    authentication {
      services {
        SOME_AUTH0_API_NAME {
          id = "<some API ID>"
          identifier = "<some identifier>"
          secret = "<some API secret>"
          secretAlgo = "AES"
          jwtAlgo = "HS256"
          localUserTokenExpiration = 15 //in minutes
        }
      }
      clients {
        SOME_AUTH0_API_CLIENT_NAME {
          clientSecret = "<some secret>"
          clientSecretAlgo = "AES"
          jwtAlgo = "HS256"
          domain = "<some domain>"
        }
      }
    }
  }

  ...

}

Local

Configuration for a local auth service controller is the same as the configuration for a client controller, without the override support.