Installing IBM Guardium Cryptography Manager 2.0.1.0 with internal OpenID Connect

You can install IBM® Guardium® Cryptography Manager 2.0.1.0 with internal OpenID Connect by using Helm.

Before you begin

Before you start installing Guardium Cryptography Manager, ensure that you have the following prerequisites.

System requirements and prerequisites
Load balancer requirements
Registration for a Red Hat subscription
Helm with version 3.x
For successful connectivity and operation of the deployed application, ensure that the following ports are explicitly allowed in your firewall or network access rules:
- TCP Port of the OIDC server.
- TCP Port 31443 for IAG host.
TCP Port 31443 and TCP Port of the OIDC server should be open for inbound and outbound traffic from the relevant client or integration systems, depending on your deployment topology. Ensure that the rules allow access from the required IP address ranges or systems as required by your internal security policies.

If you are using an external database with either CA-signed internal OIDC or a self-signed internal OIDC, perform the following steps:

Create Secure Sockets Layer (SSL) certificate secrets.

Run the following commands to create Kubernetes secrets for PostgreSQL databases in the gcmapp namespace:

kubectl create secret generic postgres-external-cert \
--from-file=tls.crt=<postgres-cert-name> \
--namespace="gcmapp" \
--dry-run=client -o yaml | kubectl apply -f -

Note: Ensure that you configure the namespace.

Run the following commands to create Kubernetes secrets for MongoDB databases in the gcmapp namespace:

kubectl create secret generic mongo-external-cert \
--from-file=tls.crt=<mongodb-cert-name> \
--namespace="gcmapp" \
--dry-run=client -o yaml | kubectl apply -f -

If you are using custom database usernames or passwords, run the following commands to create PostgreSQL certificate secret:

kubectl create secret generic "gcm-postgres-secret" \
--namespace="gcmapp" \
--from-literal=DB_USER=<db-user> \
--from-literal=DB_PASSWORD=<db-password> \
--dry-run=client -o yaml | kubectl apply -f -

If you are using custom database usernames or passwords, run the following commands to create MongoDB certificate secret:

kubectl create secret generic "gcm-mongodb-secret" \
--namespace="gcmapp" \
--from-literal=MONGO_DB_USERNAME=<db-user> \
--from-literal=MONGO_DB_PASSWORD=<db-password> \
--dry-run=client -o yaml | kubectl apply -f -

About this task

You can install the Guardium Cryptography Manager application with internal OpenID Connect through Helm on a single-node or multi-node Kubernetes cluster or on a multi-node OpenShift Container Platform (OCP) cluster.

Procedure

Download the gcm-2.0.1.tgz file that contains the Helm charts from IBM Passport Advantage® .
Run the following commands to extract the .tgz file that contains Helm files:
```
tar -xzvf gcm-2.0.1.tgz
```
The gcm-2.0.1.tgz is extracted into the helm-charts folder.

Edit the fields in the global-values.yaml file:

Note: If you require a Disaster Recovery (DR) setup, only then configure the DR hostname and DR IP address.

