Skip to main content
Version: 1.14

Basic configuration

To run ADS, a deployment configuration file is needed. The deployment configuration file used by Access Decision Service is written in YAML. (See yaml.orgOpens in a new tab for more information about the format.)

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

Updating the deployment configuration​

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

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

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

Configuration using environment variables​

Properties in the deployment file can be configured using environment variables. The example shows a deployment configuration file that uses the environment variable PORT to set the application port.

The syntax is: ${<environment variable name>:-<default value>}.

server:
  applicationConnectors:
    - type: http
      port: ${PORT:-8888}
  adminConnectors:
    - type: http
      port: 8081

Environment variable PORT with a default value

If the environment variable is not defined, then a default value of 8888 is used. Other names can be used, for example ${APP_PORT}.

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.

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 ADS can start.

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

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

Update the license property with the URL for where the license file is stored, using one of the formats listed in the table below:

License file reference​

You can set a file reference using one of the following formats:

FormatDescription
dir/axiomatics_PDP.licenserelative path on file system
/dir/axiomatics_PDP.licenseabsolute path on file system
http://<host:port>/<path_to_file>URL to the file
https://<host:port>/<path_to_file>URL to the file
NOTE: There must be a valid certificate present that the JVM trusts. If not, a valid certificate has to be added to the truststore, and the JVM instructed to use it.
classpath:/axiomatics_PDP.licensefile on classpath

License file reference formats

License expiration warning​

ADS will warn in a log message when the license is nearing its expiration date. By default, that warning is triggered 30 days before the expiration date.

You can override this by adding an optional property to the deployment configuration file. See License expiration warning for more information.

Authorization domain configuration​

The authorization domain configuration file contains a set of XACML policies and configurations (for example, attribute connector and/or cache configurations) to be used by the authorization service. It is deployed by setting a file reference to it in the deployment configuration file.

ADS supports authorization domain configuration files expressed in two different formats, YAML and XML. Each format requires its own property for configuration:

  • for a YAML-format domain configuration file, the domain property is used. (See yaml.orgOpens in a new tab, for more information about the format.)

  • for an XML-format domain configuration file produced by the Axiomatics Services Manager (ASM) (up to and including version 6.2.9), the legacyXmlConfig property is used

note

The properties are mutually exclusive and only one of them can be enabled at any given time. The sample deployment configuration file provided in the distribution package uses the domain property configuration.

See Authorization Domains for more information about domains and how to create authorization domain configuration files.

Retrieve authorization domain from ASM​

ADS can be configured to retrieve its authorization domain from ASM.

For more details on how to setup this configuration refer to Configure ADS to retrieve authorization domain from ASM.

Updating the domain configuration during runtime​

By default, ADS is configured to read the domain configuration only once, when loading the deployment configuration file at start-up. However, there is an optional property that can be added that will make ADS poll the domain configuration source at regular intervals during runtime. See Runtime updating of domain configurations for more information.

Using a YAML-format domain configuration file​

  • Locate the domain property in the sample deployment configuration file.
domain: domain.yaml

Set a file reference to a YAML-format authorization domain configuration file. See the table below for supported formats for file references.

A sample YAML-format domain file is available in the Additional Resources section Authorization decisions domain file. This domain configuration also contains a policy that you can use to run the four example requests against, as described in the section Authorization decisions. It does not contain any attribute connector configurations.

Using an XML-format domain configuration file​

  • Add the legacyXmlConfig property in the sample deployment configuration file.
legacyXmlConfig: <path_to_file>/domain.xml

Set a file reference to an XML-format authorization domain configuration file. See the table below for supported formats for file reference.

note

An XML-format authorization domain configuration file must be produced either by exporting it from Axiomatics Services Manager (up to and including version 6.2.9) via the ASM UI or retrieved programmatically using the Admin API. It is not intended to be edited manually.

Domain management​

You can manage authorization domains from the Axiomatics Services Manager using the domain management API provided with the service. See Domain management APIOpens in a new tab in the ASM documentation for more information.

Domain configuration file reference​

The property must point to the authorization domain configuration file to be used, using one of the supported formats listed in the table:

You can set a file reference using one of the following formats:

