Managing domain and certificates

IBM Security QRadar® Suite Software provides support actions to assist you in managing certificates. You can also change your QRadar Suite Software domain, and the foundational services route.

Updating your QRadar Suite Software TLS certificates

QRadar Suite Software provides the set_cert action to the TLS certificates that are used to secure in-flight communication in the cluster when it expires or to update the existing certificates.

Before you begin

Install the command-line interface (CLI) utility cpctl from the cp-serviceability pod. For more information, see Installing the cpctl utility.

For more information about certificate requirements, see Domain name and TLS certificates.

About this task

Important: Do not run the set_cert action if your QRadar Suite Software platform uses the same TLS certificate that your Red Hat OpenShift Container Platform cluster uses. If you need to update the TLS certificate for QRadar Suite Software in that case, see Synchronizing QRadar Suite Software Certificates with the cluster certificate.

Procedure

  1. Log in to your Red Hat OpenShift Container Platform cluster as a cluster administrator by typing one of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
    • Using a username and password.
      oc login <openshift_url> -u <cluster_admin_user> -p <cluster_admin_password>
    • Using a token.
      oc login --token=<token> --server=<openshift_url>
  2. To make sure that the list of available cpctl actions is up to date, enter the following command. 
    cpctl load
    The cpctl load command retrieves all of the available actions that can be run on QRadar Suite Software. The actions are cached to your local environment.
  3. Update your QRadar Suite Software TLS certificates by running the set_cert action.

    The following table details the parameters that are required to run the command.

    Parameter Description
    --key New TLS key
    --cert New TLS certificate
    --authority Certificate of the signing certificate authority
    --token The Red Hat OpenShift admin token.
    Note: The certificate authority certificate is required only if your new certificate is self-signed or signed by an unknown certificate authority.
    cpctl tools update_cert --token "$(oc whoami -t)"
    Well-known certificate authority example
    Your TLS certificate key is in a file called tls.key. Your TLS certificate is in a file that is called tls.crt. A well-known authority signs your certificate. Run the following command and insert the values that are stored in the files.
    cpctl tools set_cert --key "$(cat tls.key)" --cert "$(cat tls.crt)" --token "$(oc whoami -t)"
    Unknown certificate authority example
    Your TLS certificate key is in a file that is called tls.key. Your TLS certificate is in a file that is called tls.crt. An unknown authority signs your certificate. The CA certificate is stored in a file that is called ca.crt. Run the following command and insert the values that are stored in the files.
    cpctl tools set_cert --key "$(cat tls.key)" --cert "$(cat tls.crt)" --token "$(oc whoami -t)" --ca "$(cat ca.crt)"
    Domain change example
    When the QRadar Suite Software domain is changed, change the certificate and domain parameters at the same time. Run the following command and insert the values that are stored in the files.
    cpctl tools set_cert --domain <New QRadar Suite Domain> --key "$(cat tls.key)" --cert "$(cat tls.crt)" --token "$(oc whoami -t)"

What to do next

Replace the foundational services endpoint certificate. For more information, see Replacing the foundational services endpoint certificate.

Synchronizing QRadar Suite Software Certificates with the cluster certificate

If your QRadar Suite Software platform uses the same TLS certificate as your Red Hat OpenShift Container Platform cluster and the TLS certificate is changed, run the sync_cluster_cert action to synchronize the TLS certificate with QRadar Suite Software.

About this task

Important: Do not run the sync_cluster_cert action if your QRadar Suite Software platform uses a different TLS certificate than your Red Hat OpenShift Container Platform cluster uses. If you need to update the TLS certificate for QRadar Suite Software in that case, see Updating your QRadar Suite Software TLS certificates.

Install the command-line interface (CLI) utility cpctl from the cp-serviceability pod. For more information, see Installing the cpctl utility.

Procedure

  1. Log in to your Red Hat OpenShift Container Platform cluster as a cluster administrator by typing one of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
    • Using a username and password.
      oc login <openshift_url> -u <cluster_admin_user> -p <cluster_admin_password>
    • Using a token.
      oc login --token=<token> --server=<openshift_url>
  2. To make sure that the list of available cpctl actions is up to date, enter the following command. 
    cpctl load
    The cpctl load command retrieves all of the available actions that can be run on QRadar Suite Software. The actions are cached to your local environment.
  3. To run the sync_cluster_cert action, enter the following command. 
    cpctl tools sync_cluster_cert --token $(oc whoami -t)

Results

The QRadar Suite Software application pods restart in the Red Hat OpenShift cluster and the TLS certificate is synchronized.

What to do next

Replace the foundational services endpoint certificate. For more information, see Replacing the foundational services endpoint certificate.

Checking QRadar Suite Software and foundational services certificates

The QRadar Suite Software certificate is used to access QRadar Suite Software services. The IBM foundational services certificate is used by QRadar Suite Software to access IBM foundational services IAM. QRadar Suite Software provides an action to validate these certificates.

About this task

