Optional deployment configuration

There are configuration properties that are not included in the sample deployment configuration files that may be relevant for some users to add. These are described in this section.

Separating event types in the audit log output

The audit logs produced by ADS contain two types of events:

• evaluation events - data regarding access requests and their responses

• administrative events - data regarding runtime changes to the configuration of ADS

Which type of event to include in the log output is controlled by the use of different loggers, so that the output contains either evaluation events only, administrative events only, both types together, or one output item for each type (either to console or file).

Note: For convenience, the following focuses on the properties added by Axiomatics. For general information about logging properties, refer to the logging section of the Dropwizard documentation.

Both types of events in one output

In its simplest form (and the only one available prior to version 1.8) the log data is directed to a single output.

1. Open the deployment configuration file in a text editor.

2. Locate the logging section in the deployment configuration file.

3. Add the logger com.axiomatics.audit and the other properties according to the figure.

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-audit-event.log
          archivedLogFilenamePattern: ./logs/ads-audit-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB

Both types of events in one output file

This will result in an output file named ads-audit-event.log containing both evaluation events and administrative events.

Note: While the property additive: is set to true, the log stream is also output to console. Set the property to false to only create the file output.

Either evaluation events or administrative events in the output

Analysis of the audit log data may be simplified by only having one type of event in the output. This is accomplished by using one of two dedicated loggers.

• com.axiomatics.audit.ads.admin - this logger will emit only administrative events to the output (in our example a file named ads-admin-event.log)

• com.axiomatics.audit.ads.eval - this logger will emit only evaluation events to the output file (for example a file named ads-eval-event.log)

1. Open the deployment configuration file in a text editor.

2. Locate the logging section in the deployment configuration file.

3. Add either the logger com.axiomatics.audit.ads.admin or com.axiomatics.audit.ads.eval according to choice, and the other properties as appropriate for the chosen logger, see the figure. (Our example uses the evaluation event logger.)

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit.ads.eval":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-eval-event.log
          archivedLogFilenamePattern: ./logs/ads-eval-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB

Evaluation events only in the output file

This will result in an output file named ads-eval-event.log containing only evaluation events.

Note: While the property additive: is set to true, the log stream is also output to console. Set the property to false to only create the file output.

Important: If you edit the configuration to use the other logger, do not forget to also update the properties currentLogFilename and archivedLogFilenamePattern accordingly, for consistency and to minimize the risk of overwriting files with the wrong data.

Separate outputs for evaluation and administrative events

It may be convenient to have the log data separated, for example, into two output files, one for each type of event. This is configured by using both of the loggers described in the previous section at the same time.

1. Open the deployment configuration file in a text editor.

2. Locate the logging section in the deployment configuration file.

3. Add the loggers com.axiomatics.audit.ads.admin, and com.axiomatics.audit.ads.eval, and the other properties as shown in the figure.

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit.ads.admin":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-admin-event.log
          archivedLogFilenamePattern: ./logs/ads-admin-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB
 
    "com.axiomatics.audit.ads.eval":
      level: INFO
      additive: true
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-eval-event.log
          archivedLogFilenamePattern: ./logs/ads-eval-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB

Separate output files for evaluation and administrative events

This will result in one output file named ads-eval-event.log containing evaluation events and one file named ads-admin-event.log containing administrative events.

Note: While the property additive: is set to true, the log streams are also output to console. Set the property to false to only create the file output. In the example above, a simple variation could be to set the property additive: to false for the administrative events logger and to true for the evaluation events logger. This would result in the evaluation events log output both to console and as a file named ads-eval-event.log, and the administrative events log only output as a file named ads-admin-event.log.

Enabling verbose audit logging

By default, the log output for evaluation events is presented in a concise format, that is, information not essential to auditing is excluded from the evaluation events. If the full, or verbose, logging information is required, you need to provide an additional property in the deployment configuration file.

audit:
  mode: verbose
 
logging:
  level: WARN
  loggers:
    "com.axiomatics.audit": INFO
  appenders:
    - type: console
      target: stdout
      timeZone: system

Verbose logging output enabled

1. Open the deployment configuration file in a text editor.

2. Add the property audit:.

3. Add the subproperty mode: and the value verbose.

The subproperty mode: can take two values, concise and verbose, with concise being the default value.

See the section Audit log message format for output examples and more information about the logging output format.

Configuring single-line per event log output

Some of the log events in ADS may generate multi-line messages. If that is a problem, for example, if you are using a log analysis tool that requires single-line log messages, a solution is to configure the logging property to use a JSON layout. This will guarantee that every event is logged using one line.

