3. Configuration#

3.1. Choose who sees the portal tile#

The installation adds a School Accounts tile to the Univention Portal and shows it to everyone, including visitors who aren’t signed in. Selecting the tile asks them to sign in first. The tile doesn’t grant any permission. The app shows every user only what their roles allow, as described in Roles and permissions.

To show the tile only to the users of the school DEMOSCHOOL, add the Domain Users DEMOSCHOOL group of that school to the portal entry:

Listing 3.1 Show the portal tile only to the users of one school#

$ univention-directory-manager portals/entry modify \
    --dn "cn=ucsschool-accounts,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \
    --append allowedGroups="cn=Domain Users DEMOSCHOOL,cn=groups,ou=DEMOSCHOOL,$(ucr get ldap/base)"

To add further schools, repeat the --append option for each of them.

3.2. Point the portal tile to another system#

The domain has one School Accounts tile, no matter on how many systems you install the app. The first installation in the domain creates the tile and links it to the system it runs on. Later installations on other systems leave the tile unchanged.

To let the tile open the app on another system, for example school-accounts.example.com, change the link of the portal entry:

Listing 3.2 Point the portal tile to the app on another system#

$ univention-directory-manager portals/entry modify \
    --dn "cn=ucsschool-accounts,cn=entry,cn=portals,cn=univention,$(ucr get ldap/base)" \
    --set link='"en_US" "//school-accounts.example.com/univention/ucsschool/ucsschool-accounts/ui/"'

3.3. User visibility#

This preview doesn’t yet support configuring which users appear in the list view. The list view shows a user when the Guardian grants the signed-in user at least one permission on them. For the permissions of each role, see Roles and permissions.

3.4. Sessions#

After a user signs in, the School Accounts app keeps the session in an encrypted browser cookie. The server stores no session data, so a session survives both a restart of the app and an app update.

3.4.1. Session lifetime#

A session lasts at most 8 hours. Keycloak’s own session limits usually end it earlier: the realm’s SSO Session Idle and SSO Session Max, or Client Session Idle and Client Session Max if the client overrides them. Whichever limit runs out first sends users back to the sign-in page.

Signing out also ends the session in Keycloak. A copy of the session cookie keeps working until the app next renews the sign-in against Keycloak, which happens within the lifetime of an access token.

Each host encrypts its cookies with its own secret, so users who switch to the app on another UCS system pass through Keycloak again. While their Keycloak session is open, they see only a redirect and don’t have to enter their credentials.

3.4.2. End all sessions on a host#

To end every app session on a host, write a new secret into the session.secret file and restart the app:

Listing 3.3 Replace the session secret#

$ openssl rand -hex 32 > \
    /var/lib/univention-appcenter/apps/ucsschool-accounts/conf/session.secret
$ univention-app restart ucsschool-accounts

This doesn’t sign users out of Keycloak, so their next request takes them back into the app without a credential prompt. To force users to authenticate again, end their sessions in Keycloak. Don’t delete the session.secret file: the app generates it only during installation and refuses to start without it.

3.4.3. Change the client secret#

The app authenticates to Keycloak with the client secret in /var/lib/univention-appcenter/apps/ucsschool-accounts/conf/client.secret. The secret belongs to the domain, and Keycloak holds the authoritative copy. Every installation and every app update adopts the secret that Keycloak holds.

To change the secret, regenerate it for the client ucsschool-accounts-ui in the Keycloak administration console. Then write the new secret into the client.secret file on every host that runs the app, and restart the app there:

Listing 3.4 Replace the client secret on a host#

$ printf '%s\n' "NEW_SECRET" > \
    /var/lib/univention-appcenter/apps/ucsschool-accounts/conf/client.secret
$ univention-app restart ucsschool-accounts

Replace NEW_SECRET with the secret from Keycloak. Until you have updated a host, it can’t sign users in.

3.5. App settings#

This section is a reference for all app settings of the School Accounts app. You can configure the settings with the univention-app command or in the app settings dialog of the App Center UMC module.

The Univention App Center restarts the app after you change any setting.

3.5.1. Kelvin#

ucsschool-accounts/kelvin/url#: Defines the hostname of the system that runs the Kelvin REST API. If unset, the app uses the fully qualified domain name of the system that it runs on.

3.5.2. Logging#

ucsschool-accounts/logging/level#: Sets the log level of the app. Possible values are TRACE, DEBUG, INFO, WARNING, ERROR, and CRITICAL, with INFO as the default. The values are case-insensitive. DEBUG adds the technical context of each request, which helps with a bug report. TRACE additionally logs the start and end of every request. A value that names no level doesn’t keep the app from starting: the app logs a warning and uses INFO.

ucsschool-accounts/logging/structured#

If set to True, the app writes each log record as a single JSON object, which a log aggregator can parse without a pattern. The default is False, which writes the format described in Log format.

You can’t configure the format itself. Both variants follow the Univention log format, so that logs stay consistent across the products of a domain.

3.5.3. Portal#

ucsschool-accounts/frame-ancestors#: Defines the sites allowed to show the application inside a frame, as a space separated list of sources of the Content-Security-Policy directive frame-ancestors. The portal opens the application inside a frame, so the list must contain every system whose portal links to it. The default 'self' covers a portal on the UCS system where you installed the application. Add the URL of any other system, for example https://primary.example.org. Without a matching entry, the browser refuses to show the application inside the portal.

3.5.4. Authentication#

ucsschool-accounts/oauth/keycloak-uri#: Defines the base URI of the Keycloak server that signs users in. If unset, the app builds the URI from the hostname in the Univention Configuration Registry (UCR) variable keycloak/server/sso/fqdn, and if that is unset too, from ucs-sso-ng.DOMAIN_NAME.

School Accounts

Configuration

Contents