4. Configuration#

The UCS@school ID Connector app offers the possibility to connect a UCS@school domain to another UCS@school domain and to provision it with user data. Plugins can extend the functionality of the UCS@school ID Connector. Depending on the needed API on the target system, a specific plugin is required.

If you completed all the steps from the Installation section, you already installed the necessary plugin for the connection to the ID Broker system on the UCS system.

In the following, you will now first learn about the configuration of the plugin and then the configuration of the Identity Provider (IDP) in your UCS@school domain.

As administrator of a school authority contact the operator of the ID Broker at school-authority-admin@univention-id-broker.com to start the registration process. Your registration request has to include the name of the school authority and the public FQDN of the school authority’s SAML IDP.

For the configuration of your system, the ID Broker team provides some values that are required for the configuration. The single configuration steps explain the respective values in detail. The values include a namespace ID, a username, and the corresponding password. In the following examples for commands and file contents, you must replace the corresponding placeholders ($NAMESPACEID, $USERNAME and $PASSWORD) with the concrete value that were given to you.

4.1. UCS@school ID Connector Plugin configuration#

Changes in the school authority’s IDM (LDAP directory) trigger the UCS@school ID Connector plugin for the UCS@school ID Connector. Changes can be, for example, the creation, modification, and deletion of UCS@school users and school groups.

Upon such a change in the IDM, the plugin uses the ID Broker’s Provisioning API to create, modify or delete user and group data on the ID Broker system accordingly. If an object is part of a school, that doesn’t yet exist on the ID Broker, the plugin creates the corresponding school on the ID Broker automatically.

To access the Provisioning API of the ID Broker, the plugin requires a namespace ID, a username and the corresponding password in its configuration:

The namespace ID is an ID that represents your school authority domain in the ID Broker system. All objects like users, school groups and schools that are provisioned to the ID Broker also contain the namespace ID, which makes the objects uniquely assignable to your system.
The ID Broker’s Provisioning API requires an authenticated access. The user account created for you has the appropriate permission for the API to create, modify or delete objects with your namespace ID only.

The username usually consists of the prefix provisioning- and the namespace ID. For example, a school authority with the namespace ID ExampleSchoolAuthority receives the username provisioning-ExampleSchoolAuthority from the ID Broker team.

4.1.1. Configuration for the use of an HTTP proxy#

The UCS@school ID Connector plugin supports the use of an HTTP proxy to access the Provisioning API of the ID Broker. Using an HTTP proxy is optional. If your environment only allows access to the Provisioning API through an HTTP proxy, you must set the Univention Configuration Registry Variable proxy/http on the UCS system. For information about how to set the variable, see Proxy access configuration.

If you set or change the variable after the installation of the UCS@school ID Connector, you have to reinitialize the UCS@school ID Connector afterwards by using the command in Listing 4.1.

Listing 4.1 Reinitialize UCS@school ID Connector#

$ univention-app reinitialize ucsschool-id-connector

4.1.2. Initial setup#

To configure the UCS@school ID Connector plugin, perform the following actions once:

The configuration file of the plugin requires the JSON format. Create the file school_authority.json, for example /root/school_authority.json, in a directory of your choice on the UCS@school ID Connector system. Remember, you must replace the placeholders $NAMESPACEID, $USERNAME and $PASSWORD with the appropriate values. The file has to contain the following content:

{
    "name": "$NAMESPACEID",
    "active": true,
    "url": "https://provisioning.production.univention-id-broker.com/",
    "plugins": ["id_broker-users", "id_broker-groups"],
    "plugin_configs": {
        "id_broker": {
            "password": "$PASSWORD",
            "username": "$USERNAME",
            "version": 1
        }
    }
}

Use the following two commands to send the JSON configuration to an API of the UCS@school ID Connector. This API also allows only authenticated access. Therefore, before calling it, replace the placeholder $ADMINPW with the password of the user Administrator from your domain. Run the adapted commands on the UCS system that has the app UCS@school ID Connector installed and where the file school_authority.json exists.

$ token=$(curl -X POST \
> https://$(hostname -f)/ucsschool-id-connector/api/token \
> -H "Content-Type:application/x-www-form-urlencoded" \
> --data-urlencode "username=Administrator" \
> --data-urlencode "password=$ADMINPW" | \
>  python3 -c 'import json,sys;print(json.load(sys.stdin)["access_token"])')

$ curl -X POST https://$(hostname -f)/ucsschool-id-connector/api/v1/school_authorities \
> -H "Content-Type:application/json" \
> -H "Authorization: Bearer $token" \
> --data-binary @school_authority.json

After you have successfully uploaded the JSON configuration, you can check the connection to the ID Broker’s Provisioning API with the initial_sync.py tool.

$ univention-app shell ucsschool-id-connector \
> /var/lib/univention-appcenter/apps/ucsschool-id-connector/conf/plugins/packages/idbroker/initial_sync.py --dry-mode

4.1.3. Connect schools to the ID Broker#

