Using custom keys and certificates for deploying IBM Telco Network Cloud Manager - Orchestration

The resources of IBM® Telco Network Cloud Manager - Orchestration are protected by an authentication layer in place on the gateway, that is, Ishtar. To gain access to any of these protected resources, an authorization process takes place. As a minimum, this authorization requires providing some valid client credentials (client ID and secret) which are normally deemed as sufficient security.

  • By default, the Vault service is used as a certificate authority for generating and managing certificates and keys in IBM Telco Network Cloud Manager - Orchestration.
  • During initialization of the Vault service, a root and intermediate certificate authority are set up and root.cer and intermediate.cer certificate files are generated and stored in a Kubernetes secret named alm-certs.
  • The job alm-configurator generates internal signed certificates for all services and adds them to Java™ keystore file (keystore.p12), which is available in the Kubernetes secret alm-keystore.
  • The Nimrod(User Interface) and Ishtar(API Gateway) components have a security layer that is enabled and which protects their APIs.
  • Ishtar acts as an Oauth2 provider and can provide tokens (JWT format) which enable authorization against the protected APIs. To authenticate, it is necessary to provide a secret in a token request to Ishtar for the Ishtar clientId (Admin).
  • JWT access tokens that are given out by Ishtar contain a list of roles that the user has. The token is signed by using the jwtSigningKey to avoid tampering, which is a private key.
  • Nimrod requires its own client (NimrodClient) to communicate with backend APIs through Ishtar. When the user logs in through the UI, the username and password (from LDAP) are combined with Nimrod's client credentials to make a token request against Ishtar. A token is then supplied, which the UI can use to make backend calls until its expiry.
  • Doki also requires its own client (DokiClient). This is so that it can provide access control against the backend calls, which are made while running behavior scenarios.
  • Generally, the Admin clientId is used and it enables access to APIs in a protected way.
  • client-credentials-bootstrap.yml is a yaml file that holds details of each of the clientCredentials and is made available to Ishtar through a Kubernetes secret and passed at installation time. The default name for this secret is alm-credentials-default.

These specific keys and certificates are provided in the form of Kubernetes secrets and made available to the system. By default, the secrets alm-certs and alm-keystore are automatically generated during the deployment.

Using custom keys and certificates

It is also possible to supply certificates from an existing certificate authority to be used with IBM Telco Network Cloud Manager - Orchestration.

Two options are available for using custom certificates:

  1. Use an external Root certificate authority. In this case, only an intermediate CA is set up in Vault. The internal service certificates are generated in IBM Telco Network Cloud Manager - Orchestration by the alm-configurator job at installation time. For more information, see Option 1: Using an existing Root Certificate Authority - Generate internal certificates.
  2. No root or intermediate certificate authority is set up in Vault and all internal certificates for the services must be supplied. For more information, see Option 2: Using an existing Root Certificate Authority - No certificates generated.

In either case, you need to change the vault.certAuthority section in the tnco cr YAML configuration file you are using to create the instance. Sample IBM Telco Network Cloud Manager - Orchestration custom resources are available in the cr directory of the package. The following list shows the default values for Vault. Some of these values are referenced in the following procedures.

  vault:    
    certAuthority:      
      setupRootCA: true
      generateCertificates: true      
      rootCAName: "TNCO-Internal-Root-CA"
      rootLeaseTime: "87600h"
      intermediateCAName: "TNCO-Internal-Intermediate-CA"
      intermediateLeaseTime: "43800h"
      certTTL: "43800h"  # used for internal and external roles
      extTopLevelDomain: "alm"
      externalCASecret: "external-ca"

Option 1: Using an existing Root Certificate Authority - Generate internal certificates

Use an external Root Certificate Authority. In this case, only an intermediate certificate authority is set up in Vault. Certificates are generated for all services.

Ensure to set vault.certAuthority.setupRootCA to false in the Custom Resource Definition file for the IBM Telco Network Cloud Manager - Orchestration operator installation.

To support this option, the following files must be provided at installation time in a Kubernetes secret called external-ca (name is configurable in cr by: vault.certAuthority.externalCASecret):

File Description
root.cer Public certificate for the external root CA
intermediate.cer Signed (by root CA) certificate for intermediate CA
intermediate.key Private key for intermediate CA

To add files to a secret, run:

oc create secret generic external-ca \
 --from-file=root.cer \
 --from-file=intermediate.cer \
 --from-file=intermediate.key

Follow the installation procedure as normal, for more information, see Installing IBM Telco Network Cloud Manager - Orchestration.

Option 2: Using an existing Root Certificate Authority - No certificates generated

In this case, all internal certificates for all services must be supplied. No Root or Intermediate certificate authority is set up in the vault service.

Ensure to set the following property values to false in the Custom Resource Definition file for the IBM Telco Network Cloud Manager - Orchestration operator installation:

  • vault.certAuthority.setupRootCA
  • vault.certAuthority.generateCertificates

To support this option, the following file must be provided at installation time in a Kubernetes secret called external-ca (name is configurable in cr by: vault.certAuthority.externalCASecret):

File Description
root.cer Public certificate for the external root CA

To add these to a secret, run:

oc create secret generic external-ca \
 --from-file=root.cer

In addition to the root certificate, a Java keystore that is named keystore.p12 must be created containing certificates for all of the internal services. This keystore along with its password must be stored in the Kubernetes secret alm-keystore.

An example script is provided in the TNC-O archive package: scripts/certs/createSecrets.sh. This example script uses openssl and keytool and can be used to generate the certificates and secret alm-keystore. You are also free to use any other tool.

Certificates must be generated and placed in the keystore for the following services with the same corresponding alias name: apollo brent conductor daytona doki galileo ishtar nimrod relay talledega watchtower.

If the keystore.p12 file is prepared elsewhere without the script, then to create up the alm-keystore secret, run:

oc create secret generic alm-keystore \
 --from-file keystore.p12 \
 --from-literal=keystorePassword=<keystord_password>

Follow the installation procedure as normal, for more information, see Installing IBM Telco Network Cloud Manager - Orchestration.