Migration guide

info

This guide is for users familiar with ADS who are planning a deployment or upgrade to version 26.x.

ADS 26.x introduces significant architectural changes, native Attribute Connector integration, and built-in Contextual Authorization Query (CAQ) functionality.

To support these capabilities, ADS now runs in three distinct modes:

• ads: core ADS service only.
• caq: specialized mode with only CAQ functionality enabled.
• ads_caq: combined mode running both the core ADS service and CAQ functionality.

The primary migration paths are:

• ADS 1.x or 2.x → ADS 26.x (ads mode)
• CAQ → ADS 26.x (caq mode)

Use the table below to identify the areas that apply to your upgrade:

Current deployment	Target mode	Focus areas
ADS 1.x	ads	Account for all changes listed below. They are not backward-compatible. Skip the CAQ-related information.
ADS 1.x	ads_caq	Account for all changes listed below, including all CAQ-related information.
ADS 2.x	ads	License format, Attribute connectors. Other changes listed in this guide do not affect your deployment.
ADS 2.x	ads_caq	License format, Attribute connectors, CAQ functionality.
CAQ	caq or ads_caq	License format, CAQ functionality. Deploy ADS following the instructions in this documentation set.

CAQ functionality

ADS 26.x includes CAQ functionality for executing reverse queries. A reverse query identifies the specific authorization requests that would result in a given PDP decision.

The combined ads_caq mode is recommended only for proofs of concept (POCs), pre-production, or low-performance environments. For production environments that require both ADS and CAQ, deploy them as separate services to ensure optimal performance and scalability.

note

You must acquire the appropriate license for your chosen operating mode. This applies even when migrating from standalone CAQ to ADS 26.x running exclusively in caq mode.

License format and file

ADS 26.x requires a new license file if you are upgrading from any version prior to ADS 2.x. If you are already on ADS 2.x and targeting ads mode, no action is required. The new license file is named axiomatics_ADS.license, replacing the previous axiomatics_PDP.license.

Current deployment	Target mode	License
ADS 2.x	ads	No action required
ADS 2.x	caq or ads_caq	New license needed
CAQ	Any mode	New license needed
Other	Any mode	New license needed

Spring Boot

ADS 26.x uses the Spring BootOpens in a new tab framework, replacing the previous Dropwizard framework. Key impacts of this change include:

• Configuration properties in deployment.yaml use a new structure.
• Dropwizard health checks are replaced with new Spring Boot Actuator endpoints.
• Application lifecycle events and initialization follow the Spring Boot model.

Changed functionality

Metrics and monitoring

Monitoring and observability are now handled through Spring Boot Actuator endpoints. ADS supports Prometheus (pull), InfluxDB (push), and Azure Application Insights as backends.

The metricsBackends property is deprecated. Configure metrics using management.metrics instead. See Metrics for details.

Domain configuration

All domain-related settings are now grouped under the top-level domain key in deployment.yaml.

• ADS 1.x: Domain configuration was stored in XML.
• ADS 26.x: XML domain format is no longer supported. Domains must be declared under the domain: key in YAML. All domain-related properties (path, refreshInterval, maxRetries, and others) belong under this key.

The following examples compare the most common ADS 1.x configuration patterns to their ADS 26.x equivalents.

Domain configuration

Before: ADS 1.x

domain: /path/to/domain.yaml
domainRefreshInterval: 10 seconds

After: ADS 26.1

domain:
  path: /path/to/domain.yaml
  refreshInterval: 10 seconds

Authentication

Before: ADS 1.x

authentication:
  type: Basic
  user:
    username: ads-user
    hashPassword: 2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b

After: ADS 26.1

authentication:
  enabled: true

spring:
  security:
    user:
      name: ads-user
      password: "{sha256}2bb80d537b1da3e38bd30361aa855686bde0eacd7162fef6a25fe97bf527a25b"

Logging and metrics

Before: ADS 1.x

metricsBackends:
  parameters:
    decay: 1 minute
    bufferLength: 3

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

After: ADS 26.1

management:
  metrics:
    enable:
      decisions: true

logging:
  level:
    root: INFO
    "com.axiomatics.audit": INFO
  config: /path/to/logback.xml

Service ports and endpoints

ADS 1.x used separate, customizable ports for administration and application endpoints. ADS 26.x defaults to a single port defined under server.port in deployment.yaml. Separate management port configuration is still available via management.server.port.

Authentication

Authentication configuration has been refactored. ADS 1.x supports Basic, no-auth, and token-based authentication. ADS 26.x restructures these options:

• Authentication settings move to spring.security.
• Authentication is enabled by default and is controlled through the authentication.enabled property.
• JWT token-based authentication is supported through Spring Security.
• Passwords support {bcrypt}, {sha256}, and {pbkdf2} hash formats.
• Remote domain retrieval supports Basic or OAuth2 authentication.

