Contribute in GitHub:

Voice Agent Insights security

Note that Voice Agent Insights is currently in beta. For more information, see the Voice Agent Insights announcement.

The Voice Agent Insights microservice relies on an OpenID Provider for authentication and API authorization. OpenID is an open standard that defines a decentralized authentication protocol. To learn more about OpenID, see What is OpenID.

In OpenID terminology, the Voice Agent Insights microservice is called a Relaying Party. This means that it does not directly authenticate users accessing its REST APIs. Instead, the Voice Agent Insights microservice redirects unauthenticated users to a configured OpenID Provider to handle authentication. To facilitate OpenID support, a simple OpenID provider that runs in a separate Docker container is provided. The Voice Agent Insights microservice is designed to work out of the box with the included OpenID Provider but it can be configured to use any third-party OpenID Provider.

The configuration instructions below describe how to setup the Voice Agent Insights microservice along with the included OpenID Provider to authenticate a single user from a single instance of the Docker images. The default configuration assumes users will access the Voice Agent Insights dashboard from localhost.

If access to the dashboard is required from a fully qualified domain name or more than one user needs access, additional configuration will be required. These details will be convered under Advanced Configuration

Configuring a simple OpenID setup (required)

The simplest configuration is to use all the defaults and only modify the credentials for a single user in the included OpenID Provider's configuration. With this configuration you will be able to log into the Voice Agent Insights dashboard from a browser running on the same localhost as the Docker images. You must set up your login credentials within the docker-compose.yml file. The password that you enter in the docker-compose.yml file must be a hashed value. This ensures that your password isn't visible or saved in plain text.

To find out the hashed representation of your password, execute the following command with the docker container running:

docker exec -it va-insights securityUtility encode --encoding=hash <YOUR_PASSWORD>

Use a strong password with special characters, upper and lower case characters, numbers, and a password length greater than eight characters long.

The output will appear similar to:

{hash}AAAAAATIzL1yoSmZ9VZAAAAAIP/nVxasmHWQKZ2VKaWHsOnnhN3xT9WiYIz1aXXXXXX

This is the hashed representation of your password. In the docker-compose.yml file, set the password to this hashed value, but exclude the starting "{hash}" segment. In this example, you should use the string:

AAAAAATIzL1yoSmZ9VZAAAAAIP/nVxasmHWQKZ2VKaWHsOnnhN3xT9WiYIz1aXXXXXX

In the docker-compose.yml file under the va.op section, enter your username and hashed password value in these environment variables.

Table 1. Basic registry authentication variables
Environment Variable	Default Value	Description
`BASIC_REGISTRY_USERNAME`	N/A	user name
`BASIC_REGISTRY_PASSWORD`	N/A	hashed password

Note: By default, the Voice Gateway Open ID Provider's basic registry has been configured with the one user in the ROLE_NAME_OPERATOR group. This default user will not have access to transcriptions because the role associated with the default user is ROLE_NAME_OPERATOR. To enable access to transcriptions through Insights you will need to define an external registry with a user in either the ROLE_NAME_EDITOR or ROLE_NAME_ADMINISTRATOR group. See Advanced User Registry Support for details:

Advanced configuration

Advanced User Registry Support

If you require insights dashboard access by more than one user, each with different roles, you can define your own registry file in the provided OpenID Provider configuration.

You can define your own registry files by performing the following steps:

Clone the sample Voice Agent Insights repository.
Modify the provided sample registry file and provide your own version of the basic registry. The file name is registry-incl.xml. Important: Do not change the name of the registry file.
Place the updated basic registry file in the local path and map the volume in the Docker Compose file to that registry files.
```
volumes:
  - "./config/registry/:/config/registry/"
```

Configuring SSL (advanced)

In the docker-compose.yml file, there is a section to specify you own keystore and another section to specify your own truststore. You can uncomment and configure Voice Agent Insights to use your own keystore and/or truststore related variables.

