Deployment configuration

The deployment configuration file used by Authorization Domain Manager is written in YAML. (See yaml.orgOpens in a new tab, for more information about the format.)

Running ADM in a Docker container

A deployment configuration file is included in the distribution and it is used when ADM is started for the first time (see docker/resources/deployment.yaml). This file contains a configuration that allows you to get ADM up and running and ready for use.

However, the deployment file can be further edited to adapt to your configuration requirements. The deployment.yaml file can be opened in any text editor.

See also the additional resources section Configuration sample files for an example of a deployment configuration file.

Running ADM on the command line

When ADM is run from the command line you need to set up your own deployment configuration file.

See the descriptions for the different properties below. The additional resources section Configuration sample files contains sample configurations that you can copy and use as templates for your configuration.

Updating the deployment configuration

The deployment configuration file contains property settings for which you have to stop the application to update, as ADM reads the deployment file only at start-up.

• To update any part of the configuration, simply stop ADM (that is, kill the process), update the configuration file, and then restart ADM. (See Installation, for information about stopping and starting ADM.)

note

Some properties use file references, like <path_to_file>. These should always be seen as relative to the environment in which ADM is running.

Configuration using environment variables

Properties in the deployment file can be configured using environment variables. The example shows a deployment configuration file that uses the environment variable PORT to set the application port.

The syntax is: ${<environment variable name>:-<default value>}.

server:
  applicationConnectors:
    - type: http 
      port: ${PORT:-8888} 
  adminConnectors:
    - type: http 
      port: 8081

Environment variable PORT with a default value

If the environment variable is not defined, then a default value of 8888 is used.

note

Axiomatics recommends using environment variables to substitute any sensitive information, such as passwords, so that sensitive information can be managed and protected using generic mechanisms, external to the deployment file.

Database

ADM needs access to a database for storage, and configuration information for the database in question must be present in the deployment configuration file.

Running ADM in a Docker container

This is handled automatically during the installation, during which a PostgreSQL database is provided and configured for the purpose. No further configuration is necessary.

note

ADM only supports PostgreSQL and Axiomatics recommends that the provided PostgreSQL database is used. ::::

Running ADM from the command line

When ADM is run from the command line you need to set up the PostgreSQL instance and its configuration.

ADM only supports PostgreSQL. :::

• Locate the Database property in the deployment configuration file.

Edit the configuration as needed.

database:
  driverClass: org.postgresql.Driver
  user: ${DB_USER}
  password: ${DB_PASSWORD}
  url: jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_SCHEMA}
  properties:
    charSet: UTF-8
  maxWaitForConnection: 1s
  validationQuery: "/* Health Check */ SELECT 1"
  validationQueryTimeout: 3s
  minSize: 8
  maxSize: 32
  checkConnectionWhileIdle: false
  checkConnectionOnBorrow: true
  evictionInterval: 10s
  minIdleTime: 1 minute

Sample database configuration

This example is also included in the sample deployment configuration file in the additional resources section Configuration sample files.

For more information about configuration options for the database property, please refer to the Dropwizard documentationOpens in a new tab. 

Authentication

The authentication of users for ADM requires a separate file containing the user credentials and a reference to that file in the deployment configuration file.

Running ADM in a Docker container

The user credentials file is included in the distribution and it is used when ADM is started for the first time (see docker/resources/users.yaml). Edit that file to manage users

Running ADM from the command line

When ADM is run from the command line you need to create your own user credentials file.

Add the names and passwords of the users that should have access to ADM, using the following structure. Generate the password hash using the SHA-256 algorithm.

---
- name: <user>
  password: <SHA256 password hash>
- name: <user>
  password: <SHA256 password hash>
...

User credentials list

Save it as a YAML-format file and set a file reference to it in the userRegistry parameter of the auth property (see below).

Generating a password hash

Linux

Linux

In Linux there is a built-in command for this.

• Enter the following on the command line:

echo -n <password> | sha256sum

This will return a password hash of <password>.

Windows

Windows

There is no equivalent built-in command for Windows. However, third-party solutions are available online.

Edit the deployment configuration

