Import from external IAM

7.2. Import from external IAM#

This section describes the Nubus Directory Importer and how you use it to run a complete import on the entirety of user accounts from a subtree in an external IAM system. It describes the general steps to connect external IAM systems and single sign-on through the protocols SAML and OpenID Connect to Univention Nubus. The setup is for a unidirectional import of directory objects, such as user accounts and user groups.

If you need all user accounts from a subtree in an external IAM system in the Directory Service of Nubus for Kubernetes, and also want to regularly transfer user updates from your external IAM system, this section and the Nubus Directory Importer is for you.

If you only need those user accounts that actually use the system, or if you want to save time on the import procedure, or if you don’t care about modifications to user accounts in your external IAM system after the initial import, then the federation between the Identity Provider in Nubus with an external IAM system is for you. Refer to Federation with external IAM systems.

For your understanding, this how-to uses the following definitions:

Source IAM system: is the external IAM system that has directory objects designated for import to Nubus. Nubus can use it as source for user account objects, user group objects, and as identity provider for user sign-in.
Target: The target of the import is the Identity Provider component in Nubus for Kubernetes.

The connection uses the following processes:

Import: During import, the connector reads user account objects and user group objects through LDAP from the source and the target, calculates the differences and adds them to the target using the UDM HTTP REST API from the Directory Manager in Univention Nubus.
Single sign-on: For single sign-on, Nubus uses the external IAM system as SAML Identity Provider or as OpenID Connect Relying Party. The Identity Provider from Univention Nubus becomes a client to the external IAM system.

See also

Nubus Directory Importer in the functional components section: in Univention Nubus for Kubernetes - Architecture Manual [2] for information about the architecture of the Nubus Directory Importer.

7.2.1. Prerequisites#

Before you begin, you need to fulfill the following requirements:

The source must provide access to user account objects and user group objects through LDAP.
The source must provide an identity provider that supports the protocols SAML or OpenID Connect.
You have a running instance of Univention Nubus for Kubernetes. For installation, see Deployment.
For the synchronization of user accounts and user groups between the source and the target you need the Nubus Directory Importer.
The Nubus for Kubernetes environment needs appropriate amounts of memory and disk space.

Memory
Appropriate amounts of memory needed for the following pods:

ldap-primary:

nubusLdapServer.resourcesPrimary.limits.memory

ldap-secondary:

nubusLdapServer.resourcesSecondary.limits.memory

provisioning-listener:

nubusUdmListener.resources.limits.memory

udm-rest-api:

nubusUdmRestApi.resources.limits.memory

Disk space
Appropriate amounts of disk space needed for the following pods:

ldap-primary:

nubusLdapServer.persistence.size

ldap-secondary:

nubusLdapServer.persistence.size
Before you set up the Nubus Directory Importer, you must complete the following prerequisites.
Service accounts
1. The source system requires a service account with the permissions in the respective subtree to search and read all user objects and user group objects.
2. The target system Nubus for Kubernetes needs a service account with the permission to write user account objects and user group objects to the respective OU and the permission to use the UDM HTTP REST API.
  
  For information about authentication groups, Authorization groups in Univention Nubus for Kubernetes - Nubus Customization and Modification Manual [6].
Network
The Nubus Directory Importer:
- Must reach the UDM HTTP REST API in the Directory Manager component in Univention Nubus for Kubernetes on port 443/tcp.
- Must reach the source system. The port depends on the source system and typically is 636/tcp.
- Doesn’t need inbound connections.
Encrypted connections with TLS
The Nubus Directory Importer sends clear text passwords to authenticate with the source and target through LDAP. You need to ensure that all source and target systems have properly configured encrypted connections through TLS. An encrypted connection is especially important, if the Nubus Directory Importer runs on a different network than the Kubernetes cluster with the UDM HTTP REST API.

For Nubus for Kubernetes being the target system, the TLS configuration is already in place in the default setup. For the URL of the API, see Connection setup for UDM HTTP REST API.
Note

The Nubus Directory Importer doesn’t read and synchronize user account passwords, or their hashes from the directories.

To complete the setup and allow the synchronized user accounts to authenticate, you need to Setup single sign-on.

