Configuring User Management Services

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

Before you begin

You must have created the UMS resources, as described in Preparing to install the User Management Services.

For more information about the settings, see User Management Services parameters.

Procedure

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.

Edit the ums_configuration section of the CR file that you created in Generating the custom resource or if you did it manually by using the Manually compiling 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 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 # derby (for test), db2, oracle
    dc_ums_oauth_host: <dbhost>
    dc_ums_oauth_port: 50000
    dc_ums_oauth_name: UMSDB
    dc_ums_oauth_schema: <OAuthDBSchema>
    dc_ums_oauth_driverfiles:
    dc_ums_oauth_alternate_hosts: "server1.db2.company.com, server2.db2.company.com"
    dc_ums_oauth_alternate_ports: "50443, 51443"
    # teamserver database config
    dc_ums_teamserver_type: db2 # derby (for test), db2, oracle
    dc_ums_teamserver_host: <dbhost>
    dc_ums_teamserver_port: 50000
    dc_ums_teamserver_name: UMSTSDB
    dc_ums_teamserver_driverfiles:
    dc_ums_teamserver_alternate_hosts: "server1.db2.company.com, server2.db2.company.com"
    dc_ums_teamserver_alternate_ports: "50443, 51443"

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_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_schema: DB_user_ID
      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.

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-7.4.1.jre8.jar
      dc_ums_oauth_ssl: false
    # 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-7.4.1.jre8.jar
      dc_ums_oauth_ssl: false

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.14.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.14.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 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 must specify the secrets that contains a TLS certificate that represents the host names of the routes that your clients connect to.
```
ums_configuration:
  existing_claim_name:
  service_type: Route
  hostname: <ums-host>
  replica_count: 2
  port: 443
  images:
    ums:
      repository: cp.icr.io/cp/cp4a/ums/ums
      tag: 20.0.3
  admin_secret_name: ibm-dba-ums-secret
  # 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
```

New in 20.0.3 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 and profileserver
    #### 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"

New in 20.0.3 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.

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_jdbc_drivers: false
    use_custom_binaries: false  
    existing_claim_name:
    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"