• Locate the auth property in the deployment configuration file.

Set a file reference to a YAML-format users configuration file. See the table below for supported formats for file references.

auth:
  type: basic
  userRegistry: <path_to_file>/users.yaml 

Authentication property

User registry file reference

The property must point to the user registry file to be used, using one of the supported formats listed in the table:

Format	Description
dir/file.yaml	relative path on file system
/dir/file.yaml	absolute path on file system
http://<host:port>/<path_to_file>	URL to the file
https://<host:port>/<path_to_file>	URL to the file NOTE: There must be a valid certificate present that the JVM trusts. If not, a valid certificate has to be added to the truststore, and the JVM instructed to use it.
classpath:/file.yaml	file on classpath

User registry file reference formats

note

In the deployment configuration file included in the Docker distribution (see docker/resources/deployment.yaml), the userRegistry property points to a configuration file provided in the same subfolder, docker/resources/users.yaml.

Service connectors

Locate the server property in the deployment configuration file.

In this section, service connectors to the server can be configured to use specific ports and/or encryption to secure communication. Both TLS and TLS with client certificate can be used.

Application and administration endpoints

By default, the application endpoint will use port 8080 and the administration endpoint will use port 8081. The properties for applicationConnectors and adminConnectors can be configured to use specific ports in the deployment configuration YAML file.

Recommended configuration

A recommended configuration would have separate ports for the application and administration endpoints. For example:

server:
  applicationConnectors:
    - type: http
      port: 8080
  adminConnectors:
    - type: http
      port: 8081

Recommended port configuration

note

Axiomatics strongly recommends configuring the ports explicitly. This will simplify troubleshooting, should that be necessary.

Single port configuration

If limitations of your environment prevents you from using a dual-port configuration, it is possible to configure a single port for all the endpoints, either as HTTP or HTTPS (in this case, application endpoints and administration endpoints will be prepended with the path /application and /admin, respectively), using type: simple. For example:

server:
  type: simple 
  connector:
    type: http
    port: 8081

Single port configuration

TLS and TLS with client certificate

In the sample deployment configuration file, the applicationConnectors and adminConnectors properties are configured for HTTP. (See the sample configuration above.)

If HTTPS is used, the property can be configured for TLS or TLS with client certificate.

TLS

TLS

server:
  applicationConnectors:
    ## Requirements to enable TLS
    - type: https
      port: 8443
      keyStorePath: file:<path_to_file>/server.keystore
      keyStorePassword: changeit
      keyStoreType: pkcs12

TLS with client certificate

TLS with client certificate

server:
  applicationConnectors:
    ## Requirements to enable TLS with client certificate
    - type: https
      port: 8443
      keyStorePath: file:<path_to_file>/server.keystore
      keyStorePassword: changeit
      keyStoreType: pkcs12
      trustStorePath: file:<path_to_file>/server.truststore
      trustStorePassword: changeit
      trustStoreType: pkcs12
      wantClientAuth: true

TLS configurations

Logging

There are many possible uses for logging data, such as performance diagnostics and error correction, verification of access control measures, proof of compliance with legal requirements, or forensic evaluation of past events. Two examples follow below, logging of audit events and authorization decisions, respectively.

Audit event logging

Audit event logging in ADM registers events that relate to the access and management of authorization domains. The audit event log holds a chronological record of who did what to an authorization domain, when it happened, and how the system responded.

The audit event log record is made up of a series of distinct fields, to facilitate parsing, reading, searching, and analysis. The records are written as JSON-format strings.

Example:

INFO [2020-05-08 06:06:02,919] AUDIT: {"user":"dora","namespace":"myNamespace","domainId":"5e2cffaf-f14b-4451-a50f-a90376a6ad80”,”sourceDomainName”:”myDomain”,”destinationDomainName”:”null”,”timestamp”:”2020-05-08T08:06:02.908”,”operation”:”STORE”,”result”:”SUCCESSFUL”}

Item/Field	Example	Description
Log level and time	INFO [2020-05-08 06:06:02,919] AUDIT:	The log level and a time stamp.
user	dora	The user executing the operation. If the information is available it is recorded, otherwise it is written as "null".
namespace	myNamespace	The namespace of the domain. If the information is available it is recorded, otherwise it is written as "null".
domainId	5e2cffaf-f14b-4451-a50f-a90376a6ad80	The domain identifier. If the information is available it is recorded, otherwise it is written as "null".
sourceDomainName	myDomain	The name of the domain. If the operation is copy, it is the name of the source domain. If the information is available it is recorded, otherwise it is written as "null".
destinationDomainName	null	If the operation is copy, it is the name of the destination domain. Otherwise, it is written as "null".
timestamp	2020-05-08T08:06:02.908	The server time.
operation	STORE	The operation executed by the user. Takes one of the values: COPY, DELETE_NAME, DELETE_NAMESPACE, RETRIEVE_BY_ID, RETRIEVE_BY_NAME, RETRIEVE_HISTORY, RETRIEVE_DOMAIN_NAMES, ROLLBACK, and STORE
result	SUCCESSFUL	The result of the operation. Takes one of the values: DOMAIN_NOT_FOUND, INVALID_DOMAIN_ID, INVALID_DOMAIN_NAME, INVALID_NAMESPACE, NAMESPACE_NOT_FOUND, STORAGE_FAILURE, SUCCESSFUL, ROLLBACK_FAILURE, and UNAUTHORIZED_OPERATION

The anatomy of an audit event record

Enabling audit event logging

Locate the logging section in the sample deployment configuration file.

A configuration for audit event logging is provided in the deployment configuration file. By default, audit event logging is disabled.

Audit logging disabled

logging:
  level: INFO
  loggers:
    # Set value to INFO to enable.
    AUDIT: OFF
    com.axiomatics.domainmanager.authorizer.PdpAuthorizer: OFF
  appenders:
    - type: console
      target: stdout
      timeZone: system

Audit logging disabled

Audit logging enabled

To enable audit logging, change the value for the AUDIT logger to INFO.

logging:
  level: INFO
  loggers:
    # Set value to INFO to enable.
    AUDIT: INFO
    com.axiomatics.domainmanager.authorizer.PdpAuthorizer: OFF
  appenders:
    - type: console
      target: stdout
      timeZone: system

Audit logging enabled

In the basic configuration, the appender type is set to console and the target to stdout.

Disabling audit event logging

To disable audit event logging, change the value for the AUDIT logger to OFF in the deployment configuration file.

Authorization decision logging

Authorization decision logging, or evaluation logging, logs the authorization decisions made by the internal Policy Decision Point (PDP) of ADM. A basic configuration for authorization decision logging is provided in the sample deployment configuration file.

Authorization decision logging is disabled by default but when enabled it will record every authorization request serviced, including which attributes, with sources and values, the internal PDP used when servicing the request.

Authorization decision logging is enabled or disabled in the same manner as audit logging.

logging:
  level: INFO
  loggers:
    # Set value to INFO to enable.
    AUDIT: OFF
    com.axiomatics.domainmanager.authorizer.PdpAuthorizer: INFO
  appenders:
    - type: console
      target: stdout
      timeZone: system

Authorization decision logging enabled

Refer to the chapter "Logging" in the Access Decision Service Documentation for a description of the log output format.

Configuring other logging options

If there is a need to change the logging configuration, for example, to add other appenders, or accommodate requirements for a different output type or log format, several options are available:

• For more information about DropWizard logging configuration options, please refer to the logging sectionOpens in a new tab of the DropWizard documentation.
• Furthermore, Dropwizard implements the Logback logging system. Refer to Logback documentationOpens in a new tab, for more information.

Additional deployment configuration

There are configuration properties that are not included in the sample deployment configuration that may be relevant for some users. See Optional deployment configuration for more information.

Disclaimer

Authorization Domain Manager makes use of the DropWizard framework for its implementation.

There are many configuration options available in DropWizard. However, only properties explicitly mentioned in the Authorization Domain Manager documentation are supported. Axiomatics assumes no responsibility or liability for the use of other configuration options.

For more information about DropWizard configuration options, please refer to the DropWizard documentationOpens in a new tab.