2.1. Central Navigation API

Nubus for Kubernetes 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 section 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. 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.1 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.1 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.2. Request and response

The Central Navigation API accepts a 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.

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.2 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.3 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.4.

Listing 2.4 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 get secrets \
   --namespace "$NAMESPACE_FOR_NUBUS" \
   -o json \
   "$RELEASE_NAME"-portal-server-central-navigation-shared-secret \
   | jq -r '.data."authenticator.secret"' \
   | base64 -d

2.1.3. Deactivate API

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

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

nubusPortalServer:
  portalServer:
    centralNavigation:
      enabled: false