7.2.2. Connection setup for UDM HTTP REST API#

To import user accounts and user groups to Nubus for Kubernetes, you use the UDM HTTP REST API. This section describes how you connect to it. For the Nubus Directory Importer you need the following sections:

For the URL to the API, API location.
For authentication, Authentication.

See also

UDM HTTP REST API: in Univention Nubus for Kubernetes - Nubus Customization and Modification Manual [6] for information about the UDM HTTP REST API.

7.2.3. Nubus Directory Importer installation#

Nubus Directory Importer is an application, that searches for user account objects and user group objects in the source and the target through LDAP. It synchronizes the found objects to the Directory Manager in Nubus through the UDM HTTP REST API.

Nubus Directory Importer reads both source and target directory services and determines the differences as a basis for the modification. The connector doesn’t store local states.

The synchronization process writes the complete OU structure of the source directory service to a dedicated OU in the target directory service, meaning Nubus. The connector uses the preconfigured UDM property univentionObjectIdentifier as primary key in the target system to identify user objects and user group objects.

Note

Renaming a group, that references a nested group, may require two runs of Nubus Directory Importer to update the entries on the target system.

See also

Nubus Directory Importer: for information on the architecture of the Nubus Directory Importer in Univention Nubus for Kubernetes - Architecture Manual [2].

The Nubus Directory Importer is available as container image. You can deploy it either in Docker with the help of Docker Compose, or in Kubernetes using the Helm Chart. This section covers both methods.

For either installation method, use the following preparation steps:

On your local machine, create a directory for the configuration of the Nubus Directory Importer, for example nubus-directory-importer.
Depending on your preferred installation method for the Nubus Directory Importer, continue with either one of the following sections:
- Docker Compose
- Helm Chart and Kubernetes

Tip

The example configuration is for using a Microsoft Active Directory as external IAM system. For other external IAM products, adjust the file accordingly.

See also

Git Repository for Nubus Directory Importer: for more information about the importer.

7.2.3.1. Docker Compose#

This section describes how to run Nubus Directory Importer through Docker Compose. Describing installation and setup of Docker Compose is beyond the scope of this documentation.

To run Nubus Directory Importer through Docker Compose, continue after the steps outlined in Nubus Directory Importer installation and use the following steps:

Inside the directory for the importer, create the config directory to save the configuration.
Download ad-domain-config.yaml.example from the project repository. In your local project directory, create the config directory. Move and rename the example configuration file to config/ad-domain-config.yaml.
Download the docker-compose.yml file from the project repository and save it to your local project directory.
For a TLS configuration with custom certificates, see TLS in Nubus Directory Importer.
To start the importer, run the command in Listing 7.1.
Listing 7.1 Run the Nubus Directory Importer with Docker Compose#
```
$ docker compose up --detach
```

7.2.3.2. Helm Chart and Kubernetes#

This section describes how to install Nubus Directory Importer to a Kubernetes cluster through Helm with a Helm Chart.

To install Nubus Directory Importer through a Helm Chart, continue after the steps outlined in Nubus Directory Importer installation and use the following steps:

Download the tilt-values.yaml file, rename it to custom-values.yaml and save it to your local project directory. The file is a minimal example.

The settings below configFile correspond to the available values described at Configuration of Nubus Directory Importer.

Install Nubus Directory Importer with the command in Listing 7.2.

Listing 7.2 Install Nubus Directory Importer through Helm Chart#

$ export YOUR_DESIRED_NAMESPACE="Your preferred namespace for the importer"
$ helm upgrade \
    --namespace "$YOUR_DESIRED_NAMESPACE" \
    --version "$VERSION_IMPORTER" \
    --values custom_values.yaml \
    oci://artifacts.software-univention.de/nubus-dev/charts/directory-importer

See also

For a complete reference of the Helm Chart values of the Nubus Directory Importer, see the Helm Chart README file and the values.yaml file:

7.2.3.3. TLS in Nubus Directory Importer#

For secure connections between Nubus Directory Importer and the source and the target IAM systems, the strong recommendation is to use TLS.

Important

The following steps are only necessary, if the certificates in the source or the target system aren’t signed by a well-known public certificate authority, such as Let’s Encrypt.

