Configuring User Management Services

User Management Services configuration settings are stored in the shared custom resource (CR) file for operator deployment.

About this task

You must provide details for configuration settings that you want, including things that you have already created, like the names of your persistent volume claims, secrets, and data sources that you created previously during Preparing to install the User Management Services. For more information about the settings, see User Management Services parameters.

Procedure

Edit the ums_configuration section of the CR file that you created in Generating the custom resource.
Specify the name of the UMS database admin secret that you created for the ums_configuration.admin_secret_name during , for example ibm-dba-ums-secret.

Specify the UMS datasource settings for your database in the datasource_configuration section of the custom resource.

For example:

For Db2®:

datasource_configuration:
  dc_ums_datasource: # credentials are read from ums_configuration.admin_secret_name
    # oauth database config
    dc_ums_oauth_type: db2
    dc_ums_oauth_host: host_name
    dc_ums_oauth_port: 50000
    dc_ums_oauth_name: UMSDB
    dc_ums_oauth_schema: OAuth_DB_Schema
    dc_ums_oauth_driverfiles: db2jcc4.jar, db2jcc_license_cu.jar
    dc_ums_oauth_alternate_hosts: "server1.db2.example.com, server2.db2.example.com"
    dc_ums_oauth_alternate_ports: "50443, 51443"
    dc_ums_oauth_ssl: true
    # teamserver database config
    dc_ums_teamserver_type: db2
    dc_ums_teamserver_host: host_name
    dc_ums_teamserver_port: 50000
    dc_ums_teamserver_name: UMSTSDB
    dc_ums_teamserver_driverfiles: db2jcc4.jar, db2jcc_license_cu.jar
    dc_ums_teamserver_alternate_hosts: "server1.db2.example.com, server2.db2.example.com"
    dc_ums_teamserver_alternate_ports: "50443, 51443"
    dc_ums_teamserver_ssl: true

If you created a secret for the Db2 certificate to secure communications between UMS and Db2, specify the name of the secret, and enable SSL, for example:

datasource_configuration:
  dc_ums_datasource: 
    ...
    dc_ums_oauth_ssl_secret_name: ibm-dba-ums-db2-cacert
    dc_ums_oauth_ssl: true
    ...
    dc_ums_teamserver_ssl_secret_name: ibm-dba-ums-db2-cacert
    dc_ums_teamserver_ssl: true

For Oracle:

  datasource_configuration:
    dc_ums_datasource: # credentials are read from ums_configuration.admin_secret_name
    # oauth database config
      dc_ums_oauth_type: oracle
      dc_ums_oauth_host: host_name
      dc_ums_oauth_port: 1521
      dc_ums_oauth_name: SID
      dc_ums_oauth_schema: DB_user_ID
      dc_ums_oauth_oracle_service_name: DB_service_name
      dc_ums_oauth_ssl: false
      dc_ums_oauth_driverfiles: ojdbc8.jar, orai18n.jar
    # teamserver database config
      dc_ums_teamserver_type: oracle
      dc_ums_teamserver_host: host_name
      dc_ums_teamserver_port: 1521
      dc_ums_teamserver_name: SID
      dc_ums_teamserver_oracle_service_name: DB_service_name
      dc_ums_teamserver_ssl: false
      dc_ums_teamserver_driverfiles: ojdbc8.jar, orai18n.jar

Where host_name is the name of your database host, SID is the SID of your database, for example UMSDB, DB_user_ID is your database user ID, for example C##UMS.

Important: For Oracle RAC, specify the host name of the SCAN listener as the value of the dc_ums_oauth_host and dc_ums_teamserver_host parameters.

If you created a secret for the Oracle certificate to secure communications between UMS and Oracle, specify the name of the secret, and enable SSL, for example:

datasource_configuration:
  dc_ums_datasource: 
    ...
    dc_ums_oauth_ssl_secret_name: ibm-dba-ums-oracle-cacert
    dc_ums_oauth_ssl: true
    ...
    dc_ums_teamserver_ssl_secret_name: ibm-dba-ums-oracle-cacert
    dc_ums_teamserver_ssl: true

For MS SQL:

datasource_configuration:
    dc_ums_datasource: # credentials are read from ums_configuration.admin_secret_name
    # oauth database config
      dc_ums_oauth_type: sqlserver
      dc_ums_oauth_host: host_name
      dc_ums_oauth_port: 1433
      dc_ums_oauth_name: UMSDB
      dc_ums_oauth_driverfiles: mssql-jdbc-8.2.2.jre8.jar
      dc_ums_oauth_ssl: true
    # teamserver database config
      dc_ums_teamserver_type: sqlserver
      dc_ums_teamserver_host: host_name
      dc_ums_teamserver_port: 1433
      dc_ums_teamserver_name: UMSDB
      dc_ums_teamserver_driverfiles: mssql-jdbc-8.2.2.jre8.jar
      dc_ums_teamserver_ssl: true

