Domain

Runtime updating of domain configurations

Instead of reading the domain configuration only at start-up (which is the default), 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.

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

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.

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.

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.2, 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.1, 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

Add the property reportUnhealthyOnDomainRefreshError in the deployment configuration file to configure whether the healthcheck should return a response other than 200 OK for a running instance of ADS.

This setting is false by default. This means that as long as ADS is operational, the healthcheck will always report healthy (200 OK), regardless of the result of the latest domain refresh, as the previously working domain is still active and in use.

domain: <path_to_file>/domain.yaml

domainRefreshInterval: 5 seconds

reportUnhealthyOnDomainRefreshError: true

Healthcheck report on failed domain updates enabled

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

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

After adding this property and setting it to true, the healthcheck will not return 200 OK after a failed refresh, but instead report on the failed domain reconfiguration and alert you to the fact that the current authorization domain in use is not the latest one.

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.

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.