.. SPDX-FileCopyrightText: 2024 Univention GmbH .. .. SPDX-License-Identifier: AGPL-3.0-only .. index:: pair: overview; interfaces and protocols single: interfaces single: protocols .. _overview-interfaces-protocols: ************************ Interfaces and protocols ************************ Nubus for Kubernetes components offer services to clients and other components through network interfaces. Protocols define how services and other components use these interfaces. This section describes the interfaces each component offers, called inbound, and the interfaces it connects to, called outbound. From an external perspective, Univention Nubus for Kubernetes offers the following protocols to the outside of the Nubus cluster: * OAuth 2.0, :term:`OpenID Connect`, and Security Assertion Markup Language (:term:`SAML`) provided by the :ref:`interfaces-identity-provider`. * Nubus web applications, such as the :ref:`interfaces-management-ui` and :ref:`interfaces-portal-service`, through HTTP Univention Nubus for Kubernetes uses *Kubernetes Service objects* of the type ``ClusterIP``. The figures in this section show the ports defined as port in the service object, not the actual container ports. However, the descriptions of the *application components* mention the container ports where they differ from the port defined in the service object. .. seealso:: `Service | Kubernetes `_ for more information about the Kubernetes service method for exposing a network application that runs as one or more pods in a cluster. Wikipedia: `OAuth `_ for more information about the open authorization standard. .. dropdown:: Information about used notation :color: info This section uses the active structure elements *Application Component* and *Application Interface* from the application layer and the relationships *Composition*, *Aggregation*, and *Serving* of the ArchiMate notation. For more information on these ArchiMate concepts, refer to the following sections in :cite:t:`uv-architecture`: * :external+uv-architecture:ref:`notation-archimate-application-layer` * :external+uv-architecture:ref:`notation-archimate-relationships` .. _interfaces-external-perspective: External perspective ==================== From an external perspective, Univention Nubus for Kubernetes offers the following inbound protocols and standards to the outside of the Nubus Kubernetes cluster as shown in :numref:`interfaces-external-perspective-fig`: * The open standards OAuth 2.0, :term:`OpenID Connect`, and Security Assertion Markup Language (:term:`SAML`) provided by the :ref:`interfaces-identity-provider`. * Nubus web applications through HTTP: * :ref:`interfaces-management-ui` * :ref:`interfaces-portal-service` .. _interfaces-external-perspective-fig: .. figure:: /images/Interfaces_external_perspective.* :target: ../_images/Interfaces_external_perspective.svg :alt: ArchiMate view for the interfaces and protocols of Univention Nubus for Kubernetes from external perspective :width: 75% ArchiMate view for the interfaces and protocols of Univention Nubus for Kubernetes from external perspective. :numref:`interfaces-external-perspective-detail-fig` shows more details about the interfaces from the external perspective. The *HTTP to Nubus* interface combines the following HTTP interfaces: * From the :ref:`interfaces-management-ui` for serving static files, and connecting to the *UMC Server*. * From the :ref:`interfaces-portal-service` the interfaces from the *Portal Frontend*, the *Portal Server*, and the *HTTP REST API for notifications*. The view shows the details, so the reader can find them again in the views :numref:`interfaces-management-ui-fig` and :numref:`interfaces-portal-service-fig` in this section. .. _interfaces-external-perspective-detail-fig: .. figure:: /images/Interfaces_external_perspective_details.* :target: ../_images/Interfaces_external_perspective_details.svg :alt: Detailed ArchiMate view for the interfaces and protocols from external perspective Detailed ArchiMate view for the interfaces and protocols from external perspective .. _interfaces-authorization-service: Authorization Service ===================== The *Guardian* consists of four separate components. Each offers and consumes services. The following sections show the services and protocols. :numref:`interfaces-authorization-service-fig` shows the interfaces and protocols of the *Authorization Service*. .. _interfaces-authorization-service-fig: .. figure:: /images/Interfaces_Authorization_Service.* :target: ../_images/Interfaces_Authorization_Service.svg :alt: ArchiMate view for the interfaces and protocols of the Authorization Service ArchiMate view for the interfaces and protocols of the *Authorization Service* .. seealso:: :ref:`overview-components-authorization-service` in the functional components overview section for more information the purpose and tasks. .. _interfaces-authorization-service-authorization-rest: Guardian Authorization HTTP REST API ------------------------------------ Inbound HTTP on port ``80`` provides a HTTP REST API for other services to request authorization, using previously defined rules. The *Guardian Authorization REST API* needs a service account in the :ref:`interfaces-identity-provider` for authentication. A Kubernetes Service from the type ``ClusterIP`` maps port ``80`` to the container port ``8000``. Outbound * HTTP to the :ref:`interfaces-directory-manager` to request read-only data for user accounts and user groups. * HTTP to the :ref:`interfaces-authorization-service-open-policy-agent` to process authorization requests. .. _interfaces-authorization-service-open-policy-agent: Open Policy Agent ----------------- Inbound HTTP on port ``80`` provides REST API to manage different aspects of the *Open Policy Agent* service. No authentication required. Not exposed through ingress. Only :ref:`interfaces-authorization-service-authorization-rest` uses this port. A Kubernetes Service from the type ``ClusterIP`` maps port ``80`` to the container port ``8181``. Outbound HTTP to the :ref:`interfaces-authorization-service-management-rest` to regularly fetch the current policy data. .. _interfaces-authorization-service-management-rest: Guardian Management HTTP REST API --------------------------------- Inbound HTTP on port ``80`` provides REST API for :term:`CRUD` operations on authorization objects, such as rules, namespaces, permissions, and roles, etc., and a policy bundle service for the :ref:`interfaces-authorization-service-open-policy-agent`. A Kubernetes Service from the type ``ClusterIP`` maps port ``80`` to the container port ``8000``. Inbound requests require an OAuth 2.0 token for a user account with appropriate roles to access the authorization objects. Outbound * HTTP to the :ref:`interfaces-authorization-service-authorization-rest` to authorize CRUD operations on authorization objects. * TCP connection to an externally managed SQL database or database cluster to persist authorization objects. * HTTP to *Keycloak* in :ref:`interfaces-identity-provider` to retrieve certificates through OAuth 2.0. .. seealso:: Wikipedia: `OAuth (open authorization) `_ for more information about the open authorization standard. .. _interfaces-authorization-service-management-ui: Guardian Management UI ---------------------- Inbound HTTP on port ``80`` provides a web application for the end user administrators to manage authorization objects, such as apps, rules, etc. To use the *Guardian Management UI*, you must have a user account with the appropriate roles to access the authorization objects. Outbound HTTP to the :ref:`interfaces-authorization-service-management-rest` for :term:`CRUD` operations on authorization objects, using the previously received token. .. _interfaces-directory-manager: Directory Manager ================= Inbound HTTP on port ``80`` provides a REST API offering :term:`CRUD` operations on :term:`IAM` objects, such as user account objects, user group objects, and asset objects, stored in the *Identity Store and Directory Service*. A Kubernetes Service from the type ``ClusterIP`` maps port ``80`` to the container port ``9979``. The inbound access requires authentication using an LDAP object's distinguished name (DN) as username and the object's password. The UDM REST server first authorizes coarsely by checking user and group membership. The OpenLDAP server does a fine-grained control for each request and applies LDAP ACLs. The HTTP REST API is the only interface to write IAM objects directly. For the interactive management of user account objects, user group objects, and asset objects, see the :ref:`interfaces-management-ui`. .. TODO : Move information about authorization process to detailed section about this component, after it exists. Outbound LDAP connections to the *Identity Store and Directory Service* for authentication of *UDM HTTP REST API* access and CRUD operations on LDAP objects. :numref:`interfaces-identity-provider-fig` shows the mentioned interfaces in an ArchiMate view. .. _interfaces-directory-manager-fig: .. figure:: /images/Interfaces_Directory_Manager.* :target: ../_images/Interfaces_Directory_Manager.svg :alt: ArchiMate view for the interfaces of the Directory Manager ArchiMate view for the interfaces and protocols of the *Directory Manager* .. seealso:: :ref:`overview-components-directory-manager` in the functional components overview section for more information about the purpose and tasks. .. _interfaces-end-user-self-service: End User Self Service ===================== The Self Service consists of the following components: UMC Gateway See *UMC Gateway* in section :ref:`interfaces-management-ui`. UMC Server See *UMC Server* in section :ref:`interfaces-management-ui`. Email Trigger Service includes the *Self Service Listener*. Inbound None. Outbound * TCP connection to the *Univention LDAP Notifier* to listen for notifications about changes in the :ref:`interfaces-identity-store`. * LDAP connection to the *Identity Store and Directory Service* for one-way synchronization of LDAP data. * HTTP to *UMC Server* in :ref:`interfaces-management-ui` to request sending of user invitation email. .. seealso:: :ref:`overview-components-end-user-self-service` in the functional components overview section for more information about the purpose and tasks. .. _interfaces-identity-provider: Identity Provider ================= The *Identity Provider* consists of the following components: Keycloak Inbound * :term:`OpenID Connect` interface to *OpenID Connect Provider* in Keycloak for authentication. * OAuth 2.0 interface to *OAuth 2.0 Provider* in Keycloak for authentication. * :term:`SAML` interface to *SAML Identity Provider* in Keycloak for authentication. Outbound: * LDAP connection to the *OpenLDAP server* in the :ref:`interfaces-identity-store` used to authenticate access, and for one-way synchronization of user account and user group data. * TCP connection to an externally SQL managed database or database cluster for persistence for authorization objects and for handler-proxy communication. In Nubus, Keycloak is also responsible for providing the protocols OpenID Connect and SAML. .. seealso:: `SSO protocols `_ in :cite:t:`keycloak-latest` for more information about how to use those protocols in Keycloak. Keycloak Proxy Inbound HTTP on port ``8181`` for transparent proxy to *Keycloak* authentication endpoints. The Identity Provider only exposes this port through ingress. Outgoing * HTTP to *Keycloak* for forwarded request. * TCP connection to an externally SQL managed database or database cluster for persistence for handler-proxy communication. Keycloak Handler Inbound None. Outbound * SMTP to send an email to the user when there is a login from a new device. * TCP connection to an externally managed SQL database or database cluster for persistence for handler-proxy communication. :numref:`interfaces-identity-provider-fig` shows the mentioned interfaces in an ArchiMate view. .. _interfaces-identity-provider-fig: .. figure:: /images/Interfaces_Identity_Provider.* :target: ../_images/Interfaces_Identity_Provider.svg :alt: ArchiMate view for the interfaces and protocols of the Identity Provider ArchiMate view for the interfaces and protocols of the *Identity Provider* .. seealso:: :ref:`overview-components-identity-provider` in the functional components overview section for more information about the purpose and tasks. .. _interfaces-identity-store: Identity Store and Directory Service ==================================== The *Identity Store and Directory Service* consists of the following components: LDAP Server Inbound * LDAP on port ``389`` for the LDAP protocol server, port for TCP and UDP connections. * LDAP on port ``636`` for the LDAP protocol server, port for TCP and UDP connections over TLS. Outbound HTTP connection to *Keycloak* in :ref:`interfaces-identity-provider` to retrieve :term:`SAML` metadata. The *LDAP Server* provides access to the directory service through LDAP to services in the same cluster network. This means that services other than Nubus can have read-only access to the *LDAP Server* through LDAP if they're in the same Kubernetes cluster network as Nubus. .. important:: Univention only supports **read-only** access to the LDAP directory service through LDAP. For write operations to the LDAP directory service, use the *UDM HTTP REST API*, because it applies business logic and sanity checks to ensure data consistency. For more information, see :ref:`Directory Manager internal functions ` in the components section. :numref:`interfaces-identity-store-ldap-server-fig` shows the before mentioned inbound ports. In some sections of this manual, the connection to the *LDAP Server* is just referred to as *LDAP* for the protocol without specifying the port. In most cases, clients initiate an encrypted connection with a ``STARTTLS`` request. .. _interfaces-identity-store-ldap-server-fig: .. figure:: /images/Interfaces_LDAP.* :target: ../_images/Interfaces_LDAP.svg :alt: Relationships between the LDAP Server and its inbound interfaces :width: 50% Relationships between the *LDAP Server* and its inbound interfaces Univention LDAP Notifier The *Univention LDAP Notifier* is temporary, until the Provisioning consumer in :ref:`interfaces-provisioning-service` replaces it. Inbound Notifier on port ``6669`` that informs clients, such as the *Self Service Listener* in the *Email Trigger Service* of the :ref:`interfaces-end-user-self-service`, about changes in the *Identity Store and Directory Service*. Outbound None :numref:`interfaces-identity-store-fig` shows the mentioned interfaces in an ArchiMate view. .. _interfaces-identity-store-fig: .. figure:: /images/Interfaces_Identity_Store.* :target: ../_images/Interfaces_Identity_Store.svg :alt: ArchiMate view for the interfaces and protocols of the Identity Store and Directory Service ArchiMate view for the interfaces and protocols of the *Identity Store and Directory Service* .. seealso:: :ref:`overview-components-identity-store` in the functional components overview section for more information about the purpose and tasks. .. _interfaces-intercom-service: Intercom Service ================ For a description of the *Intercom Service*, refer to :ref:`overview-components-intercom-service`. Inbound HTTP on port ``8008`` for general and app-specific endpoints for browsers. Outbound * HTTP to frontends and backends of different web services, such as Nextcloud and Matrix for token exchange. * HTTP to *Keycloak* in the :ref:`interfaces-identity-provider` for token exchange. * Redis connection to an externally managed Redis database or Redis database cluster. :numref:`interfaces-intercom-service-fig` shows the mentioned interfaces in an ArchiMate view. .. _interfaces-intercom-service-fig: .. figure:: /images/Interfaces_Intercom_Service.* :target: ../_images/Interfaces_Intercom_Service.svg :alt: ArchiMate view for the interfaces and protocols of the Intercome Service ArchiMate view for the interfaces and protocols of the *Intercom Service* .. seealso:: :ref:`overview-components-intercom-service` in the functional components overview section for information about the purpose and tasks. .. _interfaces-management-ui: Management UI ============= The *Management UI* consists of following components: UMC Gateway Inbound: HTTP on port ``80`` to serve static files to the end user's browser. Outbound: None UMC Server Inbound: HTTP on port ``8090`` to multiplex connections to various RPC endpoints, the UMC modules. A Kubernetes Service from the type ``ClusterIP`` maps port ``80`` to the container port ``8090``. Outbound: * LDAP connections to the *OpenLDAP server* in :ref:`interfaces-identity-store` to read and update user data. * HTTP connections to *Keycloak* in :ref:`interfaces-identity-provider`. * SMTP connections to send user invitation email. * TCP connection to an externally managed SQL database or database cluster for persistence for password reset requests. * Memcached connection to an externally managed Memcached database or Memcached database cluster for session storage. :numref:`interfaces-management-ui-fig` shows the mentioned interfaces in an ArchiMate view. .. _interfaces-management-ui-fig: .. figure:: /images/Interfaces_Management_UI.* :target: ../_images/Interfaces_Management_UI.svg :alt: ArchiMate view for the interfaces and protocols of the Management UI ArchiMate view for the interfaces and protocols of the *Management UI* .. seealso:: :ref:`overview-components-management-ui` in the functional components overview section for more information about the purpose and tasks. .. _interfaces-portal-service: Portal Service ============== The *Portal Service* consists of the following components: Portal Frontend Inbound HTTP on port ``80`` to serve static files to the end user's browser. Outbound None .. note:: :numref:`interfaces-portal-service-fig` shows the additional ArchiMate application component *Portal Frontend in User Browser*. This application component isn't part of Nubus, but runs software provided by the Nubus Portal Service. The authors found it useful to introduce this application component to emphasize that the *Portal Frontend* application component doesn't have any outbound connections, but the Portal Frontend software running in the user's browser does. Portal Frontend in User Browser The *Portal Frontend* is a single-page application (:term:`SPA`) consisting of HTML, JavaScript, CSS and media files. The user's browser loads those artifacts and runs them. Inbound None Outbound * HTTP connection to *Portal Frontend* to load the SPA. * HTTP connection to *Portal Server* running the backend. Portal Server Inbound HTTP on port ``80`` running the backend for the Portal frontend code running in the end user's browser. Outbound * HTTP connection to an S3-compatible storage to load the generated Portal configuration. * HTTP connection to :ref:`interfaces-management-ui` to retrieve session information. Portal Consumer Inbound None. Outbound * HTTP connection to the *Consumer Messages HTTP REST API* in :ref:`interfaces-provisioning-service` to listen for messages about changes to portal and group objects in the directory service. * LDAP connection to the *OpenLDAP server* in *Identity Store and Directory Service* for one-way synchronization of LDAP data. * HTTP connection to an S3-compatible storage to store the generated Portal configuration. * HTTP connection to the *UDM HTTP REST API* in :ref:`interfaces-directory-manager`. Notifications API Inbound HTTP on port ``80`` to provide the REST API for notifications in the Portal. Outbound TCP connection to an externally managed SQL database or database cluster for persistence for notification objects. :numref:`interfaces-portal-service-fig` shows the mentioned interfaces in an ArchiMate view. .. _interfaces-portal-service-fig: .. figure:: /images/Interfaces_Portal_Service.* :target: ../_images/Interfaces_Portal_Service.svg :alt: ArchiMate view for the interfaces and protocols of the Portal Service ArchiMate view for the interfaces and protocols of the *Portal Service* .. note:: From the perspective of *Portal Service* functional component it uses the *HTTP to S3-compatible Storage* interface as outbound connection. The S3-compatible storage isn't part of Nubus, see :external+uv-nubus-kubernetes-operation:ref:`requirements-object-store` in :cite:t:`uv-nubus-kubernetes-operation`. From the storage's perspective, all the connections are inbound. .. seealso:: :ref:`overview-components-portal-service` in the functional components overview section for more information about the purpose and tasks. .. _interfaces-provisioning-service: Provisioning Service ==================== The *Provisioning Service* consists of the following components: Events and Consumer API Inbound HTTP on port ``80`` for the public REST API for LDAP change event consumers and internal REST API for the Dispatcher. Outbound TCP connection to *NATS* database. NATS Inbound * TCP port ``4222`` for NATS client connections. * TCP port ``6222`` to route connections for NATS clustering. * HTTP port ``8222`` for monitoring and reporting. The inbound interfaces to *NATS* are only available from within the functional component *Provisioning Service*. Outbound None. Dispatcher Inbound None. Outbound * HTTP connection to *Events and Consumer API*. * TCP connection to *NATS* database. Prefill Service Inbound None. Outbound * HTTP connection to *Events and Consumer API*. * HTTP connection to *UDM HTTP REST API* in :ref:`interfaces-directory-manager`. * TCP connection to *NATS* database. UDM Listener Inbound None. Outbound * TCP connection to the *Univention LDAP Notifier* in :ref:`interfaces-identity-store` to listen for notification about changes in the LDAP database. * LDAP connection to the *OpenLDAP server* in :ref:`interfaces-identity-store` for one-way synchronization of LDAP data, and individual queries. * HTTP connection to *Events and Consumer API*. :numref:`interfaces-provisioning-service-fig` shows the mentioned interfaces in an ArchiMate view. The only interface exposed to the outside world by the *Provisioning Service* functional component is the *Events and Consumer API*. The functional component uses all other shown interfaces internally within the functional component. .. _interfaces-provisioning-service-fig: .. figure:: /images/Interfaces_Provisioning_Service.* :target: ../_images/Interfaces_Provisioning_Service.svg :alt: ArchiMate view for the interfaces and protocols of the Provisioning Service ArchiMate view for the interfaces and protocols of the *Provisioning Service* .. seealso:: :ref:`overview-components-provision-service` in the functional components overview section for more information about the purpose and tasks. .. _interfaces-2fa-helpdesk: 2FA Helpdesk ============ The *2FA Helpdesk* consists of the following components: 2FA Helpdesk Frontend Inbound HTTP on port ``80`` to serve static files to the end user's browser. Outbound None 2FA Helpdesk Backend Inbound HTTP on port ``8080`` to receive calls from the *2FA Helpdesk Frontend* to the API. Outbound HTTP to Keycloak to reset 2FA tokens. .. _interfaces-2fa-helpdesk-fig: .. figure:: /images/Interfaces_2FA_Helpdesk.* :target: ../_images/Interfaces_2FA_Helpdesk.svg :alt: ArchiMate view for the interfaces and protocols of the 2FA Helpdesk ArchiMate view for the interfaces and protocols of the *2FA Helpdesk* .. seealso:: :ref:`overview-components-2fa-helpdesk` in the functional components overview section for more information about the purpose and tasks.