Install the command-line interface (CLI) utility cpctl from the cp-serviceability pod. For more information, see Installing the cpctl utility.

Procedure

  1. Log in to your Red Hat OpenShift Container Platform cluster as a cluster administrator by typing one of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
    • Using a username and password.
      oc login <openshift_url> -u <cluster_admin_user> -p <cluster_admin_password>
    • Using a token.
      oc login --token=<token> --server=<openshift_url>
  2. To make sure that the list of available cpctl actions is up to date, enter the following command. 
    cpctl load
    The cpctl load command retrieves all of the available actions that can be run on QRadar Suite Software. The actions are cached to your local environment.
  3. Run the check_cert action by typing the following command. 
    cpctl diagnostics check_cert --token $(oc whoami -t)

Example

The following output is a sample output of what might display after you run the command.

Get CP4S Route...
  localhost ok
Check CP4S Route...
Get IBM Foundational Services Route...
  localhost done
Check IBM Foundational Services Route...
Ensure temp dir exists...
  localhost done
Fetch CP4S truststore...
  localhost done
Test CP4S ingress...
  localhost done
Print CP4S Certificate when failed...
Stop if CP4S Certificate is not valid...
Test IBM Foundational Services Ingress...
  localhost ok
Print IBM Foundational Services Certificate when failed...
Stop if IBM Foundational Services Certificate is not valid...
Certificates are valid...

- Play recap -
  localhost                  : ok=8    changed=5    unreachable=0    failed=0    rescued=0    ignored=0

What to do next

If the output from the command shows the certificates are invalid, you can replace the certificates. For more information, see Updating your QRadar Suite Software TLS certificates.

Changing your QRadar Suite Software domain

To change your QRadar Suite Software fully qualified domain name (FQDN), update the domain value in the cp4sthreatmanagement custom resource (CR), and update the TLS certificates.

Before you begin

Install the command-line interface (CLI) utility cpctl from the cp-serviceability pod. For more information, see Installing the cpctl utility.

For more information about domain name requirements, see Domain name and TLS certificates.

Procedure

  1. Log in to your Red Hat OpenShift Container Platform cluster as a cluster administrator by typing one of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
    • Using a username and password.
      oc login <openshift_url> -u <cluster_admin_user> -p <cluster_admin_password>
    • Using a token.
      oc login --token=<token> --server=<openshift_url>
  2. To make sure that the list of available cpctl actions is up to date, enter the following command. 
    cpctl load
    The cpctl load command retrieves all of the available actions that can be run on QRadar Suite Software. The actions are cached to your local environment.
  3. Update the domain value in the cp4sthreatmanagement CR by typing the following command, where <cp4s_namespace> is your QRadar Suite Software namespace, and <FQDN> is your new FQDN. 
    oc patch cp4sthreatmanagements.isc.ibm.com threatmgmt -n <cp4s_namespace> --type merge --patch '{"spec": {"basicDeploymentConfiguration":{"domain": "<FQDN>"}}}'
  4. Verify that the domain value is updated in the cp4s-config map by typing the following command. 
    oc get cm cp4s-config -o jsonpath="{.data.domain}" && echo
  5. Update your QRadar Suite Software TLS certificates by running the set_cert action.

    The following table details the parameters that are required to run the command.

    Parameter Description
    --key New TLS key
    --cert New TLS certificate
    --authority Certificate of the signing certificate authority
    --token The Red Hat OpenShift admin token.
    Note: The certificate authority certificate is required only if your new certificate is self-signed or signed by an unknown certificate authority.
    cpctl tools update_cert --token "$(oc whoami -t)"
    Well-known certificate authority example
    Your TLS certificate key is in a file called tls.key. Your TLS certificate is in a file that is called tls.crt. A well-known authority signs your certificate. Run the following command and insert the values that are stored in the files.
    cpctl tools set_cert --key "$(cat tls.key)" --cert "$(cat tls.crt)" --token "$(oc whoami -t)"
    Unknown certificate authority example
    Your TLS certificate key is in a file that is called tls.key. Your TLS certificate is in a file that is called tls.crt. An unknown authority signs your certificate. The CA certificate is stored in a file that is called ca.crt. Run the following command and insert the values that are stored in the files.
    cpctl tools set_cert --key "$(cat tls.key)" --cert "$(cat tls.crt)" --token "$(oc whoami -t)" --ca "$(cat ca.crt)"
    Domain change example
    When the QRadar Suite Software domain is changed, change the certificate and domain parameters at the same time. Run the following command and insert the values that are stored in the files.
    cpctl tools set_cert --domain <New QRadar Suite Domain> --key "$(cat tls.key)" --cert "$(cat tls.crt)" --token "$(oc whoami -t)"
  6. Reprocess all operators by typing the following command. 
    oc delete iscguard --all
  7. Restart all operators by typing the following command. 
    oc get pod -o name | grep operator | xargs oc delete
  8. Re-create the secrets that are generated by the cases operator by typing the following command. 
    oc delete secrets isc-cases-stomp-default-cert isc-cases-openwire-default-cert isc-cases-rest-default-cert
    The cases secrets are deleted, then the Cases Operator re-creates the secrets with the new domain name.

