Skip to main content
Version: 1.1

Basic configuration

To run the Contextual Authorization Query, a deployment configuration file is needed. This deployment file, used by the CAQ, is written in YAML. (See yaml.orgOpens in a new tab for more information about the format.)

The Deployment configuration file sample provides a template that you can copy and use for your configuration. See the descriptions for the different properties below.

The deployment file contains property settings for which you have to stop the application to update, as CAQ reads it only at start-up.

note

To update any part of the configuration, simply stop the CAQ (that is, kill the process), update the file, and then restart CAQ.

Some properties use file references, like <path_to_file>. These should always be seen as relative to the environment in which CAQ is running.

License​

A license is required to run the product. The license file is provided separately by Axiomatics, and it needs to be in place before the CAQ can start.

This is how to set the file reference to the license key file:

  • Locate the license property in the deployment configuration file.
license: <path_to_file>/axiomatics_CAQ.license

Update the license property with the appropriate license file.

If the license expires you need to use a new one. Please contact the Axiomatics Customer Support to acquire a new license file.

Authorization domain configuration​

The CAQ reads the authorization domain from a YAML-based format file, when loading the deployment configuration file at startup, using the domain property. (See yaml.orgOpens in a new tab, for more information about the format.)

You can also provide the domain file as a system/env property as described in Environmental Variables

Domain configuration file​

Locate the domain property in the deployment configuration file.

domain: <path_to_file>/example.yml
note

Using an XML-format authorization domain configuration file is not supported by the CAQ. In case you have an .xml file, you need to convert it to the .yaml format. The domain conversion tool can be used to convert the xml to yaml format as described in CAQ and ASM 6.2.x integration.

The domain property can be any of the supported formats, as listed in the tabs below:

Relative or absolute file path on file system:

domain: <path_to_file>/file.yaml

Runtime updating of domain configurations​

By default, CAQ reads the domain configuration only once, when loading the deployment configuration file at start-up.

Instead of reading the domain configuration only at start-up (which is the default), CAQ 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 CAQ each time the domain configuration is updated. This may be particularly useful during policy development and testing.

domain: <path_to_file>/example.yml
domainRefreshInterval: 5 min

Domain will be updated during runtime in intervals of 5 minutes

To enable runtime updating of domain configuration:

  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 (e.g. 1 s, 2 seconds, 3 m, 4 min, 5 mins, 6 minutes).

By adding this property and a time value, the runtime updating functionality is enabled.

The updating process involves no downtime. The service of CAQ keeps accepting and processing requests while reconfiguring, and a running CAQ 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.

Authentication​

By default, Contextual Authorization Query uses basic authentication.

Enter a user name and a password in the authentication section of the deployment configuration file:

note

In the snippets below replace:

  • <username> with your username.
  • <password> with your password.
authentication:
  type: basic
  user:
    username: <username>
    password: <password>

Authentication section in the deployment configuration file

CAQ supports using as a password, both plain text or alphanumeric values produced with one of the various hash algorithms. You can encrypt your password using various hashing methods with the corresponding {id} as prefix and the " " characters.

Below are some examples of a hashed password using secret:

password: secret

or

password: "{noop}secret"

If no authentication type is configured then by default basic authentication is enabled.

note

If authentication is not required, the authentication type has to be set to none.

For example:

authentication:
  type: none

Disabling authentication in the Authentication section of the deployment configuration file

Environmental variables​

Properties in the deployment configuration file can be configured using environment variables. The example shows part of a deployment configuration file that uses the environment variable PASSWORD to set the authentication password.

The syntax is: <property name>: ${enviromental variable name}.

authentication:
  type: basic
  user:
   username: admin
   password: ${PASSWORD}

Authentication using an environmental attribute for password

note

Axiomatics recommends using environment variables to substitute any sensitive information, such as passwords, so that sensitive information can be managed and protected using generic mechanisms, external to the deployment file.