Domain

Configure ADS to retry reading its authorization domain at startup

During startup, Access Decision Service (ADS), by default, attempts to retrieve a valid authorization domain only once.

However, you can change this default behavior and configure manually the number of retries and time interval that ADS attempts to read a valid authorization domain at startup.

You can do this by adding the domainStartup: configuration section in the deployment configuration file and setting values for the maxRetries and retryInterval properties, as described below:

1. Open the deployment configuration file in a text editor.

2. Add the domainStartup: configuration section and set the values for the maxRetries and retryInterval properties for the polling interval.

domain: <path_to_file>/domain.yaml

domainStartup:
  maxRetries: 3
  retryInterval: 5 seconds

Updating the maximum number of retries and their time duration for successfully retrieving a valid authorization domain at startup

The maxRetries property represents the number of retries that ADS will attempt to read a valid authorization domain at startup, until it succeeds. The retryInterval property represents the time value for the intervals that each authorization attempt will last during startup.

info

The retryInterval value must be expressed as an integer number and a time unit. Its minimum value is 1 second.

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.

info

Domain refresh is a separate process that occurs only after the domain has been initialized successfully.

note

Runtime domain updates functionality is enabled after a successful domain is fetched at startup.

To configure the runtime updating of the domain configuration, follow the steps below:

1. Open the deployment configuration file in a text editor.

2. Add the property domainRefreshInterval: and a time value for the polling interval.

   The time value for the interval must be expressed as an integer number and a time unit. By adding this property and a time value, the runtime updating functionality is enabled.

   info

   The example in the figure below uses the domain property and a YAML-format domain configuration file, but the functionality is the same for the legacyXmlConfig property and an XML-format domain configuration file.

domain: <path_to_file>/domain.yaml

domainRefreshInterval: 5 seconds

Runtime updating of domain configuration enabled

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.

Configure ADS to retrieve authorization domain from ASM

ADS can be configured to retrieve its authorization domain from ASM/ADM or a standalone ADM. To do so, you can configure the domain property of the deployment.yaml file in order to retrieve the domain using one of the two ADM’s endpoints as displayed in the examples below.

The integration between ADS and ASM is described with more detail in ASM and ADS integration section of the Additional Resources.

Conditional requests when polling a domain name using HTTP(S)

When ADS is retrieving a domain by name using an HTTP(S) endpoint, it can include an "If-None-Match" header field to indicate to the authorization domain server which authorization domain(s) it is already in possession of. However, it does that only if it has previously received an "ETag" (entity tag) header from the authorization domain server, indicating that the server is in possession of an authorization domain.

If there is no domain present (for example, at a fresh start of ADS), ADS simply performs the GET operation and looks for an "ETag" in the response. The server may or may not include the "ETag".

If an "ETag" header has been received, ADS will in the next request send a header including an "If-None-Match" header field, with the value of the entity tag for the authorization domain present in ADS.

If this matches the domain currently pointed to by the domain name, the authorization domain server can indicate this to ADS in its response (using the "304 (Not Modified)" status code) and avoid including a complete representation of the domain in the response, thus reducing network load.

This implementation is compliant with IETF RFC 7232, §3.2Opens in a new tab, which delineates the name and semantics of the header information that clients must use for an "If-None-Match" header field, and IETF RFC 7232, §4.1Opens in a new tab, which describes the definition of the "304 (Not Modified)" status code and header information the authorization domain server will use in its response if the representation has not changed since the previous request.

note

If the deployment configuration instructs ADS to fetch its authorization domain from the file system or the classpath, the conditional request functionality does not apply. The representation will always be returned in full in the response.

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 don't want the healthcheck to not fail, when the domain refresh fails, then set the reportNotReadyOnDomainRefreshError property to false in the deployment configuration file, as shown in the sample below:

domain: <path_to_file>/domain.yaml

domainRefreshInterval: 5 seconds

reportNotReadyOnDomainRefreshError: false

Healthcheck report on failed domain updates disabled

See also Administration endpoints for more information about the healthcheck endpoint.

note

If runtime updating of domain configuration is not enabled, this property will have no effect.

info

The reportNotReadyOnDomainRefreshError property has replaced the deprecated reportUnhealthyOnDomainRefreshError.

Stop ADS from starting if a declared attribute is not provided

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

You can configure ADS to treat such a mismatch as an error and stop the application from starting or reconfiguring using that domain by adding the property failOnDeclaredAttributeNotProvided in the deployment configuration file.

domain: <path_to_file>/domain.yaml

failOnDeclaredAttributeNotProvided: true

Stop ADS from starting if a declared attribute is not provided

1. Open the deployment configuration file in a text editor.

2. Add the property failOnDeclaredAttributeNotProvided: and set the value to true.

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.