Where host_name is the name of your database host, 1433 is the port number, UMSDB is the name of your database.

If you created a secret for the MS SQL certificate to secure communications between UMS and MS SQL, specify the name of the secret, and enable SSL, for example, ibm-dba-ums-mssql-cert:

datasource_configuration:
  dc_ums_datasource: 
    ...
    dc_ums_oauth_ssl_secret_name: ibm-dba-ums-mssql-cert
    dc_ums_oauth_ssl: true
    ...
    dc_ums_teamserver_ssl_secret_name: ibm-dba-ums-mssql-cert
    dc_ums_teamserver_ssl: true

For PostgreSQL:

  datasource_configuration:
    dc_ums_datasource: # credentials are read from ums_configuration.admin_secret_name
      # oauth database config
      dc_ums_oauth_type: postgresql
      dc_ums_oauth_host: host_name
      dc_ums_oauth_port: 5432
      dc_ums_oauth_name: umsdb
      dc_ums_oauth_driverfiles: postgresql-42.2.9.jar

      # teamserver database config
      dc_ums_teamserver_type: postgresql
      dc_ums_teamserver_host: host_name
      dc_ums_teamserver_port: 5432
      dc_ums_teamserver_name: umsdb
      dc_ums_teamserver_driverfiles: postgresql-42.2.9.jar

Where host_name is the name of your database host and umsdb is the name of your database.

If you created a secret for the PostgreSQL certificate to secure communications between UMS and PostgreSQL, specify the name of the secret, and enable SSL, for example, ibm-dba-ums-postgresql-cacert:

datasource_configuration:
  dc_ums_datasource: 
    ...
    dc_ums_oauth_ssl_secret_name: ibm-dba-ums-postgresql-cacert
    dc_ums_oauth_ssl: true
    ...
    dc_ums_teamserver_ssl_secret_name: ibm-dba-ums-postgresql-cacert
    dc_ums_teamserver_ssl: true

Important: If you configured PostgreSQL for high availability following the Patroni architecture with an HAproxy for load balancing, make sure that you specify the host name and port number of the HAproxy as the values for

dc_ums_oauth_host and
dc_ums_teamserver_host

and

dc_ums_oauth_port and
dc_ums_teamserver_port

Important: If you do not have a separate teams database, UMSTSDB, specify identical values for the dc_ums_teamserver_ parameters as for the dc_ums_oauth_ ones.

Trouble: If you plan to use UMS integration with other capabilities, you might encounter registration failure errors during deployment. This can happen if the UMS deployment is not ready by the time the other containers come up. The situation resolves in the next operator loop, so the errors can be ignored.

Specify the certificates and routing for secure communications with UMS.
1. If you are creating a test environment and you do not want to deal with certificates, you do not need the following secrets, and should remove them from the custom resource:
  - external_tls_secret_name
  - external_tls_ca_secret_name
  - external_tls_teams_secret
  - external_tls_sso_secret
  - external_tls_scim_secret
  This causes the root_ca_secret to be used to generate an internal TLS secret for all services and an external TLS secret for each of the routes ums-route, ums-sso-route, ums-scim-route, and ums-teams-route.
  If you do not specify a root signing CA in the shared_configuration section of the custom resource, root_ca_secret is generated by the operator with a self-signed root CA.
2. If you are creating a production environment, you can perform one of the following options:
  - Specify the secrets that contains a TLS certificate that represents the host names of the routes that your clients connect to.
  - Use the shared secret shared_configuration.external_tls_certificate_secret that contains a single HTTPS wildcard certificate that can be used to secure all routes. For more information, see Providing certificates for external routes.
3. If you upgraded from a version earlier than 21.0.2 and you have existing secrets that contain host names, they will not conform to the new host name convention, if you do not want to regenerate the secrets, you can set backwards_compatibility_routes to true to use the old host naming pattern.
```
ums_configuration:
  hostname: <ums-host>
  admin_secret_name: ibm-dba-ums-secret
  # optional: create routes for backwards compatibility
  backwards_compatibility_routes: false
  # optional for secure communication with UMS
  external_tls_secret_name: ibm-dba-ums-external-tls-secret
  # optional for secure communication with UMS 
  external_tls_ca_secret_name: ibm-dba-ums-external-tls-ca-secret
  # optional for secure communication with UMS 
  external_tls_teams_secret_name: ibm-dba-ums-external-tls-teams-secret
  # optional for secure communication with UMS 
  external_tls_scim_secret_name: ibm-dba-ums-external-tls-scim-secret
  # optional for secure communication with UMS 
  external_tls_sso_secret_name: ibm-dba-ums-external-tls-sso-secret
```

Decide whether you want each UMS service (UMS SSO, UMS Teams, UMS SCIM-based Users and Groups) to run in its own dedicated pod so that they can scale individually, which is the default. or whether you want all UMS services to run in a single pod.

Perform one of the following:

For dedicated pods:

In the section ums_configuration set
```
  dedicated_pods: true
```