After the UCS@school ID Connector is configured, you can connect one or more new schools to the ID Broker with the manage_schools_to_sync.py tool.

Note

If the school authority has been configured already with an ID Broker plugin prior to version 1.3.16 the existing behavior is kept, meaning all existing and future schools are synchronized.

The following commands have to be executed to add the schools ou1 and ou2 to the ID Broker, which are not yet connected to the ID Broker.

$ systemctl stop univention-appcenter-listener-converter@ucsschool-id-connector.service
$ univention-app shell ucsschool-id-connector
$ cd /var/lib/univention-appcenter/apps/ucsschool-id-connector/conf/plugins/packages/idbroker/
$ ./manage_schools_to_sync.py add_schools --school_authority Traeger2 "ou1" "ou2"
$ exit
$ systemctl start univention-appcenter-listener-converter@ucsschool-id-connector.service

This will synchronize all users without groups of ou1 and ou2, then synchronize all groups without members and finally adapt all group memberships. You can use "*" as a wildcard character in your school names. When the script is finished, all following user & group updates for ou1 and ou2 and all other schools which where configures earlier will be synced to the ID Broker. To handle errors that happen during synchronization, please refer to section Error handling for manage_schools_to_sync.py. The service univention-appcenter-listener-converter@ucsschool-id-connector.service is paused because during the initial synchronization the UCS@school ID Connector operates in a special mode not suitable for normal operation.

You can add all existing schools using the flag --all_schools. With this option, all future schools need to be added manually. Alternatively you can pass "*" as the SCHOOLS argument to add all existing and future schools use to the ID Broker. Use both options with care as they will add all schools to the ID Broker.

For more information refer to section Error handling for manage_schools_to_sync.py.

Note

Please note that the synchronization time can vary greatly depending on the number of users and the nature of the group memberships. As a rule of thumb, an initial synchronization duration of 6-7 days can be assumed for approximately 85,000 user accounts and 25,000 school groups. Consider opening a screen session.

4.1.4. Removal of schools from the ID Broker#

Schools can be removed from the ID Broker by using the same tool.

$ univention-app shell ucsschool-id-connector
$ cd /var/lib/univention-appcenter/apps/ucsschool-id-connector/conf/plugins/packages/idbroker/
$ ./manage_schools_to_sync.py remove_schools --school_authority Traeger2 "ou1" "ou2"

This will remove the schools ou1 and ou2 from the school authority configuration and remove them from the ID Broker.

To remove a school name from the configuration, it needs to match exactly. The argument "ou*" will only match "ou*" in the configuration not "ou1". If "ou*" can be removed from the configuration, all matching schools will be removed from the ID Broker. Matching schools will not be removed if they still match with another school name in the configuration. If you previously added "ou1" and "*" to the configuration and remove "*", "ou1" will not be deleted since it is still configured to be synced.

Alternative to removing the schools by name, you can use the flag --all_schools to remove all schools which were to the school authority configuration from the school authority configuration and the ID Broker system. Use this option with care.

Note

In case you are familiar with the configuration of the UCS@school ID Connector: A school to authority mapping is not needed since all schools are synced to the ID Broker. You will find the connected schools in the school_authority.json.

4.2. Login with SSO using the ID Broker#

Once you configured the UCS@school ID Connector to actively provision users and groups to the ID Broker system, you need to setup a trust context between the IDP of the school authority and the ID Broker system to enable the login for a school through SSO with the ID Broker.

4.2.1. Setup with Univention Keycloak as Identity Provider#

If you are using Univention Keycloak as your IDP (see the Keycloak App documentation), you can use a command line tool to setup the trust context. The command line tool has defaults which work for the case when the UCS@school ID Connector is installed on the same system as Keycloak. If the Keycloak FQDN or Keycloak path is different from the default refer to the --help message of the tool for the corresponding optional arguments.

We recommend the Open ID Connect protocol. Open ID Connect requires that your Keycloak instance is internet accessible. If that is not the case in your environment, you can use the SAML protocol which does not have this requirement.

If Open ID Connect is used, run the following command:

$ /var/lib/univention-appcenter/apps/ucsschool-id-connector/conf/plugins/packages/idbroker/create_idbroker_client.py \
> --authority "$NAMESPACEID" oidc --secret="$PASSWORD"

If SAML is used, run the following command:

$ /var/lib/univention-appcenter/apps/ucsschool-id-connector/conf/plugins/packages/idbroker/create_idbroker_client.py \
> --authority "$NAMESPACEID" saml

Warning

You need to run the script on the same server as your Keycloak instance. If your UCS@school ID Connector is running on a different server, you can copy the script to your Keycloak server.

4.2.2. Setup SAML with SimpleSAMLphp#

Warning

This section is deprecated. With UCS 5.2, Keycloak will become the standard IDP for SAML and OpenID Connect authentication and will replace SimpleSAMLPHP and Kopano Connect.

Run the following steps on the UCS system with the UCS@school ID Connector app installed as user root:

