2.2. Prepare the client configuration#

Helm reads the client settings from a values file when it installs or updates the SCIM Client. Create a scim-client-values.yaml file before you run the installation commands. Use this file to set the connection details and authentication credentials for your environment. The following sections describe the required settings and selected optional values. The chart’s values.yaml file lists all available settings and their default values. The chart passes the settings to the client container as environment variables. Apply changes to the client settings through Helm, as described in Installation. For a Wire-specific example, see Wire connection example.

To prepare the client configuration, follow these steps:

  1. Configure Mandatory values.

  2. Configure the Database.

  3. Configure the Authentication for the SCIM target.

  4. If you want to override the default settings, configure Optional values.

  5. If you want to limit which users and user groups the client provisions, configure Select users and user groups.

Then add the provisioning subscription configuration to your nubus-values.yaml file.

2.2.1. Mandatory values#

The SCIM Client needs connection details for the services outlined in Prerequisites. Set the following values in your scim-client-values.yaml file:

For authentication with the Provisioning API, set provisioningApi.auth.username to the name of the provisioning subscription. In this procedure, the Helm Chart creates the secret for the provisioning subscription from provisioningApi.auth.password.

For LDAP authentication, provide either ldap.auth.password or ldap.auth.existingSecret.name. By default, the Helm Chart reads the LDAP password from the password key in the existing secret. If the secret uses a different key, set ldap.auth.existingSecret.keyMapping.password to that key.

For authentication with the SCIM target, the authentication method determines the required values. For details, see Authentication for the SCIM target.

Listing 2.1 shows a configuration example with OIDC authentication. Replace the URLs, credentials, database connection details, and LDAP settings with the values for your environment. The LDAP secret must exist in the namespace where you install the SCIM Client.

Listing 2.1 Minimal example of SCIM Client configuration#
scimClient:
  config:
    dbConnectionString: "postgresql+psycopg2://<DATABASE_USERNAME>:<PASSWORD>@<HOSTNAME>/<DATABASE_NAME>"

scimServer:
  connection:
    url: "https://scim.example.com/scim/v2/"
  auth:
    method: "oidc"
    password: "your-client-secret"
    oidc:
      oidcTokenUrl: "https://auth.example.com/realms/nubus/protocol/openid-connect/token"
      clientId: "scim-client"

provisioningApi:
  connection:
    url: "<PROVISIONING_API_URL>"
  auth:
    username: "scim-client"
    password: "your-provisioning-api-password"

ldap:
  connection:
    host: "<LDAP_HOSTNAME>"
  auth:
    bindDn: "<LDAP_BIND_DN>"
    existingSecret:
      name: "<LDAP_SECRET_NAME>"

2.2.2. Database#

The SCIM Client uses PostgreSQL to store provisioning tasks, their processing state, and information about failed tasks. This data supports retries and helps to investigate provisioning errors. For details about inspecting tasks and errors, see Monitor the current state from the command line.

The PostgreSQL database isn’t included in the Helm Chart. You’re responsible for operating the database, including backups and upgrades. The SCIM Client creates its tables on startup.

Set scimClient.config.dbConnectionString to the SQLAlchemy connection URL for the PostgreSQL database. Add this value to your scim-client-values.yaml file, as shown in Listing 2.1.

The connection string uses the following pattern:

postgresql+psycopg2://<DATABASE_USERNAME>:<PASSWORD>@<HOSTNAME>/<DATABASE_NAME>

Replace <DATABASE_USERNAME>, <PASSWORD>, <HOSTNAME>, and <DATABASE_NAME> with the values for your database connection. URL-encode special characters in the database username and password. For details, see Escaping Special Characters in Passwords in the SQLAlchemy documentation.

Warning

Without the connection URL, a Helm installation or upgrade fails. The Helm Chart passes the value to the client through a Secret as PROVISIONING_DB.

2.2.3. Authentication for the SCIM target#

Set scimServer.auth.method to one of the values in Table 2.1.

For all authentication methods except none, the SCIM Client needs a secret value for authentication. Provide it directly through scimServer.auth.password or use an existing Kubernetes secret through scimServer.auth.existingSecret.name.

Important

The value none sends no Authorization header. Use this value only for testing, never in production.

