Additional domain properties
The Access Decision Service (ADS) requires a valid authorization domain to evaluate an access request and produce an authorization decision. The retrieval of the authorization domain can be made at startup or during runtime. Additionally, ADS can retrieve the authorization domain from external sources such as the Axiomatics Services Manager (ASM), Authorization Domain Manager (ADM), or any other remote endpoint.
By default, ADS attempts to retrieve a valid authorization domain only once during startup. You can change this default behavior using the properties listed below:
| Properties | Description |
|---|---|
domain | The path to the directory containing the domain.yaml configuration file. Optionally, this property can point to ASM/ADM domain, a standalone ADM or a remote endpoint to retrieve the authorization domain. |
domainStartup | Used to configure manually the number of retries and time interval that ADS attempts to read a valid authorization domain at startup and has the following nested properties: - maxRetries- retryInterval |
├─ maxRetries | The number of retries that ADS will attempt to read a valid authorization domain at startup, until it succeeds. |
└─ retryInterval | The time interval duration between each retry attempt at startup. Info: The value must be expressed as an integer number and a time unit. Its minimum value is 1 second. |
domainRefreshInterval | The time interval duration between each refresh of the domain configuration during runtime. Read more in the Runtime updating of domain configurations section. Info: The value must be expressed as an integer number and a time unit. |
reportNotReadyOnDomainRefreshError | When set to false, disables the healthcheck report on failed domain updates. For details, read the Healthcheck report on failed domain updates section. |
failOnDeclaredAttributeNotProvided | If set to true, a validation of the domain configuration is performed during startup or reconfiguration that reports the issues described in the Validation of the domain configuration section.The default is false. |
domain: <path_to_file>/domain.yaml
domainStartup:
maxRetries: 3
retryInterval: 5 seconds
domainRefreshInterval: 5 seconds
reportNotReadyOnDomainRefreshError: false
failOnDeclaredAttributeNotProvided: true
Domain retrieval from ASM
ADS provides the option to retrieve its authorization domain from ASM/ADM or a standalone ADM as described in the ASM and ADS integration section.
Domain name polling with HTTP(S) using conditional requests
When the Authorization Domain Server (ADS) retrieves a domain by name using an HTTP(S) endpoint, it may use the If-None-Match header to inform the server about the authorization domains it already holds. This occurs only if ADS has previously received an ETag (entity tag) header from the server, signifying the server's possession of an authorization domain.
Upon starting or lacking domain information, ADS executes a GET operation to fetch the domain, during which it looks for an ETag in the server's response. Depending on the server's configuration, the ETag may or may not be provided.
Upon receiving an ETag, ADS includes an If-None-Match header in its subsequent request, containing the entity tag of the authorization domain it holds. If this entity tag matches the domain associated with the domain name, the server can signal this match to ADS using the 304 (Not Modified) status code. This response allows ADS to recognize that the domain has not changed, avoiding the transfer of the complete domain representation again and thus reducing network load.
This interaction is in compliance with IETF RFC 7232, §3.2 regarding the If-None-Match header and IETF RFC 7232, §4.1 concerning the 304 (Not Modified) status code. These standards ensure efficient communication between ADS and the server, particularly when integrated within the context of ASM and ADS integration, enhancing the synchronization and data exchange processes without redundant data transfer.
The conditional request feature is irrelevant if ADS is configured to retrieve its authorization domain from the file system or classpath. In such cases, the server always returns the full domain representation.
Runtime updating of domain configurations
In addition to the default behavior of reading the domain configuration only at start-up, 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.
Domain refresh is a separate process that occurs only after the domain has been initialized successfully.
Runtime domain updates functionality is enabled after a successful domain is fetched at startup.
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.
Healthcheck report on failed domain updates
By default, the healthcheck report (readiness probe) for ADS returns a 503 - Service Unavailable error when the service fails to refresh the domain. The readiness probe is dependent on the successful initialization of the domain and will continue to return a 503 error until the domain is initialized successfully.
If you want to disable the healthcheck report on failed domain updates, set the reportNotReadyOnDomainRefreshError property to false.
If runtime updating of domain configuration is not enabled, this property will have no effect.
The reportNotReadyOnDomainRefreshError property has replaced the deprecated reportUnhealthyOnDomainRefreshError.
Validation of the domain configuration
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
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.