2.1. Central Navigation API

Deployment — Kubernetes

This page refers to the Nubus for Kubernetes deployment.

In the Kubernetes deployment, Nubus provides the Portal Service as a single point of entry for end users.

After sign-in to the Portal, users can find tiles with links to applications to which they have access permissions. The Central Navigation API provides an interface to retrieve the navigation links from the portal for a specific user. A third-party application can use this information to enhance its own navigation menu, allowing the user to switch between applications in the browser with a single click. The Central Navigation API is part of the Portal Service.

This page describes how to use the Portal’s Central Navigation API in a third-party application, how to call the API, what parameters it needs, and data it returns.

See also

Portal Service

for architecture information of the Portal Service in Univention Nubus for Kubernetes - Architecture Manual [1].

2.1.1. Configure navigation entries

New in version 1.13.0.

The Central Navigation API supports the configuration of navigation entries independent of the main portal tiles. Operators can customize which applications appear in the central navigation without affecting the main portal view.

By default, when you don’t have specific central navigation entries configured, the API returns all portal entries that the user has access to, maintaining backward compatibility with previous versions.

To configure specific entries for central navigation, modify the centralNavigation property of a portal object. This property accepts a list of distinguished names (DNs) that point to portals/entry objects in the directory service that you want the central navigation to show to the user.

You can configure the entries through the following ways:

UMC Web Interface

Use the Portal management module in the Management UI to configure the Central Navigation section of a portal.

To configure the central navigation entries in the UMC, use the following these steps:

1. Open the Portal management module in the Management UI.

2. Select the portal that you want to configure. The name of the default main portal is domain.

3. In the portal settings, go to the General tab.

4. You can add or remove portal entries in the Central Navigation section.

Programmatically through UDM

To specify the entries that appear in the central navigation, you need to modify the centralNavigation property of a portal object.

Example

The example in Listing 2.1 shows how to modify the centralNavigation property of a portal object using the UDM HTTP REST API with a PATCH request. The curl command configures the central navigation to show only the Keycloak entry. Replace the DN for the portal entry with a URL-encoded string for the object DN as needed for your environment, for example cn=domain,cn=portal,cn=portals,cn=univention,dc=example,dc=com. For the initialization of the used environment variables HOSTNAME, USER, and PASSWORD, see Listing 2.19.

For a more detailed description of the UDM HTTP REST API, see UDM HTTP REST API.

Listing 2.1 Add an entry to the central navigation

$ export MODULE="portals/portal"
$ export DN="<URL encoded string for object DN>"
$ curl \
   --user ${USER}:${PASSWORD} \
   --request PATCH \
   --header "Accept: application/json" \
   --header "Content-Type: application/json" \
   --data \'{
     "properties": {
       "centralNavigation": ["cn=keycloak,cn=entry,cn=portals,cn=univention,dc=example,dc=com"]
     }
   }\' \
   "https://${HOSTNAME}/univention/udm/${MODULE}/${DN}"

Important

For a portal entry to appear in the Central Navigation API response, you need to ensure that the portal entry belongs to a portal category.

2.1.2. Authentication

The Central Navigation API and the third-party application use a shared-secret for authentication. Upon deployment, Nubus creates the shared secret and stores it in release-portal-server-central-navigation-shared-secret.

For the HTTP request, use the HTTP Basic authentication scheme with the HTTP Authorization request header. The credentials is a Base64 encoded string which consists of username:shared-secret. The username is the user account’s uid.

To configure a custom shared-secret for the Portal Service, use the following steps:

1. Create an extraSecret with a name name-for-shared-secret and ensure it has the key authenticator.secret.

2. Add the lines from Listing 2.2 to your custom_values.yaml. You need to provide the name of a Kubernetes secret. Inside that secret the key authenticator.secret holds the value of the shared secret.

   Listing 2.2 Define shared-secret for Central Navigation API in Nubus for Kubernetes

   nubusPortalServer:
     portalServer:
       centralNavigation:
         authenticatorSecretName: "name-for-shared-secret"
   

See also

HTTP authentication - HTTP | MDN

for information about the HTTP framework for access control and authentication.

2.1.3. Request and response

The Central Navigation API accepts an HTTP GET request with the HTTP Authorization request header and returns JSON object data.

Request

Endpoint:

/portal/navigation.json

FQDN:

https://portal.global.domain/

URL:

https://portal.global.domain/portal/navigation.json

For the global domain, see the global.domain value in your custom_values.yaml file in your Nubus Helm Chart.

For the request header for authentication, see Authentication.

Response

The response is a JSON object with the following fields:

identifier:

A unique identifier for the navigation item.

icon_url:

The URL to the icon in SVG format.

display_name:

The label of the link.

link:

The destination URL of the link.

target:

The browsing context in which the browser opens the link. Corresponds to the target property of <a> tags in HTML.

keywords:

It’s usually empty.

The response structure includes categories and entries. If Nubus has the central navigation configured with specific entries, the Central Navigation API only returns those entries—filtered by user permissions. If Nubus has no central navigation entries configured, the Central Navigation API returns all portal entries accessible to the user.

See also

<a>: The Anchor element - HTML: HyperText Markup Language | MDN

for information about values for the target attribute.

Example

You can use cURL to request the data. The following listings show examples for an authenticated request to the API and an anonymous request to the API.

Authenticated

Listing 2.3 Central Navigation API authenticated request for a particular user

$ curl \
   'https://portal.<global.domain>/univention/portal/navigation.json' \
   -u "default.admin:shared-secret" \
   | jq

Anonymous

Listing 2.4 Central Navigation API request for anonymous user

$ curl \
   'https://portal.<global.domain>/univention/portal/navigation.json' \
   -u "default.user:some-wrong-secret" \
   | jq

Retrieve shared secret for use in example

To retrieve the shared-secret from the Kubernetes secret store, use the commands in Listing 2.5.

Listing 2.5 Retrieve shared secret from Kubernetes secret store

$ export NAMESPACE_FOR_NUBUS="Set to your Kubernetes namespace of Nubus"
$ export RELEASE_NAME="The Helm Chart release name"

$ kubectl --namespace "$NAMESPACE_FOR_NUBUS" \
   get secrets \
   -o json \
   "$RELEASE_NAME"-portal-server-central-navigation-shared-secret \
   | jq -r '.data."authenticator.secret"' \
   | base64 -d

2.1.4. Deactivate API

The default deployment of Nubus for Kubernetes activates the Central Navigation API. To deactivate it, add the lines from Listing 2.6 to your custom_values.yaml.

Listing 2.6 Define shared-secret for Central Navigation API in Nubus for Kubernetes

nubusPortalServer:
  portalServer:
    centralNavigation:
      enabled: false