Table 2.1 Authentication methods for the SCIM target#

Value

Use case

Required values

oidc

Use OpenID Connect (OIDC) authentication.

basic

Use HTTP Basic authentication for SCIM targets that don’t support OIDC.

bearer

Use static Bearer token authentication for SCIM targets that don’t support OIDC.

none

Don’t send an Authorization header.

No authentication values required.

When you use an existing secret, it must exist in the namespace where you install the SCIM Client. The Helm Chart reads the entry named password by default. The entry must contain the OIDC client secret for oidc, the password for basic, or the static token for bearer authentication. If your secret uses a different key, set scimServer.auth.existingSecret.keyMapping.password to that key. For example, Listing 2.2 uses a Bearer token stored under the key token in the scim-target-auth secret.

Listing 2.2 Use a Bearer token from an existing Secret#
scimServer:
  auth:
    method: "bearer"
    existingSecret:
      name: scim-target-auth
      keyMapping:
        password: token

2.2.4. Optional values#

You can override the following defaults in your scim-client-values.yaml file. Listing 2.3 shows an example.

scimClient.config.logLevel

The log level for the SCIM Client.

Default value:

INFO

scimClient.config.prefill

Controls whether the provisioning subscription supplies existing user and user group data to the SCIM Client before sending new changes.

Default:

true

scimClient.config.groupSync

Controls whether the SCIM Client provisions user groups. Group provisioning is experimental. For restrictions on group membership synchronization, see Data synchronization.

Default:

false

scimClient.config.externalIdUserMapping

The Univention Directory Manager (UDM) attribute used for the SCIM externalId field of users. For restrictions on group member lookup, see Data synchronization.

Default:

univentionObjectIdentifier

scimClient.config.externalIdGroupMapping

The UDM attribute used for the SCIM externalId field of user groups.

Default:

univentionObjectIdentifier

scimClient.config.usernameMapping

The UDM attribute used for the SCIM userName field.

Default:

username

scimServer.auth.oidc.scopes

Only applies when scimServer.auth.method is oidc. A list of additional scopes to request when obtaining an OIDC access token for SCIM server authentication. The SCIM Client always includes the openid scope automatically. Use this option if the downstream SCIM server requires specific scopes in the access token.

Default:

null, which means that the SCIM Client doesn’t use any additional scopes.

Listing 2.3 Example of optional SCIM Client configuration#
scimClient:
  config:
    logLevel: "DEBUG"
    prefill: false
    groupSync: false
    externalIdUserMapping: "customUserId"
    externalIdGroupMapping: "customGroupId"

scimServer:
  auth:
    oidc:
      scopes:
        - "additionalScope1"
        - "additionalScope2"

2.2.5. Select users and user groups#

By default, the client provisions all users received through its subscription. Set scimClient.config.groupSync to true to also provision user groups. The default value false excludes user groups. For restrictions on group membership synchronization, see Data synchronization.

To provision only selected users or user groups, you can filter them by an existing boolean UDM property. For example, if your deployment provides isNextcloudUser, you can use it to select users for the target application. The client provisions users whose isNextcloudUser property is true.

The client reads the property names from the environment variables SCIM_USER_FILTER_ATTRIBUTE for users and SCIM_GROUP_FILTER_ATTRIBUTE for user groups. The Helm Chart has no dedicated filter settings, so add the variables through scimClient.extraEnvVars in scim-client-values.yaml.

Listing 2.4 sets these variables to the property names isNextcloudUser and isKMGroup. The client doesn’t create these properties. Replace the example names with properties provided by your integration.

Use boolean values for the UDM properties on the individual objects. A non-empty string such as "false" also selects an object.

Listing 2.4 Select users and user groups through Boolean UDM properties#
scimClient:
  config:
    groupSync: true
  extraEnvVars:
    - name: SCIM_USER_FILTER_ATTRIBUTE
      value: isNextcloudUser
    - name: SCIM_GROUP_FILTER_ATTRIBUTE
      value: isKMGroup

Warning

When a configured property becomes false or is removed, the client deletes the matching object from the SCIM target if it already exists there. The same applies if the property is already false or missing when the client first processes the object. Deletion happens when the client processes the object’s provisioning event.