Configure authorization domains

For background on what an authorization domain is, see Authorization domains.

ADS requires a valid authorization domain to evaluate access requests. Configure the domain in the domain section of your deployment.yaml file.

info

This section is mandatory. ADS will not serve authorization decisions without a valid, accessible domain configuration.

Point ADS at your domain file

Set domain.path to the location of your authorization domain configuration file. ADS supports local file paths and HTTP/HTTPS URLs.

domain:
  path: <path_to_file>/domain.yaml

Supported path formats

Format	Description
dir/file.yaml	Relative path on the file system
/dir/file.yaml	Absolute path on the file system
classpath:/file.yaml	File on the classpath
http://host/path/file.yaml	Remote HTTP URL
https://host/path/file.yaml	Remote HTTPS URL

A sample domain file is available in Authorization decisions domain file.

Domain configuration properties

Property	Description
domain.path	Location of the authorization domain configuration file (local path or HTTP/HTTPS URL). Required.
domain.refreshInterval	Interval at which ADS polls the domain source and reloads when content has changed. Format: integer + time unit (e.g. 10 seconds, 5 minutes).
domain.reportNotReadyOnDomainRefreshError	When true, ADS reports 503 Service Unavailable if a domain refresh fails. Default: false.
domain.startup.maxRetries	Number of retry attempts when loading the domain at startup.
domain.startup.retryInterval	Wait time between startup retry attempts. Format: integer + time unit. Minimum: 1 second.

Full domain configuration example

domain:
  path: <path_to_file>/domain.yaml
  refreshInterval: 5 seconds
  reportNotReadyOnDomainRefreshError: true
  startup:
    maxRetries: 5
    retryInterval: 5 seconds

Startup behavior

By default, ADS loads the domain once during startup. If loading fails, the service does not start.

Startup retry mechanism

Configure startup retries to handle temporary connection issues or delayed availability of domain sources. ADS retries up to maxRetries times, waiting retryInterval between each attempt.

The total timeout is maxRetries × retryInterval. Set retryInterval higher than your network's typical connection timeout to avoid premature failure.

Example: With maxRetries: 5 and retryInterval: 5 seconds, ADS retries for up to 25 seconds before failing.

Runtime domain updates

When refreshInterval is set, ADS polls the domain source at that interval and reloads only when the content has changed. This allows you to update policies without restarting ADS.

Runtime update behavior:

• Zero downtime during updates: in-progress requests continue with the previous configuration.
• Each new request uses the most recent successfully loaded configuration.
• The attribute cache is cleared only when the domain content changes.

note

Runtime domain updates are enabled only after the domain is successfully initialized at startup.

Healthcheck reporting on failed domain updates

Set reportNotReadyOnDomainRefreshError: true to make ADS return 503 Service Unavailable when a runtime domain refresh fails. This integrates with Kubernetes readiness probes or load balancer health checks to remove the instance from rotation until the domain is healthy again.

caution

• The readiness probe returns 503 during initial domain loading until initialization completes.
• This property has no effect if refreshInterval is not configured.

Authenticate when retrieving a remote domain

If your domain is served from a remote HTTP/HTTPS endpoint that requires authentication, configure credentials under domain.authentication.

note

Only one of username/password or oauth2ClientId should be set in the authentication section at a time.

Property	Description
domain.authentication.username	Username for Basic authentication when retrieving the domain. Use only when not using OAuth2.
domain.authentication.password	Password for Basic authentication. Use only when not using OAuth2.
domain.authentication.oauth2ClientId	OAuth2 client ID for token-based domain retrieval. Use only when not using Basic authentication.
domain.authentication.tlsConfigurationId	(Optional) Name of the Spring SSL bundle used to secure the domain retrieval connection.
domain.authentication.oauth2TlsConfigurationId	(Optional) Name of the Spring SSL bundle used to secure the OAuth2 token retrieval connection.

• Basic authentication
• OAuth2 client credentials

Set username and password under domain.authentication:

domain:
  path: https://remote-endpoint.com/domain
  refreshInterval: 10 seconds
  reportNotReadyOnDomainRefreshError: true
  authentication:
    username: ${DOMAIN_USER}
    password: ${DOMAIN_PASSWORD}

Set oauth2ClientId under domain.authentication, then add the OAuth2 client registration under spring.security.oauth2.client:

domain:
  path: https://remote-endpoint.com/domain
  refreshInterval: 10 seconds
  authentication:
    oauth2ClientId: hub-adm-client

spring:
  security:
    oauth2:
      client:
        registration:
          hub-adm-client:
            client-id: ads
            client-secret: ${SECRET}
            scope: openid
            authorization-grant-type: client_credentials
            provider: hub-adm-client
        provider:
          hub-adm-client:
            token-uri: https://<hostname>/auth/realms/asm/protocol/openid-connect/token

caution

Use environment variables for sensitive values such as client-secret. Never write secrets as plain text in deployment.yaml.

For TLS configuration when retrieving a remote domain, see Configure TLS: TLS options.