Advanced Configuration

#### Search Results

Search

# Advanced Configuration

- Encrypting Passwords

- Configuration File Option: Class Path

- Open Id Connect Authentication

- Health Check HTTP Call

- REDIS© Cluster

- Keyboard Mapping

## Encrypting Passwords

Each password parameter should be encrypted in the application.properties file.

- Procedure

- Example

### Procedure

Follow these steps to encrypt a password:

1. Decide on which password to encrypt.

2. Run `encryptPassword.sh` under the /bin directory with the following command:

   `encryptPassword.sh --encryption-password <JASYPT_ENCRYPTOR_PASSWORD> <passphrase>`

   The `JASYPT_ENCRYPTOR_PASSWORD` property is the key to encrypt the passphrase. It can be any string combination.

3. Place the value received from running the shell script as the password value. This value should be wrapped in `‘ENC()’` string to mark the fact that this password is encrypted.

4. In a running testing or production environment, the `JASYPT_ENCRYPTOR_PASSWORD` should be set as an environment variable.

### Example

In the following example, the required password for the `spring.data.redis.password` property is `‘pass1’`, and the `JASYPT_ENCRYPTOR_PASSWORD` property was decided to be `‘pass2’`.

Run the shell script as follows:

`encryptPassword.sh --encryption-password pass2 pass1`

The output received from the shell script could be `AAAABBBB44444FFFBB`.

This value should be set as property in the application.properties as follows:

`spring.data.redis.password=ENC(AAAABBBB44444FFFBB)`

This process must be done for each password used in the application.properties file.

The same `JASYPT_ENCRYPTOR_PASSWORD` property must be used for all encrypted properties.

When subsequently accessing the server that runs the application (for production or testing), an environment variable must be set for the key `JASYPT_ENCRYPTOR_PASSWORD` with the value `pass2`.

## Configuration File Option: Class Path

An alternative option to supply the configuration files (application.properties and license file) is by adding a resource directory to the `NaturalAvailiablityServer` class path in the servlet container:

- For WildFly®

- For Tomcat®

### For WildFly®

A module needs to be defined in order to add filles to the class path:

1. Create a directory that contains the resource files.

2. Run the following command to add the module. The module name should stay as defined in the command:

   `/opt/jboss/wildfly/bin/jbos–cli.sh -c –command=”module add –name=natural-availability-server-configuration --resource-delimiter=, --resources=<path to folder created>/application.properties, <path to folder created>/nha<version-number>.xml"`

### For Tomcat®

Configure the location of the application.properties file:

1. In the application.properties, set the `licensePath` property pointing to the location of the license file.

2. Create the following file under Tomcat® installation:

   <tomcat installation>/conf/Catalina/myHost/NaturalAvailabilityServer.xml

   … where myHost is the host name.

3. In this file NaturalAvailabilityServer.xml, add the following element:

   `<Context> <Environment name=" spring_config_location" value="<location of application.properties>/application.properties" type="java.lang.String"/> </Context>`

## Open Id Connect Authentication

- Predefined Public Identity Providers

- Basic Configuration

- Optional Properties

- Properties Needed for Custom OIDC Provider

- Example: Google Identity Provider

### Predefined Public Identity Providers

Support of OIDC (OpenID Connect) authentication requires an identity provider to be defined. Likewise, Natural Availability Server needs to be defined as a client of the identity provider.

Natural Availability Server brings along predefined public identity providers (Google©, GitHub©, and Facebook©).

If you are not using one of those public identity providers, you need to configure a custom identity provider.

### Basic Configuration

For the aforementioned commonly used identity providers (Google©, GitHub©, and Facebook©), only a minimal set of properties needs to be defined.

Once these properties are set, the Natural Availability Server will automatically detect that the applicable authentication method is Open Id Connect.

The following minimal properties are required:

