Updating the cp-console hostname and certificates in 4.14.0 and onward

Edit online

Update the cp-console hostname and certificates by updating the services configuration.

version 4140 Starting with IBM Cloud Pak® foundational services version 4.14.0, the hostname and TLS certificate are customized through updating the services configuration. For more information, see Services configuration.

version 4130 For more information about updating the cp-console hostname and TLS secret in Continuous Delivery (CD) version 4.13.0 and earlier, see Updating the cp-console hostname and TLS secret in 4.13.0 and earlier.

Note:
  • The IM Operator does not manage the lifetime of the custom certificates that you provide, so you need to manually update and make sure that the certificates are replaced ahead of their expiration or when they are revoked. For more information, see Refreshing certificates.
  • For secure settings on your installation, review and rotate credentials periodically and use strong certificates and passwords.
  • The Red Hat® OpenShift® route (cp-console) domain is defined from the cluster-level ingress, Domain Name System (DNS), and certificate configuration that are managed by OpenShift administrators. If a domain name update is already configured and resolvable within the OpenShift cluster, you can proceed with the following steps to customize the route by specifying it as a custom_hostname value.

Ingress configuration priority

Edit online

Customize the host and certificates that are used for all connections to Identity Management (IM) endpoints and the console. For more information, see Accessing your cluster by using the console.

Multiple settings alter what host is used by the IM workload. This list shows settings from highest to lowest priority:
  1. Set the custom host value with the following process.
  2. Set the cpd route host value by configuring console unification. For more information, see Configuring the unified console.
  3. Use the default cp-console route host.

When you configure for console unification, you typically don't need to complete the following steps. The IBM Cloud Pak® that installs with a unified console, such as IBM Cloud Pak® for Data, normally handles these steps.

Updating the cp-console hostname

Edit online

To update the cp-console hostname, edit the CommonService CR named common-service that is installed in the operator namespace. If a service with the ibm-im-operator name is not present, create it and include the .spec.authentication.config.ingress.hostname property set to the hostname that you want.

The following example shows a CommonService CR that defined a custom hostname: 
apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: cs-operators
spec:
  services:
    - name: ibm-im-operator
      spec:
        authentication:
          config:
            ingress:
              hostname: "custom-console.apps.example.ibm.com"
  operatorNamespace: cs-operators
  servicesNamespace: cs-data
  size: small

The IM Operator attempts to use whatever value is supplied for the hostname in objects that it controls, including ConfigMaps, OIDC client registrations, and Red Hat® OpenShift® Container Platform routes when it is installed on OpenShift Container Platform. Make sure that the hostname value is a name that your Domain Name System (DNS) can resolve both outside and inside the cluster network. If an invalid value is set for the hostname, the readiness of the IM workload is blocked until either a valid value is set or the hostname property is set to "", effectively removing the customization.

Updating the IM ingress certificates

Edit online
Note: You must manually manage any custom certificates that you use to configure IM's Routes. If the certificates need to be rotated, see Refreshing certificates for more details.

To configure IM ingress with custom edge TLS certificates, edit the CommonService CR named common-service that is installed in the operator namespace.

If a service with the ibm-im-operator name is not present, create it and include the .spec.authentication.config.ingress.secret property. Set this property to the name of the secret that contains the custom certificates in the services namespace where the IM workload is installed. This secret must contain the following fields to function properly:
  • Set the tls.crt field to the Privacy Enhanced Mail (PEM)-formatted end-entity certificate.
    • This file contains only the route server certificate. The route server certificate passes the TLS verification for the route hostname.
    • The Subject Alternative Names (SANs) on this certificate must match IM's hostname to pass TLS verification. Do not include the certificate chain in this field.
  • Set the tls.key field to the PEM-formatted TLS key.
    • This file contains the private key of the route server certificate. See the following example of PEM encoding that uses header and footer lines for each certificate and private key.
  • Set the ca.crt field to the PEM-formatted chain of CA certificates. Including the root CA certificate is optional.
    • If the ca.crt field consists of more than one certificate to complete the certificate chain as shown in the following example, each following certificate must directly certify the one preceding it. The last certificate is either from the last intermediate CA or, if the root CA certificate is included, from the root CA.