For the UMS SSO service, default values are specified for the replica_count, resource, autoscaling and logs parameters. You can change the values if the default values do not meet your requirements.

    # Configuration for sso pods
    sso:
      replica_count: 2
      resources:
        limits:
          cpu: 500m
          memory: 512Mi
        requests:
          cpu: 200m
          memory: 256Mi
        autoscaling:
          enabled: true
          minReplicas: 2
          maxReplicas: 5
          targetAverageUtilization: 98
      custom_xml:
      logs:
        traceSpecification: "*=info"

For the UMS SCIM-based Users and Groups service, default values are specified for the replica_count, resource, autoscaling and logs parameters. You can change the values if the default values do not meet your requirements.

    # configuration for scim pods
    scim:
      replica_count: 2
      resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 200m
        memory: 256Mi
      autoscaling:
        enabled: true
        minReplicas: 2
        maxReplicas: 5
        targetAverageUtilization: 98
      custom_xml:
      logs:
        traceSpecification: "*=info"

For the UMS Teams service, default values are specified for the replica_count, resource, autoscaling and logs parameters. You can change the values if the default values do not meet your requirements.

    # configuration for teamserver pods
    teamserver:
      replica_count: 2
      resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 200m
        memory: 256Mi
      autoscaling:
        enabled: true
        minReplicas: 2
        maxReplicas: 5
        targetAverageUtilization: 98
      custom_xml:
      logs:
        traceSpecification: "*=info"

To have all UMS services run in the same pod, set the value

dedicated_pods:
false

Default values are specified for the replica_count, resource, autoscaling and logs parameters. You can change the values if the default values do not meet your requirements.

    #### If dedicated_pods is set to false, the UMS capabilities sso, scim, teamserver
    #### run in the same pods with this configuration.
    replica_count: 2
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 200m
        memory: 256Mi
    autoscaling:
      enabled: true
      min_replicas: 2
      max_replicas: 5
      target_average_utilization: 98
    custom_xml:
    logs:
      traceSpecification: "*=info"

If you want to change the database connection pool sizes, health parameters, or certificate checking options, you can modify the settings that are described in UMS advanced parameters by using the custom_xml section.
If you are using an Oracle, MS SQL, or PostgreSQL database, specify the following in the ums_configuration:
```
  use_custom_jdbc_drivers: true
  existing_claim_name: operator-shared-pv
```
Where operator-shared-pv is the Persistent Volume Claim that you prepared for the operator.

Customize any other UMS configuration settings as necessary to suit your requirements. For example, in the sections oauth, resources, autoscaling, or logs:

  oauth:
    # optional: full DN of an LDAP group that is authorized to manage OIDC clients, in addition to primary admin from admin secret
    client_manager_group:
    # optional: full DN of an LDAP group that is authorized to manage app_tokens, in addition to primary admin from admin secret
    token_manager_group:
    # optional: lifetime of OAuth access_tokens. default is 7200s
    access_token_lifetime:
    # optional: lifetime of app-tokens. default is 366d
    app_token_lifetime:
    # optional: lifetime of app-passwords. default is 366d
    app_password_lifetime:
    # optional: maximimum number of app-tokens or app-passwords per client. default is 100
    app_token_or_password_limit:
    # optional: encoding / encryption when sotring client secrets in OAuth database. Default is xor for compatibility. Recommended value is PBKDF2WithHmacSHA512
    client_secret_encoding:
    use_custom_binaries: false  
    service_type: Route
    routes_ingress_annotations:
	
  resources:
    limits:
      cpu: 500m
      memory: 512Mi
    requests:
      cpu: 200m
      memory: 256Mi
  ## Horizontal Pod Autoscaler
  autoscaling:
    enabled: true
    min_replicas: 2
    max_replicas: 5
    target_average_utilization: 98
  use_custom_jdbc_drivers: false
  use_custom_binaries: false
  custom_secret_name:
  custom_xml:
  logs:
    console_format: json
    console_log_level: INFO
    console_source: message,trace,accessLog,ffdc,audit
    trace_format: ENHANCED
    trace_specification: "*=info"

By default, Cloud Pak for Business Automation uses IBM® Cloud Platform Common Services Identity Access Management (IAM) .
If IAM was not installed using a default configuration, apply the following parameters so that IAM is detected automatically on the cluster:
```
ums_configuration:
  iam:
    delegation_enabled: true
    namespace: "ibm-common-services"
```
Important: If you are deploying on a platform that is not OpenShift Container Platform, the authentication delegation to IAM is automatically disabled.
Specify an LDAP group that is authorized to administer UMS Teams by adapting the following snippet, where UMSTeamsAdmins is the name of the UMS Teams administration group:
```
ums_configuration:
  teamserver:
    admingroup: 'cn=UMSTeamsAdmins,dc=example,dc=org'
```
Remember: After deployment, you can administer teams for your business needs by logging onto the UMS Teams Management UI at https://ums_host/teamserver/ui using a user ID that is in the UMS Teams administration group.