2.4. 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, OpenID Connect, and Security Assertion Markup Language (SAML) provided by the Identity Provider.

• Nubus web applications, such as the Management UI and 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.

See also

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.

Information about used notation

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 Univention Corporate Server Architecture [2]:

• Application layer

• Relationships

2.4.1. 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 Fig. 2.14:

• The open standards OAuth 2.0, OpenID Connect, and Security Assertion Markup Language (SAML) provided by the Identity Provider.

• Nubus web applications through HTTP:

  • Management UI

  • Portal Service

Fig. 2.14 ArchiMate view for the interfaces and protocols of Univention Nubus for Kubernetes from external perspective.

Fig. 2.15 shows more details about the interfaces from the external perspective. The HTTP to Nubus interface combines the following HTTP interfaces:

• From the Management UI for serving static files, and connecting to the UMC Server.

• From the 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 Fig. 2.22 and Fig. 2.23 in this section.

Fig. 2.15 Detailed ArchiMate view for the interfaces and protocols from external perspective

2.4.2. Authorization Service

The Guardian consists of four separate components. Each offers and consumes services. The following sections show the services and protocols. Fig. 2.16 shows the interfaces and protocols of the Authorization Service.

Fig. 2.16 ArchiMate view for the interfaces and protocols of the Authorization Service

To enlarge the figure, follow the tips in How to use the document.

See also

Authorization Service in the functional components overview section

for more information the purpose and tasks.

2.4.2.1. 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 Identity Provider for authentication.

A Kubernetes Service from the type ClusterIP maps port 80 to the container port 8000.

Outbound

• HTTP to the Directory Manager to request read-only data for user accounts and user groups.

• HTTP to the Open Policy Agent to process authorization requests.

2.4.2.2. 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 Guardian Authorization HTTP REST API uses this port.

A Kubernetes Service from the type ClusterIP maps port 80 to the container port 8181.

Outbound

HTTP to the Guardian Management HTTP REST API to regularly fetch the current policy data.

2.4.2.3. Guardian Management HTTP REST API

Inbound

HTTP on port 80 provides REST API for CRUD operations on authorization objects, such as rules, namespaces, permissions, and roles, etc., and a policy bundle service for the 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 Guardian Authorization HTTP REST API 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 Identity Provider to retrieve certificates through OAuth 2.0.

See also

Wikipedia: OAuth (open authorization)

for more information about the open authorization standard.

2.4.2.4. 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 Guardian Management HTTP REST API for CRUD operations on authorization objects, using the previously received token.

2.4.3. Directory Manager

Inbound

HTTP on port 80 provides a REST API offering CRUD operations on 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 Management UI.

Outbound

LDAP connections to the Identity Store and Directory Service for authentication of UDM HTTP REST API access and CRUD operations on LDAP objects.

Fig. 2.18 shows the mentioned interfaces in an ArchiMate view.

Fig. 2.17 ArchiMate view for the interfaces and protocols of the Directory Manager

See also

Directory Manager in the functional components overview section

for more information about the purpose and tasks.

2.4.4. End User Self Service

The Self Service consists of the following components:

UMC Gateway

See UMC Gateway in section Management UI.

UMC Server

See UMC Server in section 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 Identity Store and Directory Service.

• LDAP connection to the Identity Store and Directory Service for one-way synchronization of LDAP data.

• HTTP to UMC Server in Management UI to request sending of user invitation email.

See also

End User Self Service in the functional components overview section

for more information about the purpose and tasks.

2.4.5. Identity Provider

The Identity Provider consists of the following components:

Keycloak

Inbound

• OpenID Connect interface to OpenID Connect Provider in Keycloak for authentication.

• OAuth 2.0 interface to OAuth 2.0 Provider in Keycloak for authentication.

• SAML interface to SAML Identity Provider in Keycloak for authentication.

Outbound:

• LDAP connection to the OpenLDAP server in the Identity Store and Directory Service 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.

See also

SSO protocols in Keycloak Server Administration Guide [4]

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.

Fig. 2.18 shows the mentioned interfaces in an ArchiMate view.

Fig. 2.18 ArchiMate view for the interfaces and protocols of the Identity Provider

To enlarge the figure, follow the tips in How to use the document.

See also

Identity Provider in the functional components overview section

for more information about the purpose and tasks.

2.4.6. 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 Identity Provider to retrieve 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 Directory Manager internal functions in the components section.

Fig. 2.19 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.

Fig. 2.19 Relationships between the LDAP Server and its inbound interfaces

Univention LDAP Notifier

The Univention LDAP Notifier is temporary, until the Provisioning consumer in 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 End User Self Service, about changes in the Identity Store and Directory Service.

Outbound

None

Fig. 2.20 shows the mentioned interfaces in an ArchiMate view.

Fig. 2.20 ArchiMate view for the interfaces and protocols of the Identity Store and Directory Service

See also

Identity Store and Directory Service in the functional components overview section

for more information about the purpose and tasks.

2.4.7. Intercom Service

For a description of the Intercom Service, refer to 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 Identity Provider for token exchange.

• Redis connection to an externally managed Redis database or Redis database cluster.

Fig. 2.21 shows the mentioned interfaces in an ArchiMate view.

Fig. 2.21 ArchiMate view for the interfaces and protocols of the Intercom Service

See also

Intercom Service in the functional components overview section

for information about the purpose and tasks.

2.4.8. 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 Identity Store and Directory Service to read and update user data.

• HTTP connections to Keycloak in 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.

Fig. 2.22 shows the mentioned interfaces in an ArchiMate view.

Fig. 2.22 ArchiMate view for the interfaces and protocols of the Management UI

To enlarge the figure, follow the tips in How to use the document.

See also

Management UI in the functional components overview section

for more information about the purpose and tasks.

2.4.9. 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

Fig. 2.23 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 (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 a S3-compatible storage to load generated Portal configuration.

• 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 Management UI to retrieve session information.

Portal Consumer

Inbound

None.

Outbound

• HTTP connection to the Consumer Messages HTTP REST API in 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 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.

Fig. 2.23 shows the mentioned interfaces in an ArchiMate view.

Fig. 2.23 ArchiMate view for the interfaces and protocols of the Portal Service

To enlarge the figure, follow the tips in How to use the document.

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 S3-compatible object storage in Univention Nubus for Kubernetes - Operation Manual [1]. From the storage’s perspective, all the connections are inbound.

See also

Portal Service in the functional components overview section

for more information about the purpose and tasks.

2.4.10. 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 Directory Manager.

• TCP connection to NATS database.

UDM Listener

Inbound

None.

Outbound

• TCP connection to the Univention LDAP Notifier in Identity Store and Directory Service to listen for notification about changes in the LDAP database.

• LDAP connection to the OpenLDAP server in Identity Store and Directory Service for one-way synchronization of LDAP data, and individual queries.

• HTTP connection to Events and Consumer API.

Fig. 2.24 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.

Fig. 2.24 ArchiMate view for the interfaces and protocols of the Provisioning Service

To enlarge the figure, follow the tips in How to use the document.

See also

Provisioning Service in the functional components overview section

for more information about the purpose and tasks.