The following example shows what the pre-encapsulation and post-encapsulation boundaries look like for a chain of PEM-encoded certificates: 
-----BEGIN CERTIFICATE-----
(encoded set of characters)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(encoded set of characters)
-----END CERTIFICATE-----
The following example shows what the pre-encapsulation and post-encapsulation boundaries look like for PEM-encoded keys: 
-----BEGIN PRIVATE KEY-----
(encoded set of characters)
-----END PRIVATE KEY-----
To create this secret from the command line, run the following command. The SERVICES_NS value is the operand namespace where the platform-auth-service pod runs, and custom-tls-secret is the name that you want to use for the secret. Make sure that the tls.crt, tls.key, and ca.crt files are in the current working directory. 
oc create secret generic custom-tls-secret -n $SERVICES_NS --from-file=ca.crt=./ca.crt --from-file=tls.crt=./tls.crt --from-file=tls.key=./tls.key
After the secret is created, label it with the following command so that the IM Operator can update the IM workload in response to events that involve the secret: 
oc label secret $SECRET_NAME -n $SERVICES_NS app.kubernetes.io/part-of=im
The following example shows a CommonService CR that defined custom certificates: 
apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: cs-operators
spec:
  services:
    - name: ibm-im-operator
      spec:
        authentication:
          config:
            ingress:
              secret: "custom-tls-secret"
  operatorNamespace: cs-operators
  servicesNamespace: cs-data
  size: small

Reverting a certificate or hostname customization

Edit online

To revert either a certificate or hostname customization in IM to its default value, edit the CommonService CR that is named common-service in the operator namespace. Locate the ibm-im-operator service in the list of services in the .spec.services section.

  • The default certificate is the OpenShift wildcard certificate for the appsDomain. To revert to the default certificate, set the ibm-im-operator service's .spec.authentication.config.ingress.secret property to "".
  • Similarly, to revert to the default cp-console hostname, set the ibm-im-operator service's .spec.authentication.config.ingress.hostname property to "".
The following example shows a CommonService CR with default values: 
apiVersion: operator.ibm.com/v3
kind: CommonService
metadata:
  name: common-service
  namespace: cs-operators
spec:
  services:
    - name: ibm-im-operator
      spec:
        authentication:
          config:
            ingress:
              secret: ""
              hostname: ""
  operatorNamespace: cs-operators
  servicesNamespace: cs-data
  size: small

Refreshing certificates

Edit online
version 4170 For foundational services version 4.17.0 and later, after a secret is created, label it with the following command so that the IM Operator can update the IM workload in response to events that involve that secret.
  • In the following command, replace the SECRET_NAME value with the name of the secret.
  • Replace the SERVICES_NS value with the services namespace.
oc label secret $SECRET_NAME -n $SERVICES_NS app.kubernetes.io/part-of=im
version 4160 For foundational services version 4.16.0 and earlier, the IM Operator does not manage the lifetime of the custom certificates that you provide, so you need to manually update and make sure that the certificates are replaced ahead of their expiration or when they are revoked. Refresh certificates in one of the following ways:
  • Create a secret with the CLI command in Updating the IM ingress certificates and change the value of the .spec.authentication.config.ingress.secret property to contain the new secret name.
  • Update the existing secret to contain the new certificates. Edit the existing secret and replace the tls.crt, ca.crt, and tls.key fields with the updated certificates and key.
    • If you update the secret that is used to customize IM certificates, delete the ibm-iam-operator pods so that the IM Operator can process the updates. To delete the IM Operator pods, run the following command, where OPERATOR_NS is the IM Operator namespace: 
      oc delete po -l name=ibm-iam-operator -n $OPERATOR_NS

Updating SAML IdP configurations

Edit online

If you update the hostname or the self-signed certificate with a custom certificate, also update this information in the identity provider (IdP) configuration so that SAML authentication works smoothly.

