Skip to main content
Version: 1.17

Basic configuration

This section guides you through creating the basic configuration Access Decision Service (ADS) requires before deployment.

Operating ADS requires a deployment configuration file called deployment.yaml that defines essential parameters for ADS to function correctly. See yaml.orgOpens in a new tab for more information about the format.

There are two ways to create the deployment configuration file. You can either write it yourself or utilize the sample configuration files included in the Axiomatics installation package under /docker/resources. Whichever method you choose, the file must reference a valid domain and a valid license.

The Additional Resources section Deployment configuration samples provides some samples that you can use as a starting point. These samples serve as a customizable template, facilitating your configuration process.

note

By default, ADS reads the deployment.yaml file at startup. To update your deployment, you'll need to stop the service, edit the deployment file, and then restart the service.

General guidelines​

The following guidelines are some recommendations to ensure the optimal operation of ADS.

File paths​

The samples in this section sometimes use file references, such as <path_to_file>. These should always be interpreted as relative to the environment in which ADS is running.

Environment variables​

The samples in this section contain custom values. However, Axiomatics strongly suggests configuring properties in the deployment file using environment variables, particularly for sensitive information such as passwords. Using environment variables ensures that sensitive data is managed and protected through generic mechanisms external to the deployment file.

The following example showcases the syntax used for environment variables:

property: ${<environment variable name\>:-<default value\>}

The deployment configuration sample below, uses the environment variable PORT for setting the application port:

server:
  applicationConnectors:
    - type: http
      port: ${PORT:-8888} 
# If  environment variable Port is not defined, then the default port value is `8888`. 
## Other names can be used, for example: ${APP_PORT}.

Environment variable PORT with a default value

License​

ADS requires a valid license file provided separately by Axiomatics. This license file contains the license key and needs to be in place before ADS starts.

To configure the license section of the deployment configuration file (deployment.yaml file):

  1. Obtain the license file from Axiomatics as it's provided separately.
  2. Open the deployment configuration file and locate the license property.
  3. Set the value of the license property to the path or URL where the license file is stored.
    tip

    Use one of the formats listed in the License file reference section below.

#### Path to license file
license: file:<path_to_file>/axiomatics_PDP.license

License file reference​

You can set a file reference using one of the following formats:

FormatDescription
dir/axiomatics_PDP.licenseRelative path on file system
/dir/axiomatics_PDP.licenseAbsolute 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:/axiomatics_PDP.licenseFile on classpath

License file reference formats

Compatibility for SLF4J API versions​

Starting from ADS version 1.14.0, Dropwizard 3.0.x was introduced, which has a dependency on the slf4j-api version 2.x. This version is not backward compatible with version 1.7.x, commonly used by various attribute connectors such as Table, LDAP, and SQL, as well as other custom connectors.

To prevent dependency conflicts, it is recommended to place the slf4j-api 2.x jar file or the ADS jar file at the start of your classpath. This should be done before including any other SLF4J-related jars.

Domain​

ADS uses a domain file to evaluate service requests. This domain file contains a set of XACML policies and configurations, along attribute connectors and/or cache settings, essential for the authorization process.

The domain file is deployed by setting a file reference to it in the deployment.yaml configuration file.

ADS supports authorization domain configuration files expressed in two different formats, YAML and XML. Each format requires its own property for configuration:

  • For a domain configuration file in YAML format, use the domain property.

    More details about the YAML format can be found at yaml.orgOpens in a new tab.

  • For a domain configuration file in XML format produced by the Axiomatics Services Manager (ASM) (up to and including version 6.2.12), use the legacyXmlConfig property.

note

The properties are mutually exclusive and only one of them can be enabled at any given time. The sample deployment configuration file, provided in the distribution package, uses the domain property configuration (YAML).

Configure the authorization domain​

The instructions below explain how to configure the authorization domain that ADS will use to evaluate requests, based on the format of your domain file.

To configure the domain section of the deployment configuration file using a YAML authorization file:

  1. Download or acquire from Axiomatics the domain file containing the authorization domain.
  2. Add the domain property in the deployment.yaml configuration file.
  3. Set the domain property to the domain path or URL where the domain file is stored, using one of the supported formats listed in the next table.

A sample YAML-format domain file is available in the Additional Resources section Authorization decisions domain file. This domain configuration also contains a policy that you can use to run the four example requests against, as described in the section Authorization decisions. It does not contain any attribute connector configurations.

#### Path to domain file
domain: domain.yaml

See Authorization Domains for more information about domains and how to create authorization domain configuration files.

Domain configuration file reference​

For the domain property pointing to the authorization domain configuration file to be used, use one of the supported formats listed in the table:

FormatDescription
dir/file.yamlrelative path on file system
/dir/file.yamlabsolute 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.yamlfile on classpath

Domain configuration file reference formats

The same retrieval options apply for both YAML- and XML-format files.

Domain management API​

You can manage authorization domains from the Axiomatics Services Manager using the domain management API provided with the service. See Domain management APIOpens in a new tab in the ASM documentation for more information.

Retrieve authorization domain from ASM​

ADS can be configured to retrieve its authorization domain from ASM.

For more details on how to setup this configuration refer to Configure ADS to retrieve authorization domain from ASM.

Update the domain configuration during runtime​

By default, ADS is configured to read the domain configuration only once, when loading the deployment configuration file at start-up.

However, there is an optional property that will make ADS poll the domain configuration source at regular intervals during runtime. See Runtime updating of domain configurations for more information.

Service connectors​

In this section, you can configure service connectors for the server to use specific ports and/or encryption to secure communication. You have the option to use either TLS or TLS with client certificates for enhanced security.

In the ADS deployment configuration, the server: property is key for setting these service connectors, which are crucial for secure and efficient server communication.

The two main types of endpoints used as service connectors are:

Type of endpointPropertyDefault port
ApplicationapplicationConnectors8080
AdministrationadminConnectors8081
tip

For configuring the application and administration service connector endpoints, choose custom ports that best suit the requirements of your specific environment. Axiomatics strongly advises explicitly setting the ports, as this practice significantly facilitates troubleshooting if needed.

The example below showcases a sample service connector configuration with the recommended endpoints:

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

Sample service connector configuration with default ports

Single port configuration​

If your environment restricts the use of dual ports, you can alternatively configure a unified single port for all endpoints, utilizing either HTTP or HTTPS. In this setup, differentiate the endpoints by appending /application for application services and /admin for administrative services to the base URL. You can do this simplified setup by specifying the connector type as simple.

To configure the single port setup:

  1. Locate the server property in the deployment configuration file.
  2. Add the type and connector properties and set type to simple.
  3. Configure the type and port properties under connector.

The following example showcases the single port configuration:

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

Single port configuration

TLS configuration​

You can configure HTTPS connections (type: https) with TLS encryption for increased security.

The following options are available:

  • Basic TLS encryption without client certificate authentication
  • TLS encryption with client certificate authentication

Below are two sample configurations, in the deployment file, for each scenario:

Basic TLS example:

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

For more detailed information on the TLS options and their respective Keystore and Trustore properties, refer to Additional authentication properties section.

Authentication​

In ADS deployment configuration, authentication settings dictate how users or systems are verified before gaining access to services. You can configure authentication using the type property under the authentication section of the deployment.yaml.

ADS supports three authentication methods:

  • None
  • Basic
  • Token

To ensure secure and controlled access within the ADS environment, it is crucial to carefully select and configure the most appropriate authentication method based on your specific security requirements.

When type is set to None (no user name or password needed for access), then any additional entries (user or jwt) in the authentication section, will be ignored.

The example below showcases authentication set to none:

authentication:
  type: None

None authentication

Authentication and endpoint configuration​

ADS handles authentication of the application and administration endpoints differently:

  • Application Endpoints:

    These endpoints require authentication configuration because they handle authorization queries where security is crucial. Ensure that these endpoints are configured to use authentication protocols suitable for your security requirements.

  • Administration Endpoints:

    These endpoints do not require authentication, as they are primarily used for retrieving information for service maintenance, including Kubernetes probes.

    note

    In a single port setup, administration endpoints continue to not require authentication, just as in the dual port configuration.

Logging​

In ADS deployment configuration, logging settings dictate how ADS displays logs in the console as well as the types of events that are logged.

You can configure log settings using the level property under the logging section of the deployment.yaml.

ADS supports the following logging level options:

  • OFF: No logging at all. This level is used to turn off logging.
  • ERROR: Signifies problems that might not halt ADS but are significant issues, such as exceptions that are handled but indicate faulty behavior
  • INFO: Provides general operational insights into the application's state, suitable for monitoring runtime behavior and progression without overwhelming detail.
  • WARN: Provided information for situations that aren't errors but could potentially lead to errors or unexpected behavior in the future.
  • TRACE: The finest level of logging, showing detailed diagnostic information.
  • DEBUG: Logs information that is useful for developers debugging issues.
  • FATAL: A severe error indicating that the system might crash or a critical operation has failed.

In the following sections the WARN level is used.

Example of logging section in the deployment configuration file:

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

Default logging​

The default logging setting consists of the following properties:

PropertiesDescription
appendersSpecifies how and where log data is recorded, such as to a console, file, or other logging systems.
├─typeDefines the type of appender (e.g., console, file).
├─targetDetermines the output destination (e.g., standard output, a file path).
└─timeZoneDefines the time zone used for logging timestamps. For example system uses the system default time zone.

Enable audit logging​

Audit logging in ADS tracks detailed records of policy evaluations and system changes for security, compliance, and troubleshooting purposes. This feature is disabled by default.

The following instructions describe how to enable it:

  1. Locate the logging property in the deployment configuration file and make sure that level is set to WARN.
  2. Uncomment both loggers and com.axiomatics.audit lines under level.

The logging section should look like the following sample:

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

Audit logging enabled

You can find a more detailed explanation of the audit logging properties in the table below:

PropertiesDescription
loggersA collection of logger configurations, each specifying logging levels for different components or packages within the application.
└─com.axiomatics.auditUnder loggers, specifies the logging level for Axiomatics audit logging. In the example above, INFO sets the minimum level of messages to be logged for auditing purposes.

Disable audit logging​

To disable audit logging, comment out again the loggers and com.axiomatics.audit lines in the deployment configuration file.

Enhanced logging options​

There are additional logging settings supported by ADS that may be useful in certain environments. These advanced logging configurations are described in more detail in the Additional configuration chapter in section Additional logging properties.

Dropwizard​

ADS leverages Dropwizard to facilitate the capturing, formatting, and outputting of log messages.

  • 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 configuration​

This section described the basic configuration options for ADS as well as some main settings.

You can further customize your ADS environment with additional configuration properties and settings in the deployment.yaml file.

For these custom and more advanced options see the Additional configuration chapter.

info

ADS reads the deployment.yaml file by default only once during startup. Therefore, to apply any changes, you must first stop the service, update your deployment file, and then restart the service.

Disclaimer​

Access Decision Service makes use of the Dropwizard framework for its implementation.

There are many configuration options available in Dropwizard. However, only properties explicitly mentioned in the Access Decision Service 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.

Next steps​

  • Consider using the ADS caching features to further improve the system's performance. See the Attribute caching section for more information.
  • Explore additional configuration options to optimize your ADS implementation. See the section Additional configurations for more information.