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:
Configure Mandatory values.
Configure the Database.
Configure the Authentication for the SCIM target.
If you want to override the default settings, configure Optional values.
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:
scimServer.connection.url: The URL of the SCIM target.provisioningApi.connection.url: The URL of the Provisioning API.ldap.connection.host: The hostname of the LDAP Server.ldap.auth.bindDn: The bind DN for the LDAP Server.scimClient.config.dbConnectionString: The connection URL for the PostgreSQL database.
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.
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.
Value |
Use case |
Required values |
|---|---|---|
|
Use OpenID Connect (OIDC) authentication. |
|
|
Use HTTP Basic authentication for SCIM targets that don’t support OIDC. |
|
|
Use static Bearer token authentication for SCIM targets that don’t support OIDC. |
|
|
Don’t send an |
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.
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.logLevelThe log level for the SCIM Client.
- Default value:
INFO
scimClient.config.prefillControls whether the provisioning subscription supplies existing user and user group data to the SCIM Client before sending new changes.
- Default:
true
scimClient.config.groupSyncControls whether the SCIM Client provisions user groups. Group provisioning is experimental. For restrictions on group membership synchronization, see Data synchronization.
- Default:
false
scimClient.config.externalIdUserMappingThe Univention Directory Manager (UDM) attribute used for the SCIM
externalIdfield of users. For restrictions on group member lookup, see Data synchronization.- Default:
univentionObjectIdentifier
scimClient.config.externalIdGroupMappingThe UDM attribute used for the SCIM
externalIdfield of user groups.- Default:
univentionObjectIdentifier
scimClient.config.usernameMappingThe UDM attribute used for the SCIM
userNamefield.- Default:
username
scimServer.auth.oidc.scopesOnly applies when
scimServer.auth.methodisoidc. A list of additional scopes to request when obtaining an OIDC access token for SCIM server authentication. The SCIM Client always includes theopenidscope 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.
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.
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.