Property name | Description | Required | Default and Optional Values
--- | --- | --- | ---
`spring.security.oauth2.client.registration.<identity provider>.client-id` | The client ID issued by the OAuth2 provider. | yes | No default value
`spring.security.oauth2.client.registration.<identity provider>.client-secret` | The client secret issued by the OAuth2. This is a sensitive value and should be protected. | yes | No default value
`com.softwareag.natural.web.frontend.server.config.oauth2.usernameField` | The attribute received from the identity provider that is used for the user name. | yes | email

Note
The `<identity provider>` should be filled with the identity provider name for example `google`, `facebook`, etc.

### Optional Properties

The following properties are optional and allow for customizing the user name field and the auto-login.

Property name | Description | Required | Default and Optional Values
--- | --- | --- | ---
`com.softwareag.natural.client.config.auto-connect` | Define, whether the login to the web application in OIDC authentication will be done automatically (without activating the Login button of the login screen) or whether it should be done manually. | no | yes
`com.softwareag.natural.web.frontend.server.config.oauth2.removePrefixFromUsername` | Enable removal of the string before the prefix delimiter of the `usernameField` property. | no | no
`com.softwareag.natural.web.frontend.server.config.oauth2.usernamePrefixDelimiter` | A delimiter that defines the prefix to be removed of the `usernameField` property. | no | empty string
`com.softwareag.natural.web.frontend.server.config.oauth2.removeSuffixFromUsername` | Enable removal of the string after the suffix delimiter of the `usernameField` property. | no | no
`com.softwareag.natural.web.frontend.server.config.oauth2.usernameSuffixDelimiter` | A delimiter that defines the suffix to be removed of the `usernameField` property. | no | @

In case the OIDC provider is not predefined in the Natural Availability Server, you can configure your own OIDC provider in the application.properties file.

### Properties Needed for Custom OIDC Provider

For the configuration of custom OIDC identity providers, the following properties need to be considered:

Property name | Description | Required | Default and Optional Values
--- | --- | --- | ---
`spring.security.oauth2.client.provider.<identity provider>.authorization-uri` | The URI where the OAuth2 Authorization Request is sent. This is the endpoint that the user will be redirected to for logging in. | yes |
`spring.security.oauth2.client.provider.<identity provider>.issuer-uri` | The URI that identifies the issuer of the OpenID Connect (OIDC) provider. | yes |
`spring.security.oauth2.client.provider.<identity provider>.jwk-set-uri` | The URI to the provider’s JSON Web Key Set (JWKS), which contains the public keys used to verify the signatures of the JWT tokens. | yes |
`spring.security.oauth2.client.provider.<identity provider>.token-uri=` | The URI where the OAuth2 Token Request is sent to obtain the access token. | yes |
`spring.security.oauth2.client.provider.<identity provider>.user-info-authentication-method` | Defines how the user information request is authenticated, typically by including the access token in the request. | yes | Possible values are: header form etc.
`provider.<identity provider>.user-info-uri` | The URI where the User Info Request is sent to obtain user information from the OAuth2 provider. | yes |
`provider.<identity provider>.user-name-attribute` | The attribute name used to extract the user’s name from the User Info endpoint response. | yes |

Note
The `<identity provider>` should be filled with the identity provider name for example `google`, `facebook`, etc.

#### Example Configuration:

    spring.security.oauth2.client.provider.custom-provider.issuer-uri=https://accounts.example.com
    spring.security.oauth2.client.provider.custom-provider.authorization-uri=https://accounts.example.com/oauth2/authorize
    spring.security.oauth2.client.provider.custom-provider.token-uri=https://accounts.example.com/oauth2/token
    spring.security.oauth2.client.provider.custom-provider.user-info-uri=https://accounts.example.com/userinfo
    spring.security.oauth2.client.provider.custom-provider.user-info-authentication-method=header
    spring.security.oauth2.client.provider.custom-provider.jwk-set-uri=https://accounts.example.com/oauth2/certs spring.security.oauth2.client.provider.custom-provider.user-name-attribute=id

Optionally, for the configuration of Natural Availability Server as a client of the OIDC identity providers, the following properties should be set:

Property name | Description | Required | Default and Optional Values
--- | --- | --- | ---
`spring.security.oauth2.client.registration.<identity provider>.authorization-grant-type` | The type of authorization grant used to obtain the access token. | yes | The value should be set to: authorization_code
`spring.security.oauth2.client.registration.<identity provider>.client-authentication-method` | The method used to authenticate the client with the OAuth2 provider. | yes | Common values are: basic post
`spring.security.oauth2.client.registration. <identity provider>.client-id` | The client ID issued by the OAuth2 provider. | yes | none
`spring.security.oauth2.client.registration. <identity provider>.client-name` | user-friendly name for the client. It is primarily used in UI contexts. | no |
`spring.security.oauth2.client.registration.<identity provider>.client-secret` | The client-secret issued by the OAuth2 provider. It is a sensitive value and should be protected. | yes |
`spring.security.oauth2.client.registration. <identity provider>.provider` | The ID of the OAuth2 provider configuration that this registration corresponds to. | yes |
`spring.security.oauth2.client.registration. <identity provider>.redirect-uri` | The URI where the OAuth2 provider redirects the user after authorization. This should match the one registered with the provider. When using the load balancer, the redirect-uri should be specified to match the load balancer's URL. | yes | When using the load-balancer, the value should be: <load-balancer-url>/login/oauth2/code/<identity provider>
`spring.security.oauth2.client.registration. <identity provider>.scope[]` | The scopes that your application is requesting from the OAuth2 provider. Multiple scopes can be specified as ... scope[0], scope[1] etc. | yes |

Note
The `<identity provider>` should be filled with the identity provider name for example `google`, `facebook`, etc.

#### Example Configuration for okta©:

    spring.security.oauth2.client.registration.okta.client-id=your-okta-client-id
    spring.security.oauth2.client.registration.okta.client-secret=your-okta-client-secret
    spring.security.oauth2.client.registration.okta.client-authentication-method=post
    spring.security.oauth2.client.registration.okta.authorization-grant-type=authorization_code
    spring.security.oauth2.client.registration.okta.redirect-uri={baseUrl}/login/oauth2/code/okta
    spring.security.oauth2.client.registration.okta.scope[0]=openid
    spring.security.oauth2.client.registration.okta.scope[1]=profile
    spring.security.oauth2.client.registration.okta.scope[2]=email
    spring.security.oauth2.client.registration.okta.client-name=Okta
    spring.security.oauth2.client.registration.okta.provider=okta
    spring.security.oauth2.client.provider.okta.issuer-uri=https://your-okta-domain.okta.com/oauth2/default

### Example: Google Identity Provider

To set up a minimal configuration for OpenIdConnect with Google©

1. - Connect to Google console at: https://console.cloud.google.com/

   - Choose APIs and Services

   - On the left-hand side, navigate to credentials

   - Click on the client link in the OAuth 2.0 Client IDs table

     Create an OAuth 2.0 client ID for web application should this entry not exist

2. Copy the `client-id` and `client-secret`, and paste them into the application.properties file:

       spring.security.oauth2.client.registration.google.client-id=<your client id>.apps.googleusercontent.com
       spring.security.oauth2.client.registration.google.client-secret=<client secret>

Note
When using the load balancer, the `redirect-uri` should be specified to match the load balancer's URL:

    spring.security.oauth2.client.registration.google.redirect-uri=<load-balancer-url>/login/oauth2/code/google

## Health Check HTTP Call

This HTTP call checks the availability of the Natural Availability Server and the Natural Web I/O Interface server.

When calling the service, the Natural Availability Server will access the Natural Web I/O Interface server and verify its availability.

The HTTP call is designed to supply the availability state of the node to the load balancer.

The availability check is done continuously in the background and the last state is reflected in the health check URL.

The background task can be configured using the following properties:

#####

Property name | Description | Required | Default and Optional Values
--- | --- | --- | ---
`com.softwareag.natural.chimera.connection. continuousHealthcheck` | Determines whether this service is available or not. | false | false
`com.softwareag.natural.chimera.connection.healthCheckInterval` | Defines the time between requests sent from Natural Availability Server to the Natural Web I/O Interface daemon. | false | 5000 (milliseconds)

