Additional authentication properties
To secure communications and manage access permissions, the Access Decision Service (ADS) offers a mechanism for authenticating with the Axiomatics Services Manager (ASM) or any other authorization server. This authentication process involves sending client credentials to request a domain configuration file from an authorization server.
Authentication using an authorization server
To configure ADS to use an authorization server for authentication, you need to define specific properties for domain retrieval under the domain section of the deployment.yaml file.
Configure ADS for domain retrieval
Locate the domain section in the deployment.yaml file and add the following properties to configure ADS for domain retrieval:
| Properties | Description |
|---|---|
authentication | This sub-section defines the authentication method that will be used for retrieving the domain. |
├─ username | Username for Basic authentication when retrieving the domain. Only use this if oauth2ClientId is not set. |
├─ password | Password associated with the username for Basic Authentication. Only use this if oauth2ClientId is not set. |
├─ oauth2ClientId | OAuth2 Client ID for OAuth2-based authentication. Only use this if username/password is not set. |
├─ tlsConfigurationId | (Optional) The name of the SSL bundle (defined under spring.ssl.bundle) used to configure TLS for domain retrieval requests. The referenced bundle supplies the truststore settings required to establish a secure connection to the domain endpoint. |
└─ oauth2TlsConfigurationId | (Optional) The name of the SSL bundle (defined under spring.ssl.bundle) used to configure TLS for OAuth2 token retrieval requests. Can reference the same bundle as tlsConfigurationId or a different one, allowing token retrieval to share or use a dedicated TLS configuration independently of domain retrieval. |
Only one of username/password or oauth2ClientId should be set in the authentication section.
Example Configuration
domain:
path: https://remote-endpoint.com/domain
refreshInterval: 10 seconds
reportNotReadyOnDomainRefreshError: true
authentication:
username: ${DOMAIN_USER} # Set this if using Basic Authentication
password: ${DOMAIN_PASSWORD} # Set this if using Basic Authentication
oauth2ClientId: hub-adm-client # Set this if using OAuth2
tlsConfigurationId: admBundle # Refers to the TLS configuration (see "TLS options" section)
oauth2TlsConfigurationId: tokenBundle # Refers to the TLS configuration for OAuth2 token (see "TLS options" section)
Retrieve a domain using a remote HTTP/HTTPS endpoint
ADS can retrieve an authorization domain from a remote HTTP/HTTPS endpoint using one of the following authentication methods.
- Basic
- OAuth2
Retrieve a domain using Basic authentication
To retrieve a domain using basic authentication, enter a value in the username and password properties under domain.authentication in your deployment.yaml file as shown in the sample above.
Retrieve a domain using OAuth2 authentication
To retrieve a domain using OAuth2 authentication, add the following properties under spring.security.oauth2.client in your deployment.yaml file.
For more information on Spring Security with OAuth2 refer to Spring documentationOpens in a new tab.
| Properties | Description |
|---|---|
registration | Contains settings for the OAuth2 client registration under a specific client (e.g., hub-adm-client). This defines how the client interacts with the authorization server to request tokens. |
└─hub-adm-client | Configuration settings for the OAuth2 client registration under hub-adm-client. These settings define how the application authenticates with the authorization server and requests tokens. |
├─client-id | Specifies the client identifier, uniquely identifying the client registered with the authorization server (e.g., ads). |
├─client-secret | The secret key used in conjunction with the client-id for authenticatIning the client to the authorization server. It is highly recommended to use a secure, unique value. |
├─scope | Defines the scope of access requested by the client. In this example, it is set to openid, specifying OpenID Connect authentication. |
├─authorization-grant-type | Indicates the grant type used for authentication. Here, client_credentials is specified, where the client itself, rather than a user, requests access. |
└─provider | Points to the provider configuration (e.g., hub-adm-client) that supplies the endpoint details needed for authentication. |
provider | Defines the provider settings. |
└─ hub-adm-client | Defines the URL endpoints for token retrieval. |
└─token-uri | The URI to the token endpoint for retrieving access tokens. In this case, it is https://test.axiomatics.dev/auth/realms/asm/protocol/openid-connect/token, which the client uses to obtain tokens. |
Before adding these properties to the deployment configuration file, ensure they are properly set up in the authorization server.
Axiomatics recommends using environmental variables to protect sensitive information, such as clientSecret. This approach minimizes the risk of exposing critical data in configuration files.
spring:
security:
oauth2:
client:
registration:
hub-adm-client:
client-id: ads
client-secret: {SECRET}
scope: openid
authorization-grant-type: client_credentials
provider: hub-adm-client
provider:
hub-adm-client:
token-uri: https://<hostname>/auth/realms/asm/protocol/openid-connect/token
Authorization server configuration using environment variables
TLS options
To enhance the security of your ADS configuration when communicating with any authorization server, you can incorporate Transport Layer Security (TLS). ADS supports two approaches for configuring TLS trust: using a Spring TLS bundle defined in deployment.yaml, or configuring trust at the JVM level.
ADS can be configured with either basic TLS with KeyStore for client authentication or TLS with client certificates.
- Spring TLS bundle
- JVM truststore
Configure TLS using a Spring bundle
Add the following properties under spring.ssl.bundle.jks in your deployment.yaml file.
| Properties | Description |
|---|---|
admBundle | Configuration settings for TLS, where the tlsConfigurationId is set to admBundle and provides secure connection settings including keystore and truststore configurations. |
├─keystore.location | Specifies the file system path to the keystore file containing the server’s private key and certificate, required for TLS connections (e.g., file:server_keystore.p12). |
├─keystore.password | The password used to access the keystore. It is recommended to change the default with a secure password. |
└─keystore.type | Specifies the format or type of the keystore, for example, PKCS12. |
├─truststore.location | Specifies the path to the truststore file containing trusted certificates required for TLS. |
├─truststore.password | The password used to access the truststore. It is recommended to change the default with a secure password. |
└─truststore.type | Specifies the format or type of the truststore, for example, PKCS12. |
If your TLS configuration for OAuth token retrieval is independent of domain retrieval, add the following properties as well:
| Properties | Description |
|---|---|
tokenBundle | TLS configuration settings for OAuth2 token retrieval requests. Is set to tokenBundle and provides secure connection settings including keystore and truststore configurations. |
├─keystore.location | Specifies the file system path to the keystore file containing the server’s private key and certificate, required for TLS connections (e.g., file:keystore-token.jks). |
├─keystore.password | The password used to access the keystore. It is recommended to change the default with a secure password. |
└─keystore.type | Specifies the format or type of the keystore, for example, "JKS". |
├─truststore.location | Specifies the path to the truststore file containing trusted certificates required for TLS. |
├─truststore.password | The password used to access the truststore. It is recommended to change the default with a secure password. |
└─truststore.type | Specifies the format or type of the truststore, for example, "JKS". |
Example:
spring:
ssl:
bundle:
jks:
admBundle:
keystore:
location: "file:server_keystore.p12"
password: {KEYSTORE_PASSWORD}
type: "PKCS12"
truststore:
location: "file:server_truststore.p12"
password: {TRUSTSTORE_PASSWORD}
type: "PKCS12"
tokenBundle:
keystore:
location: "file:keystore-token.jks"
password: ${KEYSTORE_PASSWORD}
type: "JKS"
truststore:
location: "file:truststore-token.jks"
password: ${TRUSTSTORE_PASSWORD}
type: "JKS"
Authorization server configuration using TLS with client certificate.
Configure TLS trust at the JVM level
As an alternative to defining a Spring TLS bundle in deployment.yaml, you can configure TLS trust at the JVM level by passing truststore properties as JVM startup arguments. The JVM truststore acts as a global trust configuration that applies to all outbound TLS connections made by ADS, without requiring any changes to the deployment.yaml file.
This approach is well-suited when:
- All outbound connections from ADS trust the same certificate authority.
- TLS trust is managed centrally at the container or platform level, for example through a shared corporate CA truststore injected at runtime.
For Kubernetes deployments of ADS, follow the instructions under the JVM Truststore tab in the Retrieve domain using TLS authentication section.
To configure JVM-level trust, pass the following system properties when starting ADS:
-Djavax.net.ssl.trustStore=<path-to-truststore>
-Djavax.net.ssl.trustStorePassword=<password>
When using JVM-level trust, the tlsConfigurationId and spring.ssl.bundle.jks properties are not required in deployment.yaml for trust validation. Client certificate authentication (mTLS) still requires a Spring TLS bundle.
Axiomatics recommends using environment variables to protect sensitive information such as the truststore password, rather than passing it as a plain-text argument.