global:
  # Specify the container orchestration platform: 'ocp' (OpenShift Container Platform) or 'k8s' (Kubernetes)
  platform: <platform>
  node:
    # Kubernetes: Hostname or fully qualified domain name (FQDN) of the master node
    # OpenShift: Route DNS for the OpenShift cluster (use double quotes, e.g., "*.apps.final.cp.example.com")
    name: <name>
    # Kubernetes: IP address of the master node (required only if NOT using a LoadBalancer node)
    # OpenShift: Leave this field empty
    ip:
    # Disaster Recovery: Set to 'true' only for DR recovery setup
    dr_enabled: false
    # OPTIONAL: Required only for Disaster Recovery setup
    # Kubernetes: Hostname or FQDN of the DR master node
    # OpenShift: Route DNS for the DR OpenShift cluster (use double quotes, e.g., "*.apps.final.cp.example.com")
    dr_name:
  app:
    # Application access address
    # Kubernetes: Use the same IP as above with port 31443, e.g., x.x.x.x:31443
    # OpenShift: Use hostname format <app_name>.<route_dns> (must match the route DNS from 'name' above)
    #            Example: gcmapp.apps.final.cp.example.com (port not required for hostname)
    host: <app-host>
  oidcServer:
    # Set to 'true' if using an external OpenID Connect (OIDC) server for authentication; otherwise 'false'
    externalOidc: false
    # OIDC server address (hostname required even if externalOidc = false)
    # External OIDC: Specify as <IP>:<Port> (e.g., x.x.x.x:8443) or provide hostname
    # Internal OIDC:
    #   - Kubernetes: Use the same IP as above with port 30443, e.g., x.x.x.x:30443
    #   - OpenShift: Use hostname format <oidc_name>.<route_dns> (must match the route DNS from 'name' above)
    #                Example: oidc.apps.final.cp.example.com
    host: <oidc-host>
    # The following values are required only when using an external OIDC server
    # Refresh token used to retrieve access token for tenant creation
    refreshToken:
    # URL for introspecting and validating OIDC tokens
    introspectEndpoint:
    # URL for the OIDC token endpoint (used to retrieve access token for UserInfo)
    tokenEndpoint:
    # URL for the OIDC UserInfo endpoint (retrieves authenticated user details)
    userInfoEndpoint:
    # URL for the OIDC discovery endpoint (retrieves OIDC configuration metadata)
    discoveryEndpoint:
    # URL for OIDC authorization requests (user redirect endpoint)
    authorizationEndpoint:
    # Unique session field name in the access token granted by OIDC
    uniqueTokenAttributeName: jti
    # Email field name in the access token granted by OIDC
    emailTokenAttributeName: email
    # Security realm or domain associated with your OIDC provider (if applicable)
    realm:
    # Required scope for GCM tenant creation - ensure this scope is added to your OIDC server
    # DO NOT MODIFY this scope
    gcmScope: "gcm_tenant_creation"
    # Enable ('true') or disable ('false') user verification against the OIDC server during authentication
    usersOidcVerification: false
  oidc:
    # Default username for OIDC authentication to the application
    # When using an external OIDC server, update the values below
    userName: gcmadmin
    # First name of the admin user created during OIDC setup
    firstName: gcm
    # Last name of the admin user created during OIDC setup
    lastName: admin
    # Email address associated with the admin user
    emailId: gcmadmin@gcm.local
  kmip:
    # OpenShift only: KMIP host in format <kmip_name>.<route_dns>
    # Example: kmip.apps.final.cp.example.com
    host: <kmip-host>
  # Seed string for Disaster Recovery: 32 or 64 characters using 0-9, A-F, or a-f
  GCM_SEED: ""
  vault:
    # Vault integration - PKI secret engine common name
    commonName: "CLM"
  gcmApp:
    # User ID for GCM application administrative or API access
    # When using an external OIDC server, use the same email address as the admin user
    userId: gcmadmin@gcm.local
    # Organization name that owns this application deployment
    tenantName: IBM
  image:
    # Base container registry repository path
    repository: icr.io/guardium-cryptomgr
    # Deployment environment: dev, pre-prod, or prod
    environment: prod
  # Kubernetes namespace where application components will be deployed
  # DO NOT CHANGE these values
  namespace:
    app: gcmapp
    dbs: gcmapp
  # Middleware components: endpoint and port configuration
  postgres:
    externalPostgres: false
    endpoint: gcm-edb-postgres-rw
    port: 5432
    dbName: gem_postgres
    hosts: gcm-edb-postgres-rw:5432
    targetServerType: primary
  kafka:
    endpoint: gcm-kafka-kafka-bootstrap
    port: 9092
  mongodb:
    externalMongoDB: false
    endpoint: gcm-mongodb-svc
    port: 27017
    dbName: tenant_manager
    hosts: gcm-mongodb-0.gcm-mongodb-svc:27017,gcm-mongodb-1.gcm-mongodb-svc:27017,gcm-mongodb-2.gcm-mongodb-svc:27017
    readPreference: primary
  redis:
    redisEnabled: false
    port: 6380
    endpoint: gcm-redis-redis-master-svc
  persistence:
    app:
      storageClassEnabled: true
      # StorageClass for application persistent volumes (e.g., rook-cephfs for Ceph file storage)
      # Set to 'true' if the rook-cephfs StorageClass is available on your cluster
      storageClass: rook-cephfs
      # Persistent storage volume size for application data
      # Increase this value at installation time based on your requirements
      size: 25Gi
    dbs:
      storageClassEnabled: true
      # StorageClass for database persistent volumes (e.g., rook-ceph-block for block storage)
      # Set to 'true' if the rook-ceph-block StorageClass is available on your cluster
      storageClass: rook-ceph-block
  # Images are hosted in a public Container Registry namespace - no authentication required
  # DO NOT MODIFY this value
  imagePullSecrets:
    name: icr-secret
  # ============================================================================
  # SIZING MODEL CONFIGURATION
  # ============================================================================
  # Centralized sizing tier configuration for all services
  # Available tiers: trial, small, large
  #   - trial: 1 replica for GCM services + 1 replica for middlewares
  #   - small: 2 replicas for GCM services + 3 replicas for middlewares
  #   - large: 3 replicas for GCM services + 3 replicas for middlewares
  #
  # Set the desired sizing tier for your deployment environment
  sizingModel: small  # Options: trial, small, large

