.. SPDX-FileCopyrightText: 2024 Univention GmbH .. .. SPDX-License-Identifier: AGPL-3.0-only .. _component-connectors: Connectors ========== This section describes the *Connectors* functional component of Nubus for Kubernetes, the functions, components, and their relationships with each other. Nubus provides the :ref:`component-iam-connector` functional element with interfaces that allow Nubus to connect external IAM systems. One implementation of such interfaces is the :ref:`component-nubus-directory-importer`. .. seealso:: :ref:`overview-components-connectors` in the functional components overview section for information about purpose and tasks. .. _component-iam-connector: IAM Connector -------------- Nubus provides interfaces for connecting an external :term:`IAM` system to Nubus for Kubernetes. The idea is that the external :term:`IAM` system provides Nubus with identity data or the other way around. The interfaces allow the following uses: * The :term:`LDAP` interface for read operations. * The *LDAP* interface for write operations to the external IAM system. * The *UDM HTTP REST API* for read- and write operations to the Nubus directory service. The concept allows communication in one direction, unidirectional, or in both directions, bidirectional. It depends on the agreement between the two systems. One direction from the Nubus perspective means that Nubus only receives, or only sends data. Both directions, Nubus receives and sends data. How the comparison and synchronization of the data between Nubus and the external directory or :term:`IAM` system works, depends on the implementation of the connector. .. important:: The *IAM Connector* is similar to an abstract class in the object oriented programming concept. An abstract class defines interfaces and needs distinct implementations. As functional element, the *IAM Connector* is part of the architecture model of Nubus. .. _component-nubus-directory-importer: Nubus Directory Importer ------------------------ The Nubus Directory Importer is an implementation of the *IAM Connector* interfaces. It's a service that imports and synchronizes directory objects from a source directory service to the directory service in Nubus as a target directory service. It detects differences between the source and the target. Its not part of the Nubus for Kubernetes deployment. Operators must install it separately. For more information about the installation, see :external+uv-nubus-kubernetes-operation:ref:`conf-import-external-iam-installation` in :cite:t:`uv-nubus-kubernetes-operation`. :numref:`component-nubus-directory-importer-figure` shows the ArchiMate overview for the *Nubus Directory Importer*. At the top are the ArchiMate concepts representing the source directory service. The *Nubus Directory Importer* includes the following aspects: * A source directory service, for example :program:`Microsoft Active Directory`. * A target directory service, in the Nubus for Kubernetes architecture it's the directory service in Nubus, :program:`OpenLDAP`. * The *Nubus Directory Importer*. * A :ref:`component-nubus-directory-importer-sso` between the *Identity Provider* in Nubus and the *External Directory service*. .. important:: The *Nubus Directory Importer* doesn't import sensitive password hashes from the external *IAM Directory service*. This would require extra active software running on the external *IAM Directory service* with higher security privileges. Usually, that's an unwanted customization with security risks. The importer imports user account information. The *Identity Provider* in Nubus needs a trust relationship with the *External Directory service* to handle or delegate authentication depending on the configuration. .. _component-nubus-directory-importer-figure: .. figure:: /images/Nubus_Directory_Importer_overview.* :target: ../_images/Nubus_Directory_Importer_overview.svg :alt: Overview of the Nubus Directory Importer Overview of the *Nubus Directory Importer* .. seealso:: :external+uv-nubus-kubernetes-operation:ref:`conf-import-external-iam` in :cite:t:`uv-nubus-kubernetes-operation` for information about how to connect an external *IAM Directory service* to Nubus and how to set up single sign-on. .. _component-nubus-directory-importer-import: Import ~~~~~~ This section explains how the import works. :numref:`component-Nubus-Directory-Importer-import-figure` shows the relationships between the parts involved in an import. The import searches for all directory objects in both the source and target directory services. The importer then takes the two sets of directory objects, compares them, and determines the differences. Based on the differences, the importer creates a set of UDM objects that cover the necessary changes for the target directory service to synchronize with the source directory. The importer then sends the set of UDM objects to the *UDM HTTP REST API*. The synchronization process writes the complete OU structure of the source to a dedicated OU in the *LDAP Server* of the *Identity Store and Directory Service*. The *Nubus Directory Importer* is stateless and doesn't store any local state. .. _component-nubus-directory-importer-import-figure: .. figure:: /images/Nubus_Directory_Importer_import.* :target: ../_images/Nubus_Directory_Importer_import.svg :alt: Overview data import ArchiMate view on the import to the target directory service .. _component-nubus-directory-importer-flow: Data flow ~~~~~~~~~ This section describes the data flow of the *Nubus Directory Importer*. :numref:`component-nubus-directory-importer-flow-figure` shows the data flow perspective together with the behavior. The data flow in the *Nubus Directory Importer* is unidirectional, from the source to the target. In detail, the *Nubus Directory Importer* searches for user accounts and user groups in the external IAM system. The search process uses the *LDAP interface*. In a second step, the importer searches for user accounts and user groups in the *Identity Store and Directory Service*. The importer compares the two data sets. Based on the difference, it generates UDM objects and sends them to the *UDM HTTP REST API*. UDM then writes them to the *Identity Store and Directory Service*. .. _component-nubus-directory-importer-flow-figure: .. figure:: /images/Nubus_Directory_Importer_flow.* :target: ../_images/Nubus_Directory_Importer_flow.svg :alt: Dataflow of Nubus Directory Importer Data flow from the source directory service through the Nubus Directory Importer to the target directory service. .. _component-nubus-directory-importer-sso: Trust relationship for authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Before users can sign in with their user account located in the source directory service, the operator must establish a trust relationship between the *Identity Provider* in Nubus and the source directory service. To establish the trust relationship, the operator can choose either :term:`SAML` or :term:`OpenID Connect`. :numref:`component-Nubus-Directory-Importer-SSO-figure` shows the relationships involved. With the established trust relationship, users from the external directory service can sign in through a trusted identity provider and Nubus and the connected applications can verify the authenticity of the user. Which identity provider the users choose for sign-in depends on the configuration and is beyond the scope of this document. .. _component-Nubus-Directory-Importer-SSO-figure: .. figure:: /images/Nubus_Directory_Importer_SSO.* :target: ../_images/Nubus_Directory_Importer_SSO.svg :alt: Single sign-on solution of the Nubus Directory Importer :width: 600px Single sign-on solution of the Nubus for Kubernetes .. seealso:: :external+uv-nubus-kubernetes-operation:ref:`conf-import-external-iam-sso-setup` in :cite:t:`uv-nubus-kubernetes-operation` for information about how to connect an external *IAM Directory service* to Nubus and how to set up single sign-on.