Updating the foundational services route

Change the IBM Cloud Pak foundational services route to a custom route.

About this task

The foundational services route (cp-console.xxx) that is used by QRadar Suite Software to access the foundational services console uses the QRadar Suite Software cluster domain to create a subdomain called cp-console. QRadar Suite Software uses this subdomain to handle authentication for the foundational services console. The foundational services URL route can be modified to point to a different domain or a different subdomain.

Procedure

  1. Log in to your Red Hat OpenShift Container Platform cluster as a cluster administrator by typing one of the following commands, where <openshift_url> is the URL for your Red Hat OpenShift Container Platform environment.
    • Using a username and password.
      oc login <openshift_url> -u <cluster_admin_user> -p <cluster_admin_password>
    • Using a token.
      oc login --token=<token> --server=<openshift_url>
  2. Set the $CP4S_NAMESPACE environment variable by typing the following command, where <cp4s_namespace> is the namespace where you are installing QRadar Suite Software.
    Important: If you install QRadar Suite Software in the all namespace mode, set the <cp4s_namespace> value as openshift-operators.
    export CP4S_NAMESPACE=<cp4s_namespace>
  3. Set the $FS_NAMESPACE environment variable to your foundational services namespace by typing the following command. 
    export FS_NAMESPACE=$(oc get cm cp4s-config -o jsonpath="{.data.CSNamespace}" -n $CP4S_NAMESPACE)
  4. Update the routeHost in the Managementingress custom resource by typing the following command, where <custom_domain> is the host URL that you plan to use to access foundational services. 
    oc patch -n $FS_NAMESPACE Managementingress default --type merge --patch '{"spec":{"routeHost":"cp-console.<custom_domain>"}}'
  5. Open the registration-json configuration map for editing by typing the command. 
    oc -n $FS_NAMESPACE edit configmap registration-json
  6. Update the following fields with the <custom_domain> URL that you set in step 2 and save your changes to the configuration map. 
    "post_logout_redirect_uris":["https://cp-console.<custom_domain>/console/logout"],
   "preauthorized_scope":"openid profile email general",
   "introspect_tokens":true,
   "trusted_uri_prefixes":["https://cp-console.<custom_domain>"],
   "redirect_uris":["https://cp-console.<custom_domain>/auth/liberty/callback","https://127.0.0.1:443/idauth/oidc/endpoint/OP"]
  7. Apply the changes that you made by typing the following command. 
    oc get job oidc-client-registration -o json -n $FS_NAMESPACE | jq 'del(.spec.selector)' | jq 'del(.spec.template.metadata.labels)' | oc replace --force -f -
  8. Update the ibm-iam-bindinfo-oauth-client-map configuration map with the <custom_domain> URL that you set in step 2 by typing the following command. 
    oc -n $FS_NAMESPACE patch cm oauth-client-map --type merge --patch '{"data":{"CLUSTER_CA_DOMAIN":"cp-console.<custom_domain>","MASTER_IP":"cp-console.<custom_domain>"}}'
  9. Restart the auth pods. 
    oc delete pod -lapp=auth-idp -lapp=auth-pap -lapp=auth-pdp -n $FS_NAMESPACE
  10. Check that you can log in to foundational services with the updated cluster domain.
  11. Update the QRadar Suite Software inventory with the <custom_domain> URL that you set in step 2 by typing the following command, where <cp4s_namespace> is your QRadar Suite Software namespace. 
    oc patch -n <cp4s_namespace> iscinventory iscplatform --type merge --patch '{"spec":{"definitions":{"cluster_hostname":"cp-console.<custom_domain>","oidc":{"authorizationurl":"https://cp-console.apps.<custom_domain>/idprovider/v1/auth/authorize","tenant":"cp-console.<custom_domain>"}}}}'
  12. To run the custom resource sequence for iscplatform,clx,iscprofile, follow the steps in Running Cloud Pak for Security sequence.
  13. Check the status of the custom resource iscsequence iscplatform and confirm that the status is Successful by typing the following command, where <cp4s_namespace> is your QRadar Suite Software namespace. 
    oc get iscsequence iscplatform iscprofile clx -n <cp4s_namespace>

    If the output from this command appears as Running, wait for 10 minutes then check the status again to ensure that it is successful.

  14. On the browser, log in to the support_execute_sequence console and validate that the login redirect URL is pointing to your new foundational services domain URL. You can retrieve the foundational services username and password by using the following commands. 
    oc -n $FS_NAMESPACE get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_username}' | base64 --decode
    oc -n $FS_NAMESPACE get secret platform-auth-idp-credentials -o jsonpath='{.data.admin_password}' | base64 --decode

    Alternatively, you can log in to the foundational services Admin Hub by using your new foundational services domain URL and your foundational services credentials. For more information, see Administration Hub.