The SAML assertion issued by your IDP must also contain the entryUUID attribute to work with the ID Broker. Use the following command to add this attribute to the SAML assertion:
```
$ udm saml/idpconfig modify \
> --dn "id=default-saml-idp,cn=univention,$(ucr get ldap/base)" \
> --append "LdapGetAttributes=entryUUID"
```
To activate automatic variable substitution in all of the following commands, set the environment variable NAMESPACEID. Replace in the following example ExampleSchoolAuthority with the corresponding value.
```
$ export NAMESPACEID="ExampleSchoolAuthority"
```
Download the configured metadata for this school authority from the authentication service called Keycloak, that runs on the ID Broker system. Run the following command to download the metadata and store it in the file metadata.xml:
```
$ curl https://sso-broker.production.univention-id-broker.com/auth/realms/ID-Broker/broker/$NAMESPACEID/endpoint/descriptor > metadata.xml
```

Finally, you must introduce the ID Broker’s service Keycloak as a service provider to the local IDP. Run the following command to save the appropriate configuration in the IDM of the school authority:

$ udm saml/serviceprovider create \
> --position "cn=saml-serviceprovider,cn=univention,$(ucr get ldap/base)" \
> --set serviceProviderMetadata="$(cat metadata.xml)" \
> --set AssertionConsumerService="https://sso-broker.production.univention-id-broker.com/auth/realms/ID-Broker.com/broker/$NAMESPACEID/endpoint" \
> --set Identifier="https://sso-broker.production.univention-id-broker.com/auth/realms/ID-Broker/broker/$NAMESPACEID/endpoint/descriptor" \
> --set isActivated=TRUE \
> --set simplesamlNameIDAttribute=entryUUID \
> --set simplesamlAttributes=TRUE \
> --set attributesNameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri" \
> --set LDAPattributes=entryUUID

4.3. Single logout with the ID Broker#

When a user signs out at a service, the service can end the complete single sign-on session: the session at the service, the session at the ID Broker, the session at your IDP, and with it the session in your Portal and in UMC.

Single logout works along the same chain as the login, but in the opposite direction. Every link of the chain has to use OpenID Connect and has to notify the next one:

The service notifies the ID Broker.

The service provider has to end the session at the Keycloak of the ID Broker. As a school authority, you don’t have to configure anything for this step. Services that don’t notify the ID Broker only end their own session, the sessions at the ID Broker and at your IDP stay active.
The ID Broker notifies your IDP.

This requires that the trust context between your IDP and the ID Broker uses OpenID Connect. See Use OpenID Connect between your IDP and the ID Broker.
Your IDP notifies the Portal and UMC.

This requires that the Portal and UMC sign in with OpenID Connect. See Use OpenID Connect for the Portal and UMC.

If one link of the chain uses SAML, the sign-out stops at that link. The user then still has an active session in the components after it.

4.3.1. Use OpenID Connect between your IDP and the ID Broker#

The ID Broker only propagates the sign-out to an IDP that it connects through OpenID Connect. With a SAML trust context, the session at your IDP stays active.

Set up the trust context with OpenID Connect as described in Login with SSO using the ID Broker. The create_idbroker_client.py tool configures the required sign-out endpoints together with the OpenID Connect client.

If you already registered your IDP with SAML, contact the operator of the ID Broker at school-authority-admin@univention-id-broker.com and ask them to change the registration of your IDP to OpenID Connect. Remember that OpenID Connect requires that your Keycloak instance is accessible from the internet.

4.3.2. Use OpenID Connect for the Portal and UMC#

By default, the Portal and UMC use SAML for single sign-on after you install the Keycloak app. Keycloak only ends the session of the Portal and of UMC upon a sign-out at the ID Broker, if they sign in with OpenID Connect.

To activate OpenID Connect for the Portal and UMC, follow OpenID Connect for single sign-on in the Nubus for UCS Operation Manual. Run through the steps on every UCS system that provides the Portal or UMC to your users.

If you run more than one UMC Server, or if you activated multiprocessing for UMC through the UCR variable umc/http/processes, UMC additionally needs a database for the session storage. Without it, the UMC Server can’t process the sign-out notification for sessions that another process or another system handles. For the configuration of the session storage, see Back-channel sign-out in the Nubus for UCS Operation Manual.

4.3.3. Verify the single logout#

To verify the setup, use the following steps:

Sign in to the Portal with a user of a connected school.
Open a service that uses the ID Broker and that provides a sign-out, and sign in through the ID Broker.
Sign out at the service.
Reload the Portal. The Portal must show you as signed out.

ID Broker manual for school authorities

Configuration

Contents

4. Configuration#

4.1. UCS@school ID Connector Plugin configuration#

4.1.1. Configuration for the use of an HTTP proxy#

4.1.2. Initial setup#

4.1.3. Connect schools to the ID Broker#

4.1.4. Removal of schools from the ID Broker#

4.3. Single logout with the ID Broker#

4.3.1. Use OpenID Connect between your IDP and the ID Broker#

4.3.2. Use OpenID Connect for the Portal and UMC#

4.3.3. Verify the single logout#