version 4170 The following instructions apply to foundational services versions after 4.16.0:

  1. After you update the hostname or custom certificate, log in to the CPD console or cp-console as the default admin user.
  2. Enable automatic propagation of certificate changes for SAML. Use the custom ingress certificate for SAML authentication and enable automatic propagation of certificate changes to the IM workload, including Route updates.
    1. Add the app.kubernetes.io/part-of=im label to your certificate secret so that the IM Operator behaves in the following ways:
      • The IM Operator automatically uses the custom certificate for SAML authentication and removes the default SAML certificate.
      • The IM Operator watches for changes to the secret and automatically updates the relevant IM resources.
      • The IM Operator eliminates the need for manual pod restarts and patch commands, which were required in foundational services version 4.16.0 and earlier.
    2. Before you run the following command, replace the SECRET_NAME value with the name of the secret and the SERVICES_NS value with the services namespace: 
      oc label secret $SECRET_NAME app.kubernetes.io/part-of=im -n $SERVICES_NS

      After you add the label, wait for the platform-* pods to restart automatically. The IM Operator detects the label change and triggers the necessary updates.

  3. Log in to the CPD console or cp-console as the default admin user.
  4. Go to the IdP dashboard, a Zen console, or the cp-console.
  5. Select the SAML configuration by right-clicking the 3 vertical dots, Open and close list of options, and selecting Edit connection.
  6. Download the service provider metadata.
  7. View the downloaded service provider metadata and make sure that the entityID tag on the metadata xml file reflects the updated cp-console hostname.
  8. Cancel the Edited SAML configuration.
  9. Send the service provider metadata to the IdP admin and ask the admin to update the corresponding SAML enterprise application with the latest service provider metadata.
  10. After you receive confirmation from the IdP admin, you can authenticate with the SAML provider.

version 4160 The following instructions apply to foundational services versions 4.16.0 and earlier:

  1. After you update the custom certificate, run the following patch command to update the authService.routerCertSecret value to the custom-tls-secret secret that you created for the cp-console route certificates, also called the custom endpoint certificates. This command restarts the platform-auth-service, platform-identity-management, and platform-identity-provider pods to mount the custom-tls-secret secret. 
    oc patch authentication.operator.ibm.com example-authentication --type='json' -p='[{"op": "replace", "path": "/spec/authService/routerCertSecret", "value":"custom-tls-secret"}]'
  2. Wait for the rollout of the IM deployment pods to complete. Then, run the following command and make sure that the platform-* pods are re-created. After the command runs, check that you see READY and the Running status. 
    oc get pod | egrep "platform-auth-service|platform-identity-management|platform-identity-provider|AGE"
  3. Log in to the CPD console or cp-console as the default admin user.
  4. Go to the IdP dashboard, a Zen console, or the cp-console.
  5. Select the SAML configuration by right-clicking the 3 vertical dots, Open and close list of options, and selecting Edit connection.
  6. Download the service provider metadata.
  7. View the downloaded service provider metadata and make sure that the entityID tag on the metadata xml file reflects the updated cp-console hostname.
  8. Cancel the Edited SAML configuration.
  9. Send the service provider metadata to the IdP admin and ask the admin to update the corresponding SAML enterprise application with the latest service provider metadata.
  10. After you receive confirmation from the IdP admin, you can authenticate with the SAML provider.

Updating OIDC IdP configurations

Edit online

Send the updated uniform resource identifier (URI) to the IdP admin to authenticate by using the OIDC provider.

  1. After you update the hostname, send the updated URI to the IdP admin. The following example shows a valid redirect URI. For a unified console, use the oc get routes -n command to get the latest CPD console or cp-console URL. 
    https://<updated CPD or cp-console URL>/ibm/api/social-login/redirect/<OIDC connection name>
  2. Make sure that the IdP admin updated the latest valid redirect URL on the IdP OIDC configuration. After you receive confirmation from the IdP admin, you can authenticate by using the OIDC provider.