Docker Compose

To provide the custom CA certificate in the Docker Compose setup, use the following steps:

For the connection to the external IAM system, save the CA certificate to the config/ca_ad.crt file in your project directory.
For the connection to Nubus, save the CA certificate to the config/ca-nubus.crt file in your project directory.
In your docker-compose.yml, remove the comments from the respective lines in the services.directory-importer.volumes section that mount the certificates for the Nubus Directory Importer.

Helm Chart and Kubernetes

To provide the custom CA certificate in the Kubernetes setup, use the following steps:

For the connection to the external IAM system, create a secret that contains the CA certificate of the external IAM system.
Optional: If you additionally want to secure the connection to Nubus inside the Kubernetes cluster, create a secret that contains the CA certificate of Nubus.

Add the secrets references and mount points to your custom_values.yaml file as shown in Listing 7.3.

Listing 7.3 Add CA certificates to values file#

configFile:
  source:
    ca_cert: "/etc/ssl/certs/ca-certificates-ad.crt"
  # Optional
  udm:
    ca_cert: "/etc/ssl/certs/ca-certificates-nubus.crt"
extraVolumes:
  - name: "certificates"
    secret:
      secretName: "Your custom secret name of CA certificate for external IAM system"
  # Optional
  - name: "nubus-certificates"
    secret:
      secretName: "Your custom secret name of CA certificate for Nubus"
extraVolumeMounts:
  - name: "certificates"
    mountPath: "/etc/ssl/certs/ca-certifcates-ad.crt"
  # Optional
  - name: "nubus-certificates"
    mountPath: "/etc/ssl/certs/ca-certificates-nubus.crt"

7.2.4. Configuration of Nubus Directory Importer#

For the configuration of the Nubus Directory Importer, you use a text file in YAML format. At the top-level hierarchy it has the following configuration dictionaries:

udm:: Configuration parameters that define the connection to UDM.
source:: Configuration parameters that define the connection to the source and rules for transformation.

7.2.4.1. Example configuration#

You find a configuration example in the repository of the Nubus Directory Importer, see ad-domain-config.yaml.example.

7.2.4.2. Configuration reference#

This section provides a reference for the configuration values of the Nubus Directory Importer.

7.2.4.2.1. Section: `udm`#

udm.uri#: URI including base path for accessing UDM HTTP REST API.

udm.user#: Username used for authenticating to UDM.

udm.password#: User password used for authenticating to UDM.

udm.ca_cert(optional)#: Path of the trusted CA certificate bundle file. Defaults to your platform-specific CA bundle file.

udm.skip_writes(optional)#: If true, skip write operations to UDM. Default: false.

udm.connect_timeout(optional)#: Timeout in seconds to wait for connection to UDM. Default: 6.0 seconds.

udm.read_timeout(optional)#: Timeout in seconds to wait for UDM results. Default: 1800 seconds.

udm.user_ou#: Name of the OU used as target container for user entries.

udm.user_pkey_property(optional)#: UDM property to use for storing the remote primary key for users.

udm.user_properties(optional)#: List of user property names the connector writes to.

udm.group_ou#: Name of the OU used as target container for group entries.

udm.group_pkey_property(optional)#: UDM property to use for storing the remote primary key for groups.

udm.group_properties(optional)#: List of group property names the connector writes to.

7.2.4.2.2. Section `source`#

source.ldap_uri#: LDAP URI of the source directory to connect to. Configure an URI starting with ldaps:// to ensure that the connector uses LDAP over TLS right from the beginning.

source.bind_dn#: The bind DN to use authenticate to the source directory through LDAP simple bind operation.

source.bind_pw#: The clear-text password to use with LDAP simple bind operation.

source.ca_cert(optional)#: Path of the trusted CA certificate bundle file. Defaults to your platform-specific CA bundle file.

source.timeout(optional)#: Timeout in seconds to wait for network. Default: 5 seconds.

source.search_pagesize(optional)#: Page size to used when searching with _Simple Paged Results_ control.

source.user_base#: search base used when searching user entries.

source.user_scope#

Search scope used when searching user entries.

Default: "sub".

Possible values: "one", "sub".