Refer the following table to update the global values:

Table 1. Global values for installation
Key	Description	Example value	Mandatory or Optional
global.platform	Defines the container orchestration platform Kubernetes value: `k8s` OCP value: `ocp`	`ocp` or `k8s`	Mandatory
global.dr_enabled	Set the `dr_enabled` value to `true` only for DR recovery.	`true` or `false`	Optional (required only for DR setup)
global.dr_name	OPTIONAL: Required only for Disaster Recovery setup. Hostname or fully qualified domain name used only for DR setup. Kubernetes value: Provide the master node’s hostname or Fully Qualified Domain Name FQDN). OCP value: Provide the cluster route's Domain Name System (DNS). Note: Always put the value within double quotes (for example, "*.apps.final.cp.example.com").	`"*.apps.final.cp.example.com"`	Optional (required only for DR setup)
global.node.name	Cluster-level identifier Kubernetes value: FQDN or hostname of the master node OCP value: Route DNS for the OpenShift cluster within quotes (`" "`)	`master-node01` or `"*.apps.final.cp.example.com"`	Mandatory
global.node.ip	IP address to access the network Kubernetes value: IP address of the master node (This is required only if you are not using a LoadBalancer node) OCP value: Leave this field empty	`x.x.x.x`	Optional
global.app.host	The address or hostname used to access the Guardium Cryptography Manager application Kubernetes value: Use the same IP as `node.ip` with port `31443` OCP value: Provide hostname in the format `<app_name>.<route_dns>`	`x.x.x.x:31443` or `gcmapp.apps.final.cp.example.com`	Mandatory
global.oidcServer.externalOidc	External OIDC (k8s) value: `true` (set to true only if using external OIDC server for authentication. Otherwise, update as false.) Internal OIDC (OCP) value: `false`	`false`	Mandatory
global.oidcServer.host	OIDC server hostname or IP address:Port. External OIDC: Specify IP:Port or hostname. Internal OIDC (k8s): Use same `node.ip` with port `30443`. Internal OIDC (ocp): Provide the hostname in the format <oidc_name>.<route_dns>	`x.x.x.x:30443` or `oidc.apps.final.cp.example.com`	Mandatory
global.oidcServer.refreshToken	Refresh token used to retrieve access token during tenant creation (only if external OIDC is enabled). Use refresh token instead of username and password for authenticating of the user and for getting the access token to create tenants.	`<token>`	Optional (Provide if global.oidcServer.externalOidc is set true)
global.oidcServer.introspectEndpoint	Endpoit to validate OIDC token (Provide this values only if external OIDC is enabled)	`https://oidc-server/introspect` or `https://oidc.apps.final.cp.example.com/introspect`	Optional (Provide if global.oidcServer.externalOidc is set true)
global.oidcServer.tokenEndpoint	Token endpoint URL	`https://oidc-server/token` or `https:/oidc.apps.final.cp.example.com/token`	Optional (Provide if global.oidcServer.externalOidc is set true)
global.oidcServer.userInfoEndpoint	Endpoint to retrieve user information. While adding user list to Guardium Cryptography Manager, create the `oidc-user-secret` to verify if the user list exists or not. (only if External OIDC is enabled)	`https://oidc-server/userinfo` or `https://oidc.apps.final.cp.example.com/userinfo`	Optional (Provide if global.oidcServer.externalOidc is set true)
global.oidcServer.discoveryEndpoint	Metadata URL for OIDC configuration — required only when external OIDC integration is enabled.	`https://oidc-server/.well-known/openid-configuration` or `https://oidc.apps.final.cp.example.com/.well-known/openid-configuration`	Optional (Provide if global.oidcServer.externalOidc is set true)
global.oidcServer.authorizationEndpoint	OIDC authorization redirect endpoint - required only when external OIDC integration is enabled	`https://oidc-server/authorize` or `https://oidc.apps.final.cp.example.com/authorize`	Optional (Provide if global.oidcServer.externalOidc is set true)
global.oidcServer.realm	Security realm or domain (if applicable)	`master` or `realm01`	Optional (Provide if global.oidcServer.externalOidc is set true)
global.oidcServer.gcmScope	OIDC scope specific to Guardium Cryptography Manager. Do not modify.	`"gcm_tenant_creation"`	Mandatory
global.oidcServer.usersOidcVerification	Enable or disable user verification against OIDC server	`false`	Optional
global.oidc.userName	Default username for OIDC authentication	`gcmadmin`	Mandatory
global.oidc.firstName	Administrator user’s first name	`gcm`	Mandatory
global.oidc.lastName	Administrator user’s last name	`admin`	Mandatory
global.oidc.emailId	Administrator user’s email	`gcmadmin@gcm.local`	Mandatory
global.kmip.host	Openshift only . Keep empty for k8sKMIP service hostname. Openshift - format should be `<kmip_name>.<route_dns>.K8s`- Keep it empty	`kmip.apps.final.cp.example.com`	Mandatory
global.gcmApp.userId	User ID or e-mail used for API or administrator access. When external OIDC is enabled, specify the same email address as the OIDC admin user.	`gcmadmin@gcm.local`	Mandatory
global.gcmApp.tenantName	Tenant or organization name	`IBM`	Mandatory
global.image.repository	Image repository location. Do not modify.	`icr.io/guardium-cryptomgr`	Mandatory
global.image.environment	Image environment location. Do not modify.	`prod`	Mandatory
global.namespace.app	Namespace for application components	`gcmapp`	Mandatory
global.namespace.db	Namespace for database components	`gcmapp`	Mandatory
global.postgres.externalPostgres	Flag to enable or disable the use of an external PostgreSQL database. Set to true when using an external database; otherwise, set to false	`true` - for external database false - for internal databse	Mandatory
global.postgres.endpoint, global.postgres.port, global.postgres.dbName global.postgres.hosts global.postgres.targetServerType	Provide endpoint, port, dbName, hosts, and targetServerType only when global.postgres.externalPostgres=true; if set to false, leave all these fields unchanged as the internal database configuration is used.	endpoint: gcm-edb-postgres-rw port: 5432 dbName: gem_postgres hosts: gcm-edb-postgres-rw:5432 targetServerType: primary	Mandatory
global.kafka.endpoint and global.kafka.port	Kafka broker and port (Do not modify)	`endpoint: gcm-kafka-kafka-bootstrap` `port: 9092`	Mandatory
global.mongodb.externalMongoDB	Enables external MongoDB integration. Use true for external DB; keep false for internal DB.	`false`
global.mongodb.endpoint, global.mongodb.port, global.mongodb.dbName, global.mongodb.hosts and global.mongodb.readPreference	MongoDB connection details. Provide endpoint, port, dbName, hosts, and readPreference only when global.mongodb.externalMongoDB=true; if set to false, leave all these fields unchanged as the internal database configuration is used.	`endpoint: gcm-mongodb-svc` `port: 27017` `dbName: tenant_manager` `hosts: gcm-mongodb-0.gcm-mongodb-svc:27017,gcm-mongodb-1.gcm-mongodb-svc:27017,gcm-mongodb-2.gcm-mongodb-svc:27017` `readPreference: primary`	Mandatory
global.redis.endpoint and global.redis.port	Redis cache endpoint (Do not modify)	`port: 6380` `endpoint: gcm-redis-redis-master-svc`	Mandatory
global.persistence.app.storageClassEnabled	Enable custom StorageClass for application data.	`true`	Mandatory
global.persistence.app.storageClass	StorageClass name (Ceph FS)	`rook-cephfs`	Mandatory
global.persistence.app.size	Persistent Volume Claim (PVC) size for app data	`25Gi`	Mandatory
global.persistence.dbs.storageClassEnabled	Enable custom StorageClass for databases	`true`	Mandatory
global.persistence.dbs.storageClass	StorageClass for databases (block storage)	`rook-ceph-block`	Mandatory
global.imagePullSecrets.name	Name of secret to pull container images. Do not modify.	`icr-secret`	Mandatory
global.sizingModel	The sizing tier for your deployment environment.	`trial` `small` `large`	Mandatory