logging:
  level: WARN
  loggers:
    "com.axiomatics.audit":
      level: INFO
      additive: false
      appenders:
        - type: file
          layout:
            type: json
          threshold: INFO
          currentLogFilename: ./logs/ads-audit-event.log
          archivedLogFilenamePattern: ./logs/ads-audit-event-%d{yyyy-MM-dd}-%i.log.gz
          archivedFileCount: 7
          timeZone: system
          maxFileSize: 10MB
  appenders:
  - type: console
    target: stdout
    timeZone: system
    # Uncomment the following lines to enable JSON layout as default layout:
    #  type: json
    #  prettyPrint: true

JSON layout enabled for audit logging

In the example, the JSON layout is enabled solely for audit logs, which are directed to a separate log file. All other log events are sent to standard output. To enable JSON layout for all logs, uncomment the section as described.

Logging enhanced with tracing information in MDC

Log entries emitted by ADS can be enhanced with trace and span identifiers as attributes in the Mapped Diagnostic Context (MDC). However, this requires that the OpenTelemetry Java agent that ADS relies on for the tracing functionality is enabled. See Tracing for more information.

When that is the case, the OpenTelemetry Java agent will inject information about the current traces and span into the MDC copy of each logging event. Refer to the OpenTelemetry MDC documentation for more on the information injected into the MDC copy.

In the JSON logging layout, the MDC value is included by default. To exclude the MDC value, the property includes: must be used.

• Add the property includes: to the JSON layout section of the deployment configuration file and exclude mdc from the list of logging event attributes.

This will prevent the MDC value from being printed in the log output.

layout:
  type: json
  timestampFormat: "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
  prettyPrint: false
  appendLineSeparator: true
  includes: [timestamp, threadName, level, loggerName, message, exception]

MDC excluded from log output (excerpt)

To include it again, add mdc back to the list of logging event attributes.

layout:
  type: json
  timestampFormat: "yyyy-MM-dd'T'HH:mm:ss.SSSZ"
  prettyPrint: false
  appendLineSeparator: true
  includes: [timestamp, threadName, level, loggerName, message, mdc, exception]

MDC included in log output (excerpt)

Refer to the Dropwizard documentation for JSON layout for more information.

License expiration warning

ADS will warn in a log message when the license is nearing its expiration date. By default, that warning is triggered 30 days before the expiration date.

You can override this by adding an optional property entry to the license property. This will control how many days before the license expires that a warning should be triggered and logged.

license: <path to valid license file>
licenseExpirationWarning: 100 days

License expiration warning

1. Locate the license: property in the deployment configuration file.

2. Add the licenseExpirationWarning: property and set a duration for the number of days before the license expires that a warning should be triggered and logged.

The log entry will look something like this:

WARN [2020-07-08 08:50:34,489] com.axiomatics.ads.license.LicenseChecker: License expires in 100 days

Runtime updating of domain configurations

Instead of reading the domain configuration only at start-up (which is the default), ADS can be configured to update the domain configuration during runtime by polling its source at regular intervals. This allows for the updating of policies or attribute connectors without having to stop and redeploy ADS each time the domain configuration is updated. This may be particularly useful during policy development and testing.

The example in the figure below uses the domain property and a YAML-format domain configuration file, but the functionality is the same for the legacyXmlConfig property and an XML-format domain configuration file.

domain: <path/to>/domain.yaml

domainRefreshInterval: 5 seconds

Runtime updating of domain configuration enabled

1. Open the deployment configuration file in a text editor.

2. Add the property domainRefreshInterval: and a time value for the polling interval.

The time value for the interval must be expressed as an integer number and a time unit.

By adding this property and a time value, the runtime updating functionality is enabled.

The updating process involves no downtime. ADS keeps accepting and processing requests while reconfiguring, and a running ADS processes any given request only once, until completion, using its most recent working configuration, that is, the processing of a request is not halted or retried when a domain configuration is updated.

The refresh feature will only reload the domain if its content has changed. When the domain is reloaded, the cache will be cleared and new instances of the attribute connectors will be created.

Conditional requests when polling a domain name using HTTP(S)

When ADS is retrieving a domain by name using an HTTP(S) endpoint, it can include an "If-None-Match" header field to indicate to the authorization domain server which authorization domain(s) it is already in possession of. However, it does that only if it has previously received an "ETag" (entity tag) header from the authorization domain server, indicating that the server is in possession of an authorization domain.

If there is no domain present (for example, at a fresh start of ADS), ADS simply performs the GET operation and looks for an "ETag" in the response. The server may or may not include the "ETag".

If an "ETag" header has been received, ADS will in the next request send a header including an "If-None-Match" header field, with the value of the entity tag for the authorization domain present in ADS.

If this matches the domain currently pointed to by the domain name, the authorization domain server can indicate this to ADS in its response (using the "304 (Not Modified)" status code) and avoid including a complete representation of the domain in the response, thus reducing network load.

