ID Broker operations manual

School authorities

3. School authorities#

This chapter explains how to add new school authorities to the ID Broker and later remove them.

3.1. Add a new school authority#

To add a new school authority to the ID Broker, you must first create a user account for the new school authority in the LDAP directory. This is a normal UCS user account, but the username must meet certain criteria.

The username requires the prefix provisioning- followed by the namespace ID of the school authority. You must specify the namespace ID. It must be unique across the ID broker domain and must only consist of lowercase and uppercase letters and digits. You and the school authorities use the namespace ID in several places during the configuration process. Therefore, use a human-readable value.

If for example the namespace ID of the school authority is ExampleSchoolAuthority, then the username must be provisioning-ExampleSchoolAuthority.

Adapt the system of the Provisioning API so it allows the school authority to access it.

Provide the following information to the school authority once you complete the configuration steps below.

  1. The namespace ID for the school authority, for example ExampleSchoolAuthority

  2. The password for the user account created above.

  3. The Keycloak URL of the ID broker. For productive operation the URL is: https://sso-broker.production.univention-id-broker.com/auth/realms/ID-Broker/broker/$NAMESPACEID/endpoint/descriptor

    Replace the placeholder $NAMESPACEID with the respective namespace ID of the school authority.

3.1.1. Add a new school authority to Keycloak#

The chapter Backup - SSO Service - Keycloak already describes how to configure Keycloak through Ansible. Use the following steps in the file system folder keycloak on the Ansible system for each school authority, that you want to add. In the commands and configuration entries below, replace the placeholder $NAMESPACEID with the respective namespace ID of the school authority.

  1. Download the SAML IDP metadata from the schools SAML IDP. Make sure that the SAML IDP of the school authority is accessible via the internet. In case the SAML IDP is only available on the school’s intranet, ask the school authority to download the metadata for you. Simply ask the school authority for the FQDN of their SAML IDP. As a rule of thumb, the FQDN usually is ucs-sso.$DNSDOMAIN_OF_SCHOOLAUTHORITY. In the following command you must specify the FQDN of the SAML IDP instead of $IDP_FQDN:

    $ curl https://$IDP_FQDN/simplesamlphp/saml2/idp/metadata.php \
> -o schools_saml_IDP/$NAMESPACEID_metadata.xml

  2. Edit schools_saml_IDP/idps.yml in the Keycloak folder to add a new entry for the new school authority.

    For the school authority, add a new section below register_idps corresponding to the following example. School authorities configure their UCS@school ID connector so that their provisioned users store the namespace ID of the school authority in the ucsschoolSourceUID LDAP attribute.

    An example configuration looks like this:

    register_idps:
  - alias: $NAMESPACEID
    ucsschoolSourceUID: $NAMESPACEID
    path: schools_saml_IDP/$NAMESPACECID_metadata.xml

  3. Updating the Keycloak configuration

    To activate the new school authority in Keycloak, please switch back to the Backup - SSO Service - Keycloak chapter and perform the next steps there. If you have already completed the installation of Keycloak and are just adding a new school authority, it is sufficient to run the Ansible playbook:

    $ ansible-playbook -i hosts.ini main.yml

3.2. Remove a school authority#

Removing a school authority from the ID-Broker can be done by the remove-school-authority script. However, the script can only be run on a primary server and is intended to be run in its default interactive mode, which provides a guided deletion for the specified school authority.

Additionally, the script offers two alternative run modes:

  1. The dry-run mode can be activated by providing the --dry-run command-line interface argument and will list the objects that would be deleted when run in the interactive mode without actually removing them.

  2. The force mode can be activated by providing the --force command-line interface argument and will skip any non-critical user interaction.

For additional information please consult the script’s help text accessible via:

$ remove-school-authority -h

Alternatively it is possible to remove a school authority manually as well using the following process:

  1. Remove the school authority’s identity provider from Keycloak.

  2. Delete the provisioning user in LDAP.

  3. Delete all school OUs and any objects they contain.

As the remove-school-authority script does automate this process, it is advised to default to it rather than doing a manual deletion.

On this page