Environment Variable	Default Value	Description
`SSL_TRUST_STORE_FILE`	Provided by the container Java SDK	The file that contains the trusted keys. This file must be located in the security volume indicated below.
`SSL_TRUST_PASSPHRASE`	`changeIt`	The passphrase that was used to secure the `SSL_TRUST_STORE_FILE` truststore file.
`SSL_TRUST_FILE_TYPE`	JKS	The format of the `SSL_TRUST_STORE_FILE`.
`SSL_KEY_STORE_FILE`	N/A	The keystore file that contains the trusted keys for inbound SSL connections. This file must be located in the security volume indicated below.
`SSL_KEY_PASSPHRASE`	N/A	The passphrase that was used to secure the `SSL_KEY_STORE_FILE` keystore file.
`SSL_KEY_FILE_TYPE`	JKS	The format of the `SSL_KEY_STORE_FILE`.
{: caption="Table 3. Keystore and truststore variables for the `docker-compose.yml` file" caption-side="top"}

Mount the volume in the Docker Compose file for certificate files:

volumes:
  - "./config/security/:/config/resources/security/"

Note: In the default docker-compose.yml file provided in the voice.gateway.samples git repository, Voice Agent Insights points to the same trust store as the Open ID provider key store. This configuration prevents the need to move the Open ID providers certificate into the Insights trust store. Using the default file makes it simple to get a localhost installation working, but will not work if:

Non-localhost access is required (e.g. access through a Fully Qualified Domain Name)
A third party Open ID provider is required.

See the sections below on the changes needed to support these additional configurations.

Configuring a Fully Qualified Domain Name (FQDN)

For deployments where users will access Voice Agent Insights remotely instead of localhost, modify the configuration so that all redirects between the OpenID Provider and the Insights microservice are made to the associated FQDN instead of to localhost. Modify the following Insights environment variables to point to the FQDN instead of localhost:

Insights Environment Variable	Default Value	Description
`OIDC_AUTH_ENDPOINT_URL`	https://localhost:9444/oidc/endpoint/OP/authorize	Redirect URL to the OpenID authentication endopint. Passed to the browser by Insights when the request is unauthenticated.
`OIDC_LOGOUT_ENDPOINT_URL`	https://localhost:9444/oidc/endpoint/OP/logout	Redirect URL to the OpenID logout endopint. Passed to the browser by Insights when the logout method is invoked.

Additionally, modify the following Voice Agent OpenID Provider's environment variables to point the various redirect URLs to the FQDN instead of to localhost:

OpenID Provider Environment Variable	Default Value	Description
`HTTP_HOST`	localhost	Represents the URL used to access the Voice Agent OpenID Provider.
`OIDC_INSIGHTS_HOST`	localhost	Redirect URL to the Voice Agent Insights microservice.
`OIDC_ISSUER_IDENTIFIER`	https://localhost:9444/oidc/endpoint/OP	Verifiable identifier for this OpenID Provider issuer. An issuer identifier is a case-sensitive URL that uses the HTTPS scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.
`STARTUP_PAGE`	https://localhost:9443/va.insights	The redirect URL used by the OpenID Provider to redirect a browser after a logout occurs.

Configuring a third party OpenID provider

It is possible to configure the Voice Agent Insights microservice to use a third-party OpenID Provider instead of the OP included in the IBM suite of Voice Agent/Voice Gateway related microservices. To configure a third party OpenID provider, modify the following environment variables to point to the third party OP instead of localhost:

Insights Environment Variable	Default Value	Description
`OIDC_AUTH_ENDPOINT_URL`	https://localhost:9444/oidc/endpoint/OP/authorize	Redirect URL to the OpenID authentication endopint. Passed to the browser by Insights when the request is unauthenticated.
`OIDC_LOGOUT_ENDPOINT_URL`	https://localhost:9444/oidc/endpoint/OP/logout	Redirect URL to the OpenID logout endopint. Passed to the browser by Insights when the logout method is invoked.
`OIDC_TOKEN_ENDPOINT_URL`	https://va-openid-provider:9444/oidc/endpoint/OP/token	URL used by Insights to access the OpenID Provider's token endpoint URL.
`OIDC_JWK_ENDPOINT_URL`	https://va-openid-provider:9444/oidc/endpoint/OP/jwk	URL used by Insights to access the OpenID Provider's JWK endpoint URL.

Note: In addition to these configuration changes, you must register the Voice Agent Insights microservice with the third-party OP. Instructions on how to perform this registration vary depending on the OpenID provider and are outside the scope of these instructions. Refer to the OP specific instructions on how to perform this registration.

Role mapping

If the third-party OP points to a user repository where users are mapped to roles that are different than the standard Insights roles, the role mapping can be changed to match currently existing roles. The Insights REST API supports the following role variables. The default values of these variables can be changed by changing the environment variables in the docker-compose.yml file.