This implementation is compliant with IETF RFC 7232, §3.2, which delineates the name and semantics of the header information that clients must use for an "If-None-Match" header field, and IETF RFC 7232, §4.1, which describes the definition of the "304 (Not Modified)" status code and header information the authorization domain server will use in its response if the representation has not changed since the previous request.

Note: If the deployment configuration instructs ADS to fetch its authorization domain from the file system or the classpath, the conditional request functionality does not apply. The representation will always be returned in full in the response.

Healthcheck report on failed domain updates

Add the property reportUnhealthyOnDomainRefreshError in the deployment configuration file to configure whether the healthcheck should return a response other than 200 OK for a running instance of ADS.

This setting is false by default. This means that as long as ADS is operational, the healthcheck will always report healthy (200 OK), regardless of the result of the latest domain refresh, as the previously working domain is still active and in use.

domain: <path/to>/domain.yaml

domainRefreshInterval: 5 seconds

reportUnhealthyOnDomainRefreshError: true

Healthcheck report on failed domain updates enabled

1. Open the deployment configuration file in a text editor.

2. Add the property reportUnhealthyOnDomainRefreshError: and set the value to true.

After adding this property and setting it to true, the healthcheck will not return 200 OK after a failed refresh, but instead report on the failed domain reconfiguration and alert you to the fact that the current authorization domain in use is not the latest one.

See also Administration endpoints for more information about the healthcheck endpoint.

Note: If runtime updating of domain configuration is not enabled, this property will have no effect.

Stop ADS from starting if a declared attribute is not provided

A validation of the domain configuration is performed during startup or reconfiguration that reports to the user if there is

• a mismatch between the declaration of provided attributes and the attributes actually provided by the instantiated attribute connector, or

• a mismatch between the provided attributes by the instantiated attribute connector and the declaration of provided attributes, or

• an attribute declared in the attributes section that is not provided by any attribute connector

You can configure ADS to treat such a mismatch as an error and stop the application from starting or reconfiguring using that domain by adding the property failOnDeclaredAttributeNotProvided in the deployment configuration file.

domain: <path/to>/domain.yaml

failOnDeclaredAttributeNotProvided: true

Stop ADS from starting if a declared attribute is not provided

1. Open the deployment configuration file in a text editor.

2. Add the property failOnDeclaredAttributeNotProvided: and set the value to true.

This setting is false by default. After adding this property and setting it to true, the validation will not just report the error, but instead stop ADS from starting or reconfiguring.

Authentication using an authorization server

ADS can be configured to authenticate itself against Axiomatics Services Manager (ASM), and send client credentials when requesting a domain configuration file from ASM.

To configure this, you must add the property authHttpClientConfiguration to the deployment configuration file.

Note: Axiomatics recommends using environment variables to populate sensitive information.

authHttpClientConfiguration:
  clientId: ${AUTH_SERVER_CLIENT_ID}
  clientSecret: ${AUTH_SERVER_CLIENT_SECRET}
  tokenUri: ${AUTH_SERVER_TOKEN_URI}
  timeout: 5 seconds

Authorization server configuration

1. Open the deployment configuration file in a text editor.
2. Add the property authHttpClientConfiguration:
3. Add the parameters clientId:, clientSecret:, tokenUri:, and timeout:

These are the parameter values to set:

• clientId: A valid String which should be the name of the client (configured in the authorization server), that is, the ADS instance name.
• clientSecret: A valid String which is the generated secret for the specific client (configured in the authorization server). It is automatically generated after the clientId has been configured.
• tokenUri: A valid URL which is the specific URI to the authorization server.

Note: These three parameters and their values must be configured in the authorization server in question before they are entered/copied into the deployment configuration file.

• timeout: The maximum idle time for a connection, once established. The recommended starting value is 5 seconds. The default value is 500 ms.

TLS options

TLS can be configured in different ways, to accommodate the requirements of your implementation.

TLS

authHttpClientConfiguration:
  clientId: ${AUTH_SERVER_CLIENT_ID}
  clientSecret: ${AUTH_SERVER_CLIENT_SECRET}
  tokenUri: ${AUTH_SERVER_TOKEN_URI}  
  timeout: 5 seconds
  tls:
    keyStorePath: file:<path/to/>client.keystore
    keyStorePassword: changeit
    keyStoreType: pkcs12

TLS with client certificate

authHttpClientConfiguration:
  clientId: ${AUTH_SERVER_CLIENT_ID}
  clientSecret: ${AUTH_SERVER_CLIENT_SECRET}
  tokenUri: ${AUTH_SERVER_TOKEN_URI}
  timeout: 5 seconds
  tls:
    keyStorePath: file:<path/to/>client.keystore
    keyStorePassword: changeit
    keyStoreType: pkcs12
    trustStorePath: file:<path/to/>client.truststore
    trustStorePassword: changeit
    trustStoreType: pkcs12