The authentication.type property is deprecated. Use spring.security instead. See Configure authentication for the replacement configuration.

Quick comparison:

Feature	ADS 1.x	ADS 2.x and 26.x
Basic auth	authentication.type	spring.security.user
Disable auth	authentication.type: none	authentication.enabled: false
Token support	Custom	JWT/OAuth2
Password hashing	SHA-256	Built-in hash formats supported
Remote domain auth	Supported	Basic / OAuth2

PBKDF2 password hash compatibility (ADS 26.2.0+)

In ADS 26.2.0, the default salt length for {pbkdf2} was updated from 8 bytes to 16 bytes. Because the salt length is not stored within the hash string itself, ADS 26.2.0 assumes a 16-byte salt and will fail to verify hashes generated on earlier versions, resulting in HTTP 401 Unauthorized responses.

Identifying affected hashes

Inspect the value of spring.security.user.password in deployment.yaml (or the corresponding environment variable):

• Affected (Legacy 8-byte salt): The hexadecimal string following {pbkdf2} is 80 characters long (16 hex character salt + 64 hex character hash).
• Compatible (16-byte salt): The hexadecimal string following {pbkdf2} is 96 characters long (32 hex character salt + 64 hex character hash).

Required action

1. Before switching to ADS 26.2.0, regenerate your password hash. Alternatively, transition to {bcrypt}.
2. Update the spring.security.user.password property in deployment.yaml or your deployment secret/environment variable.
3. Start ADS 26.2.0.

note

This change only affects Basic authentication using the {pbkdf2} algorithm. Passwords hashed with {bcrypt}, {sha256}, or plain-text {noop} are unaffected.

Logging

Logging configuration shifts from Dropwizard-based setup to Spring Boot YAML configuration. Log levels remain the same, but the structure changes:

• Log levels move to logging.level.root (previously a flat level property).
• The loggers property from ADS 1.x is replaced by direct keys under logging.level, such as com.axiomatics.audit.
• appenders and timeZone output settings are no longer supported in deployment.yaml. Use a Logback configuration file via the logging.config property instead.
• Audit logs are generated in JSON format by default, providing smaller log size and improved performance. CAQ logs remain in XML format only.

note

ADS can still output audit logs in XML format if required.

See Audit logging for details.

Attribute connectors

ADS 26.x bundles all standard Attribute Connectors (SQL, Table, LDAP, HTTP, and Parser) for both Kubernetes and JAR deployments by default. You no longer need to download and install Attribute Connector JARs manually.

To use custom Attribute Connectors or add external dependencies such as JDBC drivers, place the .jar files in the resources/lib/ directory before deployment. This makes them available on the classpath when ADS starts.

Deprecated features

The following features are no longer supported in ADS 26.x:

Endpoints

• POST /asm-pdp/pdp (SOAP)
• POST /asm-pdp/authorize (REST)

XML-based domain configuration

Older ASM versions used XML domain files. ADS 26.x requires domain files in YAML, referenced under the domain: block.

note

XML remains supported for ASM 6.2.x, but is a legacy format.

ASM as metrics backend

ADS 26.x does not support ASM as a metrics backend. Observability is now managed using Spring Boot with Prometheus, InfluxDB, or Azure Application Insights. If you previously relied on ASM for metrics, transition to one of the supported backends.

Deprecated properties

Property	Status	Replacement
legacyXmlConfig	Deprecated	No replacement. XML domain config is removed.
metricsBackends	Deprecated	Use management.metrics. See Metrics for details.
authentication.type	Deprecated	Use spring.security. See Authentication for details.
metricsBackends (basic-configuration)	Deprecated	Use management.metrics. See Metrics for details.
security.enabled	Deprecated	Use spring.security.*. See Authentication for details.

Migration procedure

1. Request a new license from Axiomatics Support.

   note

   Use the new axiomatics_ADS.license format.

2. Place the license file in your deployment environment and reference it in deployment.yaml.

3. Back up your current configuration and domain files.

   If you have an XML domain file, contact Axiomatics Customer SupportOpens in a new tab to convert it to YAML.

4. Remove any deprecated features from your setup.

5. ADS 1.x to 26.x only: Convert your configuration to the new deployment.yaml structure using the Deployment configuration samples as a starting point.

   danger

   If your deployment.yaml specifies default values for environment variables, remove any hyphens (-) appended to them. Hyphens in default values are incompatible with ADS 26.x.

6. Install ADS 26.x following the official installation instructions.

   Apply your YAML configuration and verify that the new license is detected at startup.

7. Start ADS 26.x and validate its behavior, including policy evaluation and the health and metrics endpoints.

If you encounter issues during migration, contact Axiomatics Customer SupportOpens in a new tab.