FormatDescription
dir/file.yamlrelative path on file system
/dir/file.yamlabsolute path on file system
http://<host:port>/<path_to_file>URL to the file
https://<host:port>/<path_to_file>URL to the file
NOTE: There must be a valid certificate present that the JVM trusts. If not, a valid certificate has to be added to the truststore, and the JVM instructed to use it.
classpath:/file.yamlfile on classpath

Domain configuration file reference formats

The same retrieval options apply for both YAML- and XML-format files.

note

To have ADS send user credentials when requesting a domain configuration file from remote locations that support Basic Authentication, you need to configure an additional property. Note that this feature only supports YAML-format deployment configuration files. See HTTP client configuration for more information.

Authentication​

Locate the authentication section in the sample deployment configuration file.

The available types of authentication are None, Basic and Token.

When type is set to None (no user name or password needed for access), then any additional entries (user or jwt) in the authentication section, will be ignored.

Basic authentication​

To use Basic authentication set the type property to Basic and enter the user property including the username and hashedPassword. Generate the hashed password using the SHA-256 algorithm. Only one user can be configured for use with the Basic authentication option.

authentication:
  type: Basic
  user:
    username: ads-user
    hashPassword: <sha-256 hash password>

Basic authentication

When type is set to Basic authentication, the authenticated user can access any endpoint on ADS.

JWT authentication​

To use JSON Web Token (JWT) authentication, set the type property to Token and configure the authentication section as in the example below: 

authentication:  
  type: Token
  jwt:    
     jwksUri: "https://localhost/api/.well-known/jwks"      # Required ( Only 'file:' or 'https:' URIs are allowed)
     audience: ["ads", "axiomatics"]            # Optional
     issuer:   "axiomatics"                     # Optional
     clockSkew: 30                              # Optional

JWT authentication

JWT verification properties​

  • jwksUri

    The jwksUri property is used to represent the JSON Web Key Set (JWKS) and it can only be set to a file or a HTTPS protocol.

    • If set to a local file, the jwksUri property should have the file: prefix, and the file content should be in the JWKS format.

    • If set to a HTTPS URI, the jwksUri property should have the https: prefix, and the endpoint should provide a JWKS response. Please note that http is not an accepted protocol for jwksUri.

​ In order to verify JWTs using your own keys, you will need to first convert them to the JWKS format. ​ This can be achieved either manually or programmatically using a suitable library.

  • audience

    The audience property corresponds to the aud claim. This property is optional.

  • issuer

    The issuer property corresponds to the iss claim. This property is optional.

    tip

    You can adjust these properties in order to limit the values that are permitted.

  • clockSkew

    The clockSkew property determines the acceptable time difference (measured in seconds) between the time on the token issuer's clock and ADS' clock when validating the exp and nbf claims. This property is optional and its default value is 0.

    The clockSkew property can take both positive and negative values:

    • If set to a positive integer (e.g., 30), the system performing the token validation will allow for a time difference of up to the specified number of seconds between the token issuer's clock and ADS' clock. This extends the validity period specified by the nbf and exp claims.
    • If set to a negative integer (e.g., -30), the system will account for a time difference of up to the specified number of seconds in the past. This shortens the validity period specified by the nbf and exp claims and can be useful in scenarios where the token issuer's clock may be a little ahead of ADS' clock.
    • If no value is provided, or if the value is explicitly set to 0, the token's exp and nbf claims must be strictly accurate, and any time difference beyond 0 seconds will cause the token to be considered invalid.
    note

    It is recommended to set the clockSkew value to an integer that corresponds to a reasonable time window, typically representing a few minutes.

tip

The following claims are required for a successful token authentication:

  • exp
  • sub

Refer to the official RFC documentationOpens in a new tab for more information.

note

Soap API is not supported when Token authentication is configured.

Service connectors​

Locate the server: property in the sample deployment configuration file.

In this section, service connectors to the server can be configured to use specific ports and/or encryption to secure communication. Both TLS and TLS with client certificate can be used.

Application and administration endpoints​

By default, the application endpoint will use port 8080 and the administration endpoint will use port 8081. The properties for applicationConnectors and adminConnectors can be configured to use specific ports in the deployment configuration YAML file.