Authorization server configuration with TLS and TLS with client certificate

Concurrent use with httpClientConfiguration

Important: The configuration authHttpClientConfiguration can be set concurrently with the httpClientConfiguration (see below). However, some restrictions apply.

HTTP client configuration

To have ADS send user credentials when requesting a domain configuration file from remote locations that support Basic Authentication, you need to configure the httpClientConfiguration property in the deployment configuration file.

httpClientConfiguration:
  domainUser: ${HTTPCLIENT_USER}
  domainPassword: ${HTTPCLIENT_PASS}
  timeout: 5 seconds

HTTP client configuration

1. Open the deployment configuration file in a text editor.
2. Add the property httpClientConfiguration:
3. Add the parameters domainUser:, domainPassword:
4. Add the property timeout:

There are four values to set:

• domainUser: The user name.
• domainPassword: The password of the user.
• timeout: The maximum idle time for a connection, once established. The recommended starting value is 5 seconds. The default value is 500 ms.

Note: Axiomatics recommends using environment variables to populate the sensitive information when configuring the user/password required by the server where the domain is located.

If you want ADS to read the domain configuration from a file on the local file system, then the httpClientConfiguration property is not needed.

TLS options

TLS can be configured in different ways, to accommodate the requirements of your implementation.

TLS

httpClientConfiguration:
  domainUser: ${HTTPCLIENT_USER}
  domainPassword: ${HTTPCLIENT_PASS}
  timeout: 5 seconds
  tls:
    keyStorePath: file:<path/to/>client.keystore
    keyStorePassword: changeit
    keyStoreType: pkcs12

TLS with client certificate

httpClientConfiguration:
  domainUser: ${HTTPCLIENT_USER}
  domainPassword: ${HTTPCLIENT_PASS}
  timeout: 5 seconds
  tls:
    keyStorePath: file:<path/to/>client.keystore
    keyStorePassword: changeit
    keyStoreType: pkcs12
    trustStorePath: file:<path/to/>client.truststore
    trustStorePassword: changeit
    trustStoreType: pkcs12

HTTP client configuration with TLS and TLS with client certificate

Concurrent use with authHttpClientConfiguration

Important: The configuration httpClientConfiguration can be set concurrently with the authHttpClientConfiguration (see above). However, when the authHttpClientConfiguration is used, the httpClientConfiguration cannot include the domain properties.

This configuration is allowed	This configuration is NOT ALLOWED

Connection pooling

When using standard attribute connectors that rely on database access via JDBC, setting parameters for the connection pool may be considered. Suitable values for this is best determined for the execution environment in question.

Note: For both property values, Axiomatics recommends starting with low values and work upwards in small increments.

attributeConnectorContext:
    jdbc:
        connectionPool:
            maximumSize: 5
            minimumSize: 1

Connection pool configuration

1. Open the deployment configuration file in a text editor.

2. Add the property attributeConnectorContext:

3. Add the subproperty jdbc:

4. Add the subproperty connectionPool:

There are two property values to set:

• maximumSize: This property controls the maximum size that the pool is allowed to reach, including both idle and in-use connections. This value will determine the maximum number of connections to the database backend. The value must be a non-negative integer. If the value is zero, or not set, connection pooling will not be used. The recommended starting value is 5.

• minimumSize: Each instance of a Table or SQL attribute connector will create a connection pool of this size on startup. The connection pool will never be smaller than this. If the value is zero, or not set, the connections will not be created until needed. The recommended starting value is 1.

Connections above the minimum number will be closed after a 10-minute period of inactivity. (As of this release, this is not configurable.)

Number of concurrent requests

For performance reasons (to avoid long response times and maximize throughput), a parameter for the maximum number of concurrent requests may be considered.

1. Open the deployment configuration file in a text editor.

2. Locate the server: property.

There is one value to set:

• maxThreads: This property controls the maximum number of threads to use for requests. Suitable values for this is best determined by the execution environment in question. The default value is 1024. It should not be set to a value lower than 8.

Concurrent evaluation of Multiple Decision Profile requests

The presence of this configuration object enables concurrent, or multi-threaded, evaluation of Multiple Decision Profile (MDP) requests. If this object is missing, all evaluations will be sequential.

1. Open the deployment configuration file in a text editor.

2. Add the property concurrentEvaluation:

There is one property value to set:

• numberOfWorkers: This property controls the number of workers that will perform the decision request evaluations in parallel. The value must be a positive integer.

Note: Multiple Decision Profile (MDP) is a standards-based way of grouping multiple similar access requests into a single "batch" request which will reduce the performance cost incurred by over-the-network use. See the Multiple Decision Profile specification, for more information.