source.user_filter(optional)#: LDAP filter used when searching user entries.

source.user_attrs(optional)#: Request LDAP attributes while searching for users. Recommendation: only list the attributes actually used in the transformation and mapping later.

source.user_range_attrs(optional)#: LDAP user attributes for which values are optionally retrieved by _Range Retrieval_ for Microsoft Active Directory.

source.user_trans#: Data transformation configuration applied to user entries.

source.group_base#: search base used when searching group entries.

source.group_scope#

Search scope used when searching group entries.

Default: "sub".

Possible values: "one", "sub".

source.group_filter(optional)#: LDAP filter used when searching group entries.

source.group_attrs(optional)#: Request LDAP attributes while searching for groups. Recommendation: only list the attributes actually used in the transformation and mapping later.

source.group_range_attrs(optional)#: LDAP group attributes for which values are optionally retrieved by _Range Retrieval_ for Microsoft Active Directory.

source.group_trans#: Data transformation configuration applied to group entries.

Note

python-ldap uses the OpenLDAP client library libldap. And libldap implements a TLS hostname verification that strictly requires the hostname in the LDAP URI to match one of the DNS values of X.509v3 extension _subjectAltName_ in the source directory’s TLS server certificate.

7.2.5. Performance optimizations#

If your Directory Service in Nubus for Kubernetes would contain more than 25,000 user accounts after the synchronization with the external IAM system, the primary user group has more than 5,000 user accounts, and you want to synchronize with an external IAM system, you need to apply the recommended optimizations in this section to run the import in an acceptable amount of time.

7.2.5.1. Deactivate primary group updates#

By default, the Directory Manager assigns the Domain Users user group as the primary user group to imported user accounts. Having many group members in the primary user group degrades the performance of user account creation exponentially. Deactivating the Directory Manager’s default behavior of adding created user accounts to the primary group mitigates the performance degradation.

To deactivate the primary group updates in the Directory Service, add the lines from Listing 7.4 to your custom_values.yaml file of your Nubus for Kubernetes installation.

In consequence, the permissions derived from a membership in the Domain Users no longer apply. You need to manage them separately, for example through memberships in other user groups. Keep in mind that those user groups shouldn’t extend 5,000 user members, as well.

Listing 7.4 Deactivate primary group updates in Directory Service of Nubus for Kubernetes#

global:
  configUcr:
    directory:
      manager:
        user:
          primarygroup:
            update: false

7.2.5.2. Index for `univentionObjectIdentifier`#

univentionObjectIdentifier is an LDAP attribute that stores the primary identifier of an object from the source directory. The Directory Manager in Nubus enforces the uniqueness of this attribute by searching for existing occurrences in the Directory Service. If the Directory Service doesn’t have an index on the univentionObjectIdentifier attribute, searches for the attribute lead to an exponential performance degradation in environments with many user account objects.

Since Nubus for Kubernetes 1.9.0, the univentionObjectIdentifier LDAP attribute has an index for better performance. For more information, see Nubus for Kubernetes - Release Notes.

7.2.6. Setup single sign-on#

The Identity Provider within Nubus uses Keycloak and supports both SAML and OpenID Connect protocols. The Nubus Directory Importer imports user account and group account data from an external IAM system. The import process doesn’t copy user account credentials for compliance, security, and operational reasons. To allow the users to sign in to Nubus with their user accounts from the external IAM system, you need to set up Keycloak to delegate the authentication through its broker functionality to other identity providers. Depending on the configuration of the identity broker, end users can choose the identity provider in the Keycloak login dialog. Keycloak acts as a proxy service, forwarding the user’s sign-in request to the source IAM system and translating between SAML and OpenID Connect, if necessary.

This section describes how to set up single sign-on between the external source IAM system as identity provider and the Identity Provider within Univention Nubus for Kubernetes as service provider. You need to configure Keycloak as an Identity Broker to use the source system as a source for identities.

Before you start, make sure that the external IAM system and Keycloak communicate through port 443.

7.2.6.1. Add source system to Keycloak#

To add the source system to Keycloak, use the following steps:

Sign in to the Keycloak Admin Console, as described in Keycloak Admin Console.
Go to the section Identity Provider.
Select a user-defined identity provider based on either OpenID Connect v1.0 or SAML v2.0.
Provide the information about the source system.
OpenID Connect v1.0
For OpenID Connect you need to provide the following values:
- Alias
- Discovery endpoint
- Client ID
- Client Secret
- Other optional values
SAML v2.0
For SAML you need to provide the following values:
- Alias
- Service provider entity ID
- SAML entity descriptor
- Other optional values
Go to the section Authentication to configure different login flows. For the use case in this how-to, select the default flow browser.
Copy the login flow browser, provide a name and customize it to your needs.

Important

Change the parameter Identity Provider Redirector to Required. The parameter enforces the redirection to the source system and end users don’t have to select the source system in the login dialog.
In the step Identity Provider Redirector, click the cog wheel and select your previously created identity provider for your source system.

See also

Refer to the following resources from Keycloak Server Administration Guide [7]. Make sure to select the documentation that matches the Keycloak version in Univention Nubus for Kubernetes.

Integrating identity providers: for the Keycloak documentation about external identity providers.
OpenID Connect v1.0 identity providers: for the procedure to add a user-defined OpenID Connect v1.0 identity provider.
SAML v2.0 identity providers: for the procedure to add a user-defined SAML v2.0 identity provider.
Authentication flows: for the description of authentication flows.

7.2.6.2. Add Keycloak as client to source system#

To add Keycloak as client in the source system, use the following steps:

Create a client configuration for Keycloak in the source system.
OpenID Connect v1.0
For OpenID Connect you need to provide the following values:
- Client ID
- Client Secret
- Redirect URI
SAML v2.0

For SAML you need to provide the XML metadata from Keycloak.
Finally, you need to define the attributes that the source system forwards to Keycloak.

7.2.7. Verify the sign-in#

After you configured all pieces, you can sign in to Univention Nubus for Kubernetes with credentials for user accounts from the source system.

In the browser, Keycloak redirects the end user to the login dialog of the source system. The end users sign in one-time. Further browser-based access to the same application then no longer requires an additional sign-in.

Nubus for Kubernetes - Operation Manual 1.x

Import from external IAM

Contents

7.2. Import from external IAM#

7.2.1. Prerequisites#

7.2.2. Connection setup for UDM HTTP REST API#

7.2.3. Nubus Directory Importer installation#

7.2.3.1. Docker Compose#

7.2.3.2. Helm Chart and Kubernetes#

7.2.3.3. TLS in Nubus Directory Importer#

7.2.4. Configuration of Nubus Directory Importer#

7.2.4.1. Example configuration#

7.2.4.2. Configuration reference#

7.2.4.2.1. Section: `udm`#

7.2.4.2.2. Section `source`#

7.2.5. Performance optimizations#

7.2.5.1. Deactivate primary group updates#

7.2.5.2. Index for `univentionObjectIdentifier`#

7.2.6. Setup single sign-on#

7.2.6.1. Add source system to Keycloak#

7.2.6.2. Add Keycloak as client to source system#

Nubus for Kubernetes - Operation Manual 1.x

Import from external IAM

Contents

7.2. Import from external IAM#

7.2.1. Prerequisites#

7.2.2. Connection setup for UDM HTTP REST API#

7.2.3. Nubus Directory Importer installation#

7.2.3.1. Docker Compose#

7.2.3.2. Helm Chart and Kubernetes#

7.2.3.3. TLS in Nubus Directory Importer#

7.2.4. Configuration of Nubus Directory Importer#

7.2.4.1. Example configuration#

7.2.4.2. Configuration reference#

7.2.4.2.1. Section: udm#

7.2.4.2.2. Section source#

7.2.5. Performance optimizations#

7.2.5.1. Deactivate primary group updates#

7.2.5.2. Index for univentionObjectIdentifier#

7.2.6. Setup single sign-on#

7.2.6.1. Add source system to Keycloak#

7.2.6.2. Add Keycloak as client to source system#

7.2.7. Verify the sign-in#

7.2.4.2.1. Section: `udm`#

7.2.4.2.2. Section `source`#

7.2.5.2. Index for `univentionObjectIdentifier`#