Skip to main content

The most recent patch for this version is 2.1.1.  Learn more  

Version: 2.1

Basic configuration

This guide provides instructions for the basic configuration of the Access Decision Service (ADS).

Operating ADS requires the deployment configuration file, deployment.yaml. This file 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.

Deployment file templates​

The Deployment configuration samples psection provides two ready-to-use templates:

  • A basic configuration sample for quickly starting ADS with minimal setup.
  • An extended configuration sample that includes all supported properties, commented for clarity and customization.

You can copy and adapt these templates to create your own deployment.yaml file based on your environment and needs.

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:
  port: ${PORT:8080} 
# If  environment variable Port is not defined, then the default port value is `8080`. 
## Other names can be used, for example: ${APP_PORT}.

Environment variable PORT with a default value

note

Unlike domain configuration, deployment configuration requires that default values for environment variables specified in deployment.yaml do not have hyphens (-) appended to them. This is because deployment configuration follows the standard method for setting environment variables as defined by the Spring framework.

Override default configuration​

ADS supports overriding any property defined in the default configuration by setting a new value in your deployment.yaml file.

To safely override configuration values:

  • Use environment variables whenever possible to manage different environments (dev, test, prod).
  • Only change advanced properties if you know their impact.
  • Review comments in the full configuration template to understand the default behavior.
tip

If a property is not explicitly defined in your deployment.yaml, ADS uses a default value internally or the Spring Boot defaults.

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.

info

This is a mandatory section. ADS will not start without a valid license file.

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_ADS.license

License file reference​

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

FormatDescription
dir/axiomatics_ADS.licenserelative path on file system
/dir/axiomatics_ADS.licenseabsolute path on file system
classpath:/axiomatics_ADS.licensefile on classpath

License file reference formats

License expiration warning​

ADS will issue an expiration warning message in the log messages as the license approaches its expiration date. By default, the warning is activated 30 days prior to the expiry.

Domain​

The next important step in the deployment is setting the domain property in the deployment configuration file. This property must be set to the authorization domain configuration file that ADS will use for authorization of domains.

info

Make sure the domain configuration is valid and accessible at startup. ADS will not serve authorization decisions without it.

This domain configuration file contains a set of XACML policies and configurations, such as attribute connector(s) and/or cache configurations, to be used by the authorization service.

Authorization domain configuration​

ADS supports YAML-format authorization domain configuration files. The YAML-format domain configuration file uses the domain property.
See yaml.orgOpens in a new tab, for more information about the format.

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

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. Locate the domain property in the deployment configuration file.
  3. Edit the file and set the path sub-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.

#### Domain configuration
domain: 
    path: <path_to_file>/domain.yaml   #local or HTTP(s) path

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
classpath:/file.yamlfile on classpath

Domain configuration file reference formats

note

To have ADS send user credentials when requesting a domain configuration file from remote locations that support Basic Authentication, you need to configure an additional property. Note that this feature only supports YAML-format deployment configuration files.

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.

Authentication​

In the ADS deployment configuration, authentication settings dictate how users or systems are verified before gaining access to services. By default, authentication is enabled in ADS, and the authentication method is controlled by the security property under the spring section of the deployment.yaml.

Token-based authentication​

For a secure and flexible option, you can enable JSON Web Token (JWT) authentication. This method utilizes JSON Web Tokens and includes properties such as audiences for specifying the intended recipients of the token. The configuration is done primarily through Spring, with the key set location specified in the jwk-set-uri property.

The example below showcases a JWT authentication configuration:

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          audiences: ads                                                                              # Optional     
          jwk-set-uri: "http://localhost:1234/api/.well-known/jwks"         # Required ( Only 'file:' or 'https:' URIs are allowed)
          jws-algorithms: HS256                                                                # Optional

JWT authentication

JWT verification properties​

The JWT verification properties section outlines crucial settings for validating JSON Web Tokens (JWT) in a secure manner. These settings include:

PropertyDescriptionRequired
audiencesCorresponds to the JWT's aud claim, indicating the intended recipients of the token. This setting is used to verify that the token is intended for the specific audience.Optional
jwk-set-uriSpecifies the location of the JSON Web Key Set (JWKS) for verifying JWT signatures. Can be a local file with a file: prefix or a secure HTTP/HTTPS URL with a http or https: prefix.Required
jws-algorithmsSpecifies the JSON Web Algorithms used for verifying the digital signatures.
Default value: RS256		Optional
info

By default, ADS stores the retrieved JWKs in a cache for 5 minutes. To ensure smooth operation, especially under heavy load, ADS refreshes the JWK set 30 seconds before the cache expires. This refresh happens in the background, preventing any interruptions or delays.

For more on JWT authentication properties refer to Spring documentationOpens in a new tab.

Service ports​

