Configuring the system for SSL/TLS connections

If you chose to enable SSL during the BMC AMI Ops User Interface installation process, you need to customize the security protocol for the system to make sure the components can send and receive data as expected. Customization involves creating SSL/TLS certificates, updating the common environment variables (AMICMNEV) member of the &HLQ.UBBSAMP data set, and editing the JCL script.

You need to adjust or confirm the protocol for the following servers and services:

BMC AMI Ops UI Server (Application server)
BMC AMI Ops UI Discovery server (Eureka server)
BMC AMI Ops Monitor service (Ops monitor)
BMC AMI Ops Insight service (for details, see Planning and Configuring after installation in the BMC AMI Ops Insight documentation)

Before you begin

To enable secure communication with SSL/TLS, you must create or obtain client certificates, or create a RACF keyring.

Best practice

Use a certificate authority (CA)-signed certificate in a production environment.

Important

If you want to use the keyring, the server started task must have:

The correct keyring user name
Read and Update access to the keyring

To set HTTPS connections

Set the following properties in the AMICMNEV member of the &HLQ.UBBSAMP data set:
SSL_ENABLE=true
AMIDSC_PORT_TYPE=https
AMIDSC_SECURED=true
AMIDSC_UNSECURED=false

Set the following keystore details. The values are the same as those you entered during installation and as you determined in the Planning topic.