Specify the number of pod replicas per microservice. By default specify the value of replica per service as 1. You can scale replicas for higher availability.

If you are deploying Helm for the first time or if you are deploying Helm into a fresh or cleaned-up cluster, run the following command as a root user:

cd helm-charts
./installer.sh

After you run the command, on the prompt to select Install, Upgrade, Uninstall, or Exit, enter 1.

Prompt to select installation or upgrade options — Figure 1. Selecting installation or upgrade options

Output of installation script to prompt acceptance of license — Figure 2. Accepting license after prompt

The installation script checks for all required prerequisites at first. If any prerequisites are missing, it installs them system-wide in/usr/local/bin (including Helm, kubectl, oc, and yq). The script also creates the necessary secrets and proceeds to install all required services. After the installation of the services, you can verify that the containers are running successfully.

Prompt to add administrator password — Figure 3. Creating administrator password

When you are installing for the first time, provide the value of the Guardium Cryptography Manager administrator password and then enter the password again for confirmation. This value should not be empty or more than 256 characters.

If your environment does not allow root user access, you must install these tools manually before using the Helm chart.

Table 2. Prerequisite tools for Helm chart
Tool name	Required Version	Download Link	Verification Command
Helm	3.13.x	https://helm.sh/docs/intro/install/	`helm version`
kubectl	1.33 or 1.34	Install kubectl	`kubectl version --client`
YQ CLI	Most recent version	https://github.com/mikefarah/yq/releases	`yq --version`

