ID Broker manual for school authorities

Download PDF

Configuration

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.

Please perform the following actions once to configure the UCS@school ID Connector plugin:

  1. 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,
        }
    }
}

  2. 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" | \
>  python -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

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

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"
$ 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.

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.

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

  1. 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"

  2. 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"

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

  4. 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
On this page