- To call this API, a request needs to be sent to the following URL:

  <server>:<HTTP port>/healthcheck

  Example:

  http://localhost:8080/healthcheck

- Option responses from calling this API are:

  > Response code : 200

  >   Alive - Indicates that the server and host are available.

  > Error 404

  >   Indicates that the health check API is disabled.

  > Error 503

  >   Indicates that the Natural Web I/O Interface daemon is not available.

## REDIS© Cluster

When using a single-node REDIS© server, high availability cannot be guaranteed because the REDIS© server can fail. To overcome this problem, REDIS© can use replications.

For replications, Natural Availability Server supports REDIS© Enterprise. The REDIS© Enterprise can be used on-premise or as SaaS.

Use the following properties for the REDIS© configuration:

Property name | Description | Required | Default and Optional Values
--- | --- | --- | ---
`spring.data.redis.cluster.nodes` | A list of REDIS© servers in the format of : `<machine1 name>:<redis port>, <machine2 name>: <redis port> etc` | For REDIS© cluster | none
`spring.redis.cluster.max-redirects` | Number of allowed cluster redirections. | For REDIS© cluster | none

Note
The property `spring.data.redis.cluster.nodes` should not be used together with the property `spring.data.redis.host`.

## Keyboard Mapping

The following table defines the options to define keyboard combination that will be used to define a special behavior in the web application.

The combination can use modifier keys (Ctrl , Shift, Alt) and any character. For example:

- a single character, Esc, Insert, Delete, F4, and so on

- Shift+<any character >

- Ctrl+<any character >

- Ctrl+Shift+<any character >

- Ctrl+Alt+<any character >

- Ctrl+Shift+Alt+<any character >

If you are using any modifier keys, make sure they can be used in the following order: Ctrl > Shift > Alt.

You cannot write Shift+Ctrl+F5, but you can write Ctrl+Shift+F5.

Note
All keyboard mapping properties are optional, and they do not have a default value.

Property name | Description
--- | ---
`com.softwareag.natural.client.config.keyboard-mapping.insertKey` | Define a key for toggling between insert mode (replace mode) and regular web application behavior (the replace mode overrides the next character inside input field with the new typed characters).
`com.softwareag.natural.client.config.keyboard-mapping.helpKey` | Define a key for calling the help routine on a field.
`com.softwareag.natural.client.config.keyboard-mapping.carriage-return-key` | Define a key for carriage return (enter behavior).
`com.softwareag.natural.client.config.keyboard-mapping.clearEndOfField` | Define a key that will clear the content of the field from the caret position to the end of the field.
`com.softwareag.natural.client.config.keyboard-mapping.escapeKey` | Define a key that will invoke escape behavior.
`com.softwareag.natural.client.config.keyboard-mapping.backSpaceKey` | Define a key that will invoke backspace behavior.
`com.softwareag.natural.client.config.keyboard-mapping.backTabKey` | Define a key that will invoke back tab behavior.
`com.softwareag.natural.client.config.keyboard-mapping.invokeTabKey` | Define a key that will invoke tab behavior.
`com.softwareag.natural.client.config.keyboard-mapping.deleteCharKey` | Define a key that will clear the next character in an input field.
`com.softwareag.natural.client.config.keyboard-mapping.pageDownKey` | Define a key that will invoke page down behavior.
`com.softwareag.natural.client.config.keyboard-mapping.pageUpKey` | Define a key that will invoke page up behavior.
`com.softwareag.natural.client.config.keyboard-mapping.refreshKey` | Define a key that will invoke page refresh behavior.
`com.softwareag.natural.client.config.keyboard-mapping.jumpToNextLineKey` | Define a key that will set focus on the first field in the next line.

### On this page

- Encrypting Passwords
- Configuration File Option: Class Path
- Open Id Connect Authentication
- Health Check HTTP Call
- REDIS© Cluster
- Keyboard Mapping