Table 2. Authorization roles for mapping to Insights roles
Insights Environment Variable	Default Value	Description
`ROLE_NAME_ADMINISTRATOR`	Administrator	The `administrator` role has access to all Voice Agent Insights REST APIs.
`ROLE_NAME_EDITOR`	Editor	The `editor` role has access to all Voice Agent Insights REST APIs.
`ROLE_NAME_OPERATOR`	Operator	The `operator` role has no access to transcriptions.
`ROLE_NAME_VIEWER`	Viewer	The `viewer` role has no access to transcriptions and CDRs.

Configuring session expiration

With OpenID there are two different tokens you must configure to control session expiration. The two tokens are:

JWT: JSON Web Token (JWT) is a compact URL-safe means of representing claims to be transferred between two parties. The JWT is created by the OpenID Provider.
LTPA: Once the Relaying Party (in this case the Voice Agent Insights microservice) has the JWT token, it locally maintains this token as part of its HTTP session state. An LTPA token is then used between the browser and Insights to access this session state.

Timeouts need to be set for both of these tokens using the following two environment variables:

OpenID Provider Environment Variable	Default Value	Description
`OIDC_ACCESS_TOKEN_LIFETIME`	7200s	Time that JWT token is valid (seconds). Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s). For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

Insights Environment Variable	Default Value	Description
`LTPA_TOKEN_EXPIRATION`	7200s	Amount of time after which an ltpa token expires in minutes. Specify a positive integer followed by a unit of time, which can be hours (h) or minutes (m). For example, specify 30 minutes as 30m. You can include multiple values in a single entry. For example, 1h30m is equivalent to 90 minutes.

Configuring Basic Authentication for Insights

Users can directly access the REST API exposed by the Voice Agent Insights microservice instead of using the included UI. To use the REST API, configure the microservice with a Basic authentication registry instead of relying on OpenID for authentication.

To enable Basic authentication:

Clone the voice.gateway.samples repository that can be found at https://github.com/WASdev/sample.voice.gateway.
From the samples clone, do a deep copy of the \voice-agent-insights\config directory into the directory where your docker-compose file resides.
Modify the basic-registry-incl.xml file located in the \config\insights\registry to include user name and password for the users you wish to enable. Note that the password should be hashed as describe OpenID config.
In the docker-compose file, uncomment the following volume in the va.insights section: - "./config/insights/registry/:/config/registry/"

There are a number of additional OpenID related environment variables exposed in both the Voice Agent Insights microservice and the included OpenID Provider. See the tables below for details:

Insights Environment Variable	Default Value	Description
`HTTP_PORT`	9080	HTTP port used by the Voice Agent Insights service.
`HTTPS_PORT`	9443	HTTPS port used by the Voice Agent Insights service.
`SSL_OIDC_TRUST_PASSPHRASE`	changeit	Passphrase used to access the OIDC trust store.
`SSL_OIDC_TRUST_FILE_TYPE`	JKS	Trust store key format.
`OIDC_CLIENT_ID`	va-insights	Insights OIDC client ID. Used by OpenID Provider to identify this Relaying Party.
`OIDC_CLIENT_SECRET`	changeit	Insights OIDC client secret. Used by OpenID Provider to identify request from this Relaying Party.
`OIDC_REALM`	OpBasicRealm	Insights OIDC realm. Used by OpenID Provider to identify realm related this Relaying Party.
`OIDC_SIGNATURE_ALGORITHM`	RS256	Algorithm used by the OpenID Provider to sign JWTs. Specifies the algorithm that is used to validate the JWT.

OpenID Provider Environment Variable	Default Value	Description
`HTTPS_PORT`	9444	HTTPS port used by the OpenID Provider service.
`SSL_KEY_PASSPHRASE`	changeit	Passphrase for the OpenID Provider's keystore.
`SSL_KEY_STORE_FILE`	/sslconf/key.jks	Keystore for the OpenID Provider.
`SSL_KEY_FILE_TYPE`	JKS	Keystore file type.
`OIDC_INSIGHTS_PORT`	9443	Port associated with the insights microservice.
`OIDC_INSIGHTS_CLIENT_ID`	va-insights	Client ID associated with the insights microservice.
`OIDC_INSIGHTS_CLIENT_SECRET`	changeit	Insights OIDC client secret. Used by OpenID Provider to identify request from Voice Agent Insights.