A recommended configuration would have separate ports for the application and administration endpoints. For example:

server:
  applicationConnectors:
    - type: http
      port: 8080
  adminConnectors:
    - type: http
      port: 8081

Recommended port configuration

note

Axiomatics strongly recommends configuring the ports explicitly. This will simplify troubleshooting, should that be necessary.

Single port configuration​

If limitations of your environment prevents you from using a dual-port configuration, it is also possible to configure a single port for all the endpoints, either as HTTP or HTTPS (in this case, application endpoints and administration endpoints will be prepended with the path /application and /admin, respectively), using type: simple. For example:

server:
    type: simple
    connector:
       type: http
       port: 8081

Single port configuration

TLS and TLS with client certificate​

In the sample deployment configuration file, the applicationConnectors and adminConnectors properties are configured for HTTP. (See the sample configuration above.)

If HTTPS is used, the property can be configured for TLS or TLS with client certificate:

server:
  applicationConnectors:
    ## Requirements to enable TLS
    - type: https
      port: 8443
      keyStorePath: file:<path_to_file>/server.keystore
      keyStorePassword: changeit
      keyStoreType: pkcs12

Disable SNI host checking​

When making requests over HTTPS, the SNI host checking is enabled by default in Dropwizard 3.x. It is recommended to disable it in order to ensure smooth connection between the service connectors and the server.

To disable SNI in the sample configuration file, add the disableSniHostCheck property and set it to true as show in the example below:

server:
  applicationConnectors:
    - type: https
      port: 8080
      ..
      disableSniHostCheck: true
  adminConnectors:
    - type: https
      port: 8081
      ..
      disableSniHostCheck: true

SNI disabled

For more information about SNI, please refer to the SNI host checkingOpens in a new tab section of the Dropwizard documentation.

note

These instructions are applicable only to ADS version 1.14.0, as SNI host checking is disabled in later versions.

Logging​

  • Locate the logging section in the sample deployment configuration file.

Enabling audit logging​

A configuration for audit logging is provided in the sample deployment configuration file. By default, it is disabled.

logging:
  level: WARN
  #loggers:
  #  "com.axiomatics.audit": INFO
  appenders:
    - type: console
      target: stdout
      timeZone: system

Audit logging disabled

In the sample deployment configuration, the appender type is set to console and the target to stdout.

Some of the log events in ADS may generate multi-line messages. This is not always desirable, for example, if you are using a log analysis tool that requires single-line log messages. This can be resolved by configuring the logging property to use a JSON layout. See Configuring single-line per event log output for more information.

The audit logs produced by ADS contain two types of events, evaluation events and administrative events. You can control whether log output files should contain either evaluation events or administrative events or both. See Separating event types in the audit log output for more information.

By default, the log output for evaluation events is presented in a concise format. For processing efficiency, information not essential to auditing is excluded from the evaluation events. If the full logging information is required, this can be configured using an additional property. See Enabling verbose audit logging for more information.

See the section Audit log message format for output examples and more information about the logging output format.

Disabling audit logging​

  • To disable audit logging example in the sample configuration file, comment out the "loggers" property and the com.axiomatics.audit parameter in the deployment configuration file.

Configuring other logging options​

If there is a need to change the logging configuration, for example, to add other appenders, or accommodate requirements for a different output type or log format, several options are available:

  • Further examples of logging configurations are available in the section Additional Configurations

  • For more information about Dropwizard logging configuration options, please refer to the logging sectionOpens in a new tab of the Dropwizard documentation.

  • Furthermore, Dropwizard implements the Logback logging system. Refer to Logback documentationOpens in a new tab, for more information.

Additional deployment configuration​

There are configuration properties that are not included in the sample deployment configuration files that may be relevant for some users. See Additional Configurations for more information.

Disclaimer​

Access Decision Service makes use of the Dropwizard framework for its implementation.

There are many configuration options available in Dropwizard. However, only properties explicitly mentioned in the Access Decision Service documentation are supported. Axiomatics assumes no responsibility or liability for the use of other configuration options.

For more information about Dropwizard configuration options, please refer to the Dropwizard documentationOpens in a new tab.