.. SPDX-FileCopyrightText: 2024 Univention GmbH .. .. SPDX-License-Identifier: AGPL-3.0-only .. _component-portal-service: Portal Service ============== This section provides an overview of the *Portal Service* component in Nubus for Kubernetes. It describes the following *Portal Service* components in detail: #. :ref:`component-portal-service-server` #. :ref:`component-portal-service-Frontend` #. :ref:`component-portal-service-consumer` #. :ref:`component-portal-service-announcement` #. :ref:`component-portal-service-notifications-api` #. :ref:`component-portal-service-central-navigation-api` :numref:`component-portal-service-complete-figure` shows the *Portal Service* components, their relationships among each other and to other functional components in Nubus. The upcoming sections add the behavior level for each of the components. .. _component-portal-service-complete-figure: .. figure:: /images/Functional_component_Portal_Service_complete.* :target: ../_images/Functional_component_Portal_Service_complete.svg :alt: Functional components of the Portal Service. Functional components of the Portal Service. Some application components in the *Portal Service* need an S3-compatible object storage. For a relational overview from the object storage perspective, see :ref:`overview-s3-compatible-storage`. .. seealso:: :ref:`interfaces-portal-service` in the interfaces section for information about incoming and outgoing interfaces. :ref:`deployment-portal` in the deployment view section for information about Docker images, Kubernetes pods, and Helm Charts used for deployment. :ref:`overview-components-portal-service` in the functional components overview section for more information about the purpose and tasks. :ref:`overview-s3-compatible-storage` for information about application components using S3-compatible object storage. .. _component-portal-service-server: Portal Server ------------- The *Portal Server* is the core component of the :ref:`component-portal-service`. It provides the following functionality, as shown in :numref:`component-portal-service-server-figure`. * *Manage portals and user group assignment* to define which portal the *Portal Service* shows to which user group. * *Evaluate groups of the user* to determine which portal entries to show to the user. * *Read the portal configuration* for the *Portal Server*, such as configuration information, categories for tiles, and portal tiles. * *User session handling* so that users see the content designated for them. The *S3-compatible storage* contains the *User group cache for Portal Service* and the *Portal Service configuration* for fast retrieval. Other functionality, described later, stores the information in there. .. _component-portal-service-server-figure: .. figure:: /images/Functional_component_Portal_Service_Server.* :target: ../_images/Functional_component_Portal_Service_Server.svg :alt: Behavior of the Portal Service Server. Behavior of the Portal Service Server. .. _component-portal-service-frontend: Portal Frontend --------------- The *Portal Frontend* consists of the following parts, as shown in :numref:`component-portal-service-frontend-figure`. .. _component-portal-service-frontend-portal-frontend: Portal Frontend The *Portal Frontend* is a Kubernetes pod that delivers the frontend as single web page application to the user's web browser. It consists of HTML, CSS, JSON, and SVG files. The *Portal Frontend* also delivers dynamic portal assets. .. _component-portal-service-frontend-user-browser: Portal Frontend in the User Browser The *Portal Frontend in the User Browser* is the single web page application that runs in the user's browser. It also contains UI elements for the :ref:`component-end-user-self-service`. .. _component-portal-service-frontend-figure: .. figure:: /images/Functional_component_Portal_Service_Frontend.* :target: ../_images/Functional_component_Portal_Service_Frontend.svg :alt: Behavior of the Portal Service Frontend. :width: 600px Behavior of the Portal Service Frontend. .. _component-portal-service-consumer: Portal Consumer --------------- The *Portal Consumer* is responsible for writing the portal configuration and the group cache to the S3-compatible storage. During Nubus deployment, the *Portal Service* registers the *Portal Consumer* as a consumer in the :ref:`component-provisioning-service`. The *Portal Consumer* provides the following behavior, as shown in :numref:`component-portal-service-consumer-figure`: * *Write Portal configuration* * *React on user group membership change* * *Recreate user group cache* From Directory Service through Provisioning Service to Portal Consumer A portal administrator creates portals with portal entries and assigns user groups through the :ref:`component-portal-service-server`. The *Portal Server* stores the information in the :ref:`component-identity-store-directory-service`. The *Directory Service* :ref:`notifies about changes to directory objects ` and triggers the data transformation and messaging process in the :ref:`component-provisioning-service`. The *Portal Consumer* receives a message from the *Consumer Messages HTTP REST API* to *React on user group membership change*. User group cache Triggered by the *Provisioning Service*, the application function *Read user group cache* receives the *Event object* containing the changes to user groups and portals. To create the user group cache, it queries the *Directory Service* directly for the affected user groups, nested groups, and their user account memberships. With this data, it builds a mapping to resolve a username to its direct and indirect or nested group memberships. It stores the resulting mapping in the *S3-compatible storage* for the :ref:`component-portal-service-server`. Portal configuration *Write Portal configuration* writes the configuration for the *Portal Service* to the *S3-compatible storage*. Changes to *Portals* and *Portal Entries* in the directory service trigger the *Provisioning Service* to notify the *Portal Consumer*. .. _component-portal-service-consumer-figure: .. figure:: /images/Functional_component_Portal_Service_Consumer.* :target: ../_images/Functional_component_Portal_Service_Consumer.svg :alt: Behavior of the Portal Service Consumer. Behavior of the Portal Service Consumer. .. _component-portal-service-announcement: Portal Announcement ------------------- The *Portal Announcement* component shows announcements in the portal to a predefined group of users or all users. For example, administrators can inform users about an upcoming maintenance, or a recent update of a service. *Portal Announcement* provides a UMC module to *Manage announcements*. It runs in the *UMC Server* in the :ref:`overview-components-management-ui`. :numref:`component-portal-service-announcement-figure` shows the behavior of the *Portal Announcement* together with data flow of the associated information. *UMC Server* stores the announcement settings in the *LDAP Server*. This change triggers the *Provisioning Service* and passes the information to the *Portal Consumer* which *Write Portal configuration* to the *S3-compatible storage*. The *Portal Server* reads the portal configuration and shows the announcement in the portal. .. _component-portal-service-announcement-figure: .. figure:: /images/Functional_component_Portal_Service_Announcement.* :target: ../_images/Functional_component_Portal_Service_Announcement.svg :alt: Behavior of the Announcement module. Behavior of the Announcement module. .. _component-portal-service-notifications-api: Notifications API ----------------- The *Notifications API* provides an interface to applications to show messages in the portal to all users. :numref:`component-portal-service-notifications-api-figure` shows the behavior of the *Notifications API*. *Nubus application* or *Third-party applications not part of Nubus* send their notifications to the *Endpoint to notify users*. The *Notifications API* takes the notification and passes it to the *Endpoint of notification stream*. The *Endpoint of notification stream* sends the message to the portal. The *Portal Frontend in the User Browser* shows the notification. Notification are transient. The *Notifications API* doesn't save them persistently. .. _component-portal-service-notifications-api-figure: .. figure:: /images/Functional_component_Portal_Service_Notifications_API.* :target: ../_images/Functional_component_Portal_Service_Notifications_API.svg :alt: Behavior of the Notifications API. Behavior of the Notifications API. .. _component-portal-service-central-navigation-api: Central Navigation API ---------------------- Third-party applications can use the *Central Navigation API* to append their application menu with navigation links that the user has on their portal. :numref:`component-portal-service-central-navigation-api-figure` shows the behavior of the *Central Navigation API*. The *Third-party applications not part of Nubus* have behavior that can *Enhance global navigation menu for user*. For this purpose, it requests the information from the *Central Navigation API*. The returned data contains information about label, target, and icon of the tiles on the portal. .. _component-portal-service-central-navigation-api-figure: .. figure:: /images/Functional_component_Portal_Service_Navigation_API.* :target: ../_images/Functional_component_Portal_Service_Navigation_API.svg :alt: Behavior of the Central Navigation API. Behavior of the Central Navigation API. .. TODO: Add reference to the customization guide in a seealso box that explains how to use the API.