ADS exposes its endpoints through a configurable service port. You can customize this port based on your deployment requirements, including enabling HTTPS for secure communication

Configure ports​

To specify a custom HTTP or HTTPS port, update the deployment.yaml configuration:

server:
  port: <custom_http_port>

By default, ADS runs on port 8080 for HTTP. To enable HTTPS, TLS must be explicitly configured.

If needed, you can also set a separate port for management endpoints, which handle system health and diagnostics:

management:
  server:
    port: <custom_management_port>
info

All ADS 2.x endpoints listen on the same configured port for both evaluation and administration functions.

For more information on exposed endpoints, see the API section.

Enable TLS​

ADS supports HTTPS through TLS/SSL configuration and you can enable it for ADS endpoints by configuring one of the following options:

In one-way SSL, only the client validates the server's certificate to ensure secure communication. To enable it, configure the following properties:

server:
  port: 8443
  ssl:
    enabled: true
    key-store: file:server_keystore.p12
    key-store-password: password
    key-store-type: PKCS12
    client-auth: none

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 root sub-property under the level property of the logging section in the deployment.yaml.

The default logging level in ADS is the WARN level.

Example of logging section in the deployment configuration file:

logging:
  level:
    root: WARN
#   "com.axiomatics.audit": INFO

ADS supports the following logging options defined with the root sub-property:

Logging LevelDescription
OFFNo logging at all. This level is used to turn off logging.
ERRORSignifies problems that might not halt ADS but are significant issues, such as exceptions that are handled but indicate faulty behavior.
INFOProvides general operational insights into the application's state, suitable for monitoring runtime behavior and progression without overwhelming detail.
WARNProvides information for situations that aren't errors but could potentially lead to errors or unexpected behavior in the future.
TRACEThe finest level of logging, showing detailed diagnostic information.
DEBUGLogs information that is useful for developers debugging issues.
FATALA severe error indicating that the system might crash or a critical operation has failed.

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.

Enable audit logging​

Open the deployment.yaml configuration file and perform the following actions:

  1. Locate the logging section and make sure that the root sub-property is set to WARN.

  2. Uncomment the "com.axiomatics.audit" line under root.

    The logging section should look like the following sample:

    logging:
      level: 
        root: WARN
        "com.axiomatics.audit": INFO
    info

    The com.axiomatics.audit sub-property specifies the Axiomatics audit logging level. In the example above, INFO sets the minimum level of messages to be logged for auditing purposes.

To disable audit logging, revert the changes by commenting out the "com.axiomatics.audit" line or set the "com.axiomatics.audit" property to OFF.

For further details regarding audit logging, read the Audit logging section.

Metrics​

ADS collects two types of metrics:

  • ADS-specific metrics: These follow the RED methodology (Rate, Errors, Duration) and provide insights into access request evaluations.
  • Spring Boot system metrics: These cover JVM, CPU, memory, HTTP requests, cache, and other system-level metrics.

For more information on metrics, see the Metrics section.

Enable metrics​

To enable metrics, set the sub-properties under management.metrics.enable to true in the deployment.yaml file.

note

Enabling metrics may require additional configuration, such as selecting a metrics backend and defining expiry/buffer-length settings. See the Metrics Configuration section for more details.

When enabled, ADS collects RED metrics for all requests to the authorize endpoint in both JSON and XML formats. Metrics data is presented as counters and timers and is accessible through the configured backend like for example, InfluxDB.

In ADS, all metrics are disabled by default to minimize performance overhead and reduce unnecessary data collection. To enable the collection of metrics, you need to explicitly configure them in the deployment.yaml file as shown in the sample below:

management:
  metrics:
    enable:
      system: true
      jvm: true
           ...
      decisions: true
      duration.info: true

When enabled, ADS collects RED metrics for all requests to the authorize endpoint in both JSON and XML formats. Metrics data is presented as counters and timers and is accessible through the configured backend like for example, InfluxDB.

For more information on metrics and how to configure them, see the Metrics section.

Test your configuration​

Once your deployment.yaml file is in place, follow these steps to validate that your configuration works:

  1. Start the ADS container or service.
  2. Check logs for startup success messages.
  3. Use the /actuator/health endpoint to confirm the service is running.
  4. If you've configured Prometheus or logging, validate those outputs as well.

If the service fails to start, review the logs for errors related to missing properties, invalid paths, or authentication issues.

Additional configurations​

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 section and its subsections.

Deprecated properties​

The following properties from ADS 1.x are no longer supported in ADS 2.x:

PropertyStatusNotes
metricsBackendsDeprecatedReplaced by management.metrics
security.enabledDeprecatedUse spring.security.* instead

Disclaimer​

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

There are many configuration options available in Springboot. 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 Springboot configuration options, please refer to the