Property	Description
AMIAPS_KEYSTORE_TYPE=keystoreType	Type of keystore Enter one of the following values: JKS, PKCS12, JCERACFKS, or JCECCARACFKS.
AMIAPS_KEYSTORE_NAME=<keystoreName>	Name of the BMC AMI Ops UI Server keystore Enter one of the following information: USS path where the Keystore is located (for example, /u/MAINVIEW/opsui/amiops.keystore ) RACF keyring path created using any mainframe SAF mechanism (for example, safkeyring://USER/Keyring_name)
AMIMON_KEYSTORE_NAME=<monitorKeystoreName>	Name of the BMC AMI Ops Monitor server keystore Enter one of the following information: USS path where the Keystore is located (for example, /u/MAINVIEW/opsui/amiops.keystore ) RACF keyring path created using any mainframe SAF mechanism (for example, safkeyring://USER/Keyring_name)
AMIAPS_KEYSTORE_LABEL=<certificateAlias> ²	Enter the Keystore alias Tip We recommend not to use spaces in the label values.
AMIAPS_KEYSTORE_PASSWORD=<keystorePassword>	Keystore password For a RACF Keyring (JCERACFKS or JCECCARACFKS type), the value must be password.
AMIDSC_KEYSTORE_TYPE=<keystoreType>	Type of Keystore Enter one of the following values: JKS, PKCS12, JCERACFKS, or JCECCARACFKS.
AMIMON_KEYSTORE_TYPE=<keystoreType>	Type of Keystore Enter one of the following values: JKS, PKCS12, JCERACFKS, or JCECCARACFKS.
AMIDSC_KEYSTORE_PASSWORD=<keystorePassword>	Keystore password For a RACF keyring (JCERACFKS or JCECCARACFKS type), the value must be password.
AMIDSC_KEYSTORE_LABEL=<certificateAlias>²	Enter the Keystore alias Tip We recommend not to use spaces in the label values.
AMIMON_KEYSTORE_LABEL=<certificateAlias>²	Enter the Keystore alias Tip We recommend not to use spaces in the label values.
AMIMON_KEYSTORE_PASSWORD=<keystorePassword>	Keystore password For a RACF keyring (JCERACFKS or JCECCARACFKS type), the value must be password.
AMIDSC_KEYSTORE_NAME=serviceregistryKeystoreName	Name of the BMC AMI Ops UI Discovery server server keystore Enter one of the following information: USS path where the Keystore is located (for example, /u/MAINVIEW/opsui/amiops.keystore ) RACF keyring path created using any mainframe SAF mechanism (for example, safkeyring://USER/Keyring_name)
AMIMGR_KEYSTORE_TYPE=<keystoreType>	Type of keystore Enter one of the following values: JKS, PKCS12, JCERACFKS, or JCECCARACFKS.
AMIMGR_KEYSTORE_ALIAS=<certificateAlias>	Enter the Keystore alias Tip We recommend not to use spaces in the label values.
AMIMGR_KEYSTORE_PASSWORD=<keystorePassword>	Keystore password For a RACF keyring (JCERACFKS or JCECCARACFKS type), the value must be password.
AMIMGR_KEYSTORE_NAME=amiManagerKeystoreName	Name of the BMC AMI Managerserver keystore Enter one of the following information: USS path where the Keystore is located (for example, /u/MAINVIEW/opsui/amiops.keystore ) RACF keyring path created using any mainframe SAF mechanism (for example, safkeyring://USER/Keyring_name)

Set the following Truststore details. The values are the same as those you entered during installation and as you determined in the Planning topic.

Property	Description
AMIAPS_TRUSTSTORE_TYPE=truststoreType¹	Type of truststore Enter one of the following values: JKS, PKCS12, JCERACFKS, or JCECCARACFKS.
AMIAPS_TRUSTSTORE_NAME=truststoreName	Name of the BMC AMI Ops UI Server truststore Enter one of the following information: USS path where the Truststore is located (for example, /u/MAINVIEW/opsui/amiops.jks) RACF keyring path created using any mainframe SAF mechanism (for example, safkeyring://USER/Keyring_name)
AMIAPS_TRUSTSTORE_PASSWORD=<truststorepassword>	Truststore password For a RACF keyring (JCERACFKS or JCECCARACFKS type) the value must be password.

1. If the keystore type is JCERACFKS or JCECCARACFKS and cannot be used as a truststore, use the JKS type instead, but make sure that the SAF keyring certificate is imported to the JKS truststore.
2. If the keystore label name contains spaces, enclose the following values in double quotes (") in AMIAPSEV and AMIDSCEV environment members (in the &HLQ.BMCPCNFG data set), and the MUXMONEV member (in the &HLQ.BMCSAMP data set):

For BMC AMI Ops UI Server
export AMIAPS_KEYSTORE_LABEL="$AMIAPS_KEYSTORE_LABEL"
For BMC AMI Ops UI Discovery server
export AMIDSC_KEYSTORE_LABEL="$AMIDSC_KEYSTORE_LABEL"
For BMC AMI Ops Monitor server
export AMIMON_KEYSTORE_LABEL="$AMIMON_KEYSTORE_LABEL"

Validate the JCL script for SSL communication by confirming that the following lines are present and uncommented in the AMIAPSEV and AMIDSCEV environment members that are located in the &HLQ.BMCPCNFG data set, and the MUXMONEV member that is located in the &HLQ.BMCSAMP data set:
IJO="$IJO -Djavax.net.ssl.trustStorePassword=${AMIAPS_TRUSTSTORE_PASSWORD}"
IJO="$IJO -Djavax.net.ssl.trustStore=${AMIAPS_TRUSTSTORE_NAME}"
IJO="$IJO -Djavax.net.ssl.trustStoreType=${AMIAPS_TRUSTSTORE_TYPE}"

Updating client certificate settings

You can enable or disable client certificate authentication and update the client certificate details.

Client certificate should be added to RACF against a user.

To enable or disable client certificate authentication

Set the following properties in the AMICMNEV member of the &HLQ.UBBSAMP data set. The values are the same as those you entered during installation and as you determined in the Planning topic.

Property	Description
AMIAPS_CLIENT_AUTH	Whether to enable client authentication Enter one of the following values: none—Disables client authentication and no client certificate are in use. need—Enables client authentication and certificates are required. For BMC AMI Ops Insight user roles configuration, see To update User role settings when using client certificate.
AMIAPS_ALLOW_CLIENT_CERT	Whether to allow authentication of credentials when the digital certificate are configured Important AMIAPS_ALLOW_CLIENT_CERT parameter is considered only when AMIAPS_CLIENT_AUTH is needed. Enter one of the following values: true—Allows authentication by using a digital certificate or user ID and password (mainframe credentials). false—Only digital certificate authentication is allowed.

Property

Description

AMIAPS_CLIENT_AUTH

Whether to enable client authentication

Enter one of the following values:

none—Disables client authentication and no client certificate are in use.
need—Enables client authentication and certificates are required.
For BMC AMI Ops Insight user roles configuration, see To update User role settings when using client certificate.

AMIAPS_ALLOW_CLIENT_CERT

Whether to allow authentication of credentials when the digital certificate are configured

Important

AMIAPS_ALLOW_CLIENT_CERT parameter is considered only when AMIAPS_CLIENT_AUTH is needed.

Enter one of the following values:

true—Allows authentication by using a digital certificate or user ID and password (mainframe credentials).
false—Only digital certificate authentication is allowed.

To update User role settings when using client certificate

(Use this option only for BMC AMI Ops Insight.)

Set the following properties in AMIAPSEV environment member that is located in the &HLQ.BMCPCNFG data set.

User role global settings when using client certificate:

Properties	Description
export APS_CLT_CRT_ID_MAPPING=true	Set to true If client certificate is created with hostIdMapping, which is the host and user id mapping, the user roles (none, user or admin) are fetched from RACF definitions for mapped user id. Important You need to secure a client certificate with hostIdMapping from your security team. Set to false If client certificate is not created with hostIdMapping or if you want to define user's role, you must follow the User role manual settings. Important If hostIdMapping is not present in the certificate, then common name (CN) of the certificate is picked up as username.

Properties

Description

export APS_CLT_CRT_ID_MAPPING=true

Set to true

If client certificate is created with hostIdMapping, which is the host and user id mapping, the user roles (none, user or admin) are fetched from RACF definitions for mapped user id.

Important

You need to secure a client certificate with hostIdMapping from your security team.

Set to false

If client certificate is not created with hostIdMapping or if you want to define user's role, you must follow the User role manual settings.

Important

If hostIdMapping is not present in the certificate, then common name (CN) of the certificate is picked up as username.

The following is a sample config file to create a certificate having hostIdMapping using OpenSSL:

[ req ]

distinguished_name = req_distinguished_name
policy              = policy_anything
x509_extensions     = v3_req
req_extensions      = v3_req

[ req_distinguished_name ]
countryName                     = Country Name (2 letter code)
countryName_default             = US
countryName_min                 = 2
countryName_max                 = 2
stateOrProvinceName             = State or Province Name (full name) ## Print this message
stateOrProvinceName_default     = United States ## This is the default value
localityName                    = Locality Name (eg, city) ## Print this message
localityName_default            = Houston ## This is the default value
0.organizationName              = Organization Name (eg, company) ## Print this message
0.organizationName_default      = BMC ## This is the default value
organizationalUnitName          = Organizational Unit Name (eg, section) ## Print this message
organizationalUnitName_default = ZOS ## This is the default value
commonName                      = Common Name (eg, your name or your server hostname) ## Print this message
commonName_max                  = 64
emailAddress                    = Email Address ## Print this message
emailAddress_max                = 64

[ policy_anything ]
countryName        = optional
stateOrProvinceName    = optional
localityName        = optional
organizationName    = optional
organizationalUnitName    = optional
commonName        = supplied
emailAddress        = optional

[ user_crt ]
nsCertType              = client, server, email
nsComment               = "OpenSSL Generated Certificate"
subjectKeyIdentifier    = hash
authorityKeyIdentifier = keyid,issuer

[ v3_req ]
basicConstraints        = CA:FALSE
extendedKeyUsage        = serverAuth, clientAuth, codeSigning, emailProtection
keyUsage                = nonRepudiation, digitalSignature, keyEncipherment

#############
1.3.18.0.2.18.1 = critical,ASN1:SET:HostIdMappings

[HostIdMappings]
1 = SEQUENCE:HostIdMapping1

[HostIdMapping1]
1 = IA5STRING:<Hostname>
2 = IA5STRING:<USER-ID>

User role manual settings:

Properties	Description
export APS_CLT_CRT_ROLE=USER	Default role for all client certificates You can use ADMIN, USER, or NONE role as the value.
export APS_CLT_CRT_NONELIST=/ export APS_CLT_CRT_USERLIST=/ export APS_CLT_CRT_ADMINLIST=/	Comma separated CN field value from the certificate for respective role

For more information, see Security section of the BMC AMI Ops Insight documentation.

Creating or obtaining certificates

Use the keytool utility to create a self-signed or acquire a CA-signed certificate for the product.

The keystore will be the same for the following services and servers:

BMC AMI Ops UI Server (Application server)
BMC AMI Ops UI Discovery server (Eureka server)
BMC AMI Ops Insight service
BMC AMI Ops Monitor service (Ops monitor)

To create a self-signed certificate

Run the following command to create a self-signed certificate and add it to the keystore. Make sure that the keytool is in the JAVA_HOME/bin directory. The supported version is Java 17.

Example

keytool -keystore <pathToKeystore> -storepass <keystorePassword> -deststoretype <storeType> -genkeypair -keyalg RSA -validity 180 -alias <aliasName> -dname "CN=localhost" -ext "SAN=DNS:localhost,IP:127.0.0.1,DNS:<hostName>"

Replace the following placeholders:

<pathToKeystore>
<keystorePassword>
<storeType>
<aliasName>
<hostName>

To acquire a CA certificate

Run the following command to generate a key by using the keytool utility. Make sure the keytool is in the JAVA_HOME\bin directory.
keytool -genkeypair -alias <aliasName> -keypass <keyPassword> -keystore <keystoreName> -storepass <keystorePassword> -validity <numberOfDays> -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -deststoretype <storeType>
Replace the following placeholders:
- <aliasName>
- <keyPassword>
- <keystoreName>
- <keystorePassword>
- <numberOfDays>
- <storeType>
Enter the information for the following prompts:
What is your first and last name? [Unknown]: <fully qualified domain name>

What is the name of your organizational unit? [Unknown]: <company name>

What is the name of your organization? [Unknown]: <organization name>

What is the name of your City or Locality? [Unknown]: <your city>

What is the name of your State or Province? [Unknown]: <your state>

What is the two-letter country code for this unit? [Unknown]: <your 2 letter country code>

Is CN=<FQDN>, OU=<company name>, O=<organization name>, L=<your city>, ST=<your state>, C=<your country> correct? [no]: y
Use the key you generated in the previous step to create a certificate signing request (.csr):
keytool -certreq -alias <aliasName> -file <fileName>.csr -keystore <keystoreFileName> -ext san=dns:<FQDN> -storepass <keystorePassword>
Replace the following placeholders:
- <aliasName>
- <keystoreFileName>
- <FQDN>
- <keystorePassword> —This is the same keystore password as defined in the earlier -storepass <keystorePassword>.
Approach a CA provider with the key and .csr file to obtain a CA certificate.
After you receive the CA certificate, use the following command to create a keystore, using the key and certificate files that you created:
keytool -importcert -alias <aliasName> -file <certificateFileName> -keystore <keystoreFileName> -storetype <storeType> -trustcacerts
Replace the following placeholders:
- <aliasName>
- <certificateFileName>
- <keystoreFileName>
- <storeType>

Where to go from here

To sign in to BMC AMI Ops User Interface and start using its features, see Signing-in-to-BMC-AMI-Ops-User-Interface.

If you are not seeing the data you expect, see Troubleshooting.

Configuring the system for SSL/TLS connections

Before you begin

To set HTTPS connections

Updating client certificate settings

To enable or disable client certificate authentication

To update User role settings when using client certificate

Creating or obtaining certificates

To create a self-signed certificate

To acquire a CA certificate

On this page