Results

After installing Guardium Cryptography Manager 2.0.1.0, perform the following validations:

Validate the deployment of by doing these steps:
1. Run the following command to check the Helm releases:
```
helm ls --namespace gcmapp
```
2. Run the following command to verify pods:
```
kubectl get pods --namespace gcmapp
```
3. Run the following command to check the logs of pods:
```
kubectl logs -f <pod-name> --namespace gcmapp
```
Validate OIDC server access, log in using either of the following URLs with username as gcmadmin and password as gcmsecret, and then verify that the gcmadmin exists:
- Use https://<ip-address>:<OIDC server port> for Kubernetes cluster
- Use https://<route-url> for OCP cluster
Log in by using the following credentials:
- Username: gcmadmin
- Password: gcmsecret

What to do next

After installing Guardium Cryptography Manager 2.0.1.0, complete the following tasks:

Open the Guardium Cryptography Manager application by using either of the following URLs:
- If the Guardium Cryptography Manager application is installed in a Kubernetes cluster, use the URL, https://<ip_address>:31443
- If the Guardium Cryptography Manager application is installed in an OCP cluster, use the URL, https://<route_url>
Log in to the Guardium Cryptography Manager user interface by using the following credentials:
- Username: gcmadmin
- Password: <password>
Note: Use the same password that you had configured during the installation process.
You can reset gcmadmin user password. See Troubleshooting installation and uninstallation .
On the Guardium Cryptography Manager, click Help>About>Version, and verify that the version is as required.