1. Introduction#
1.1. About this document#
Target audience of the document are persons with technical skills; focus is on Univention Developers, Univention Operations and (partly) Service Providers.
Knowledge about UCS and UCS@school is a prerequisite.
The document is updated on a regular base to follow the current state of the implementation.
In a future release the Univention ID Broker will include a process to revert pseudonymization service. This is not yet part of the architecture document.
Security related questions will be reviewed in each chapter and not separately.
1.2. Big Picture - what is the Univention ID Broker?#
The main objective of the Univention ID Broker is to ease the integration between identities of learners and teachers managed by school authorities or federal states and the various service providers for educational purposes with respect to the data protection regulations in Europe.
Fig. 1.1 Overview of the involved components of the ID Broker and external Systems.#
To reach this goal the service will ensure:
Single sign-on for end users between the identity provider (IDP) of a school authority / federal state (in the document summarized under the term school authority) and service providers (educational SaaS offerings).
Only one configuration step to connect with the ID Broker both for IDPs and service providers (there is no need to configure each IDP with each service).
Service specific pseudonyms instead of global identifiers for users to ensure that an users activities in the different services can’t be combined to a “profile” of the user.
To give end users a “complete” environment from scratch, service providers can retrieve information about the role and the courses of users.
For services which must not get access to clear text information about a user, the ID Broker will provide (de-)pseudonymization services.
To ensure data protection, the ID Broker environment will store only a minimal data set.
1.3. Use Cases#
1.3.1. Overview#
The list in this document describes the high level use cases for end users, service providers and administrators of identity providers.
1.3.2. End user single sign-on#
As end user of an school authority, I’m authenticated in the environment of my school authority (typically by logging in to the Univention Portal hosted by my school authority). I want to access a SaaS without entering login & password, but based on a secure single sign-on.
1.3.3. End user comfort in SaaS offering#
After entering the SaaS offering, as an end user I want the SaaS offering to provide me the services which are appropriate for my role and learning context. This means it displays my name, offerings related to my role as teacher and/or learner, and a work environment prepared to connect to other end users participating in the same groups / courses. I want to identify group / course members based on their names.
1.3.4. Onboarding of new IDPs#
As administrator of a school authority or federal state IDP, I want to have only one technical onboarding (configuration) with the ID Broker environment to implement the above listed end user use cases for all SaaS offerings / service providers. This onboarding should be as easy as possible while providing a secure and trustworthy connection. The needed steps are well documented.
As administrator I also want to have clear responsibilities in case a problem occurs and troubleshooting needs to be done.
As person responsible for the IDP and the information stored in it, I want to be sure that the handling of the data is done well (only minimal data is transferred, systems are secure) and the legal framework has been clarified (i.a. a data processing contract is signed).
1.3.5. Onboarding of new Service Providers#
As administrator of a service provider, I want to have only one technical onboarding (configuration) with the ID Broker environment to implement the above listed end user use cases for all IDPs (school authorities and federal states). This onboarding should be as easy as possible while providing a secure and trustworthy connection. The needed steps are well documented.
As administrator I also want to have clear responsibilities in case a problem occurs and troubleshooting needs to be done.
As person responsible for the provided Service and the information stored in it, I want to be sure that the handling of the data is done well (only minimal data is transferred, systems are secure) and the legal framework has been clarified (i.a. a data processing contract is signed).
1.3.6. Operation if the ID Broker environment#
As operator of the ID Broker environment I want to know how to install the environment, which services it has to provide and where to find information about the services, their architecture / modules, KPIs about the health state of the services and information where to find log messages. I expect to have a way to do a fully automated setup.
1.3.7. Univention as software vendor#
As software vendor I want to maintain a solution which has as much overlap to my existing and established software stack as reasonable for the given use cases. I want to have the same development process as for other modules, including build and test procedures.
1.4. Requirements and demarcation#
1.4.1. Requirements#
1.4.1.1. Functional requirements#
Single sign-on (SSO) for end users while accessing service providers with school authority as leading identity provider.
Information retrieval for service providers about the group memberships of an authenticated current user: granting access to the information is based on the users SSO session, so only information about a currently authenticated user can be retrieved.
The unique identifier of an users has to be an individual pseudonym for each service provider: in case of a data breach of a service provider, there must not be any individual identifier of an user that allows to make a connection to the users data at any other service provider. It might be needed to extend this pseudonymization also to group identifiers.
For security reasons, user authentication / “session” don’t last more than 6 hours. Afterwards the IDP of the school authority needs to be involved and might extend the session without asking the end user for the password.
Provisioning of user and group information is limited to the scope of the school authority which authenticated against the Provisioning API.
Any data retrieval API (initially the “Self-disclosure API”) limits access to data to the scope of the authenticated user: To access the API an authentication as end user is needed, the data to retrieve is data about the user and his or her context (i.e. learning groups). Detailed requirements will be added in the individual chapters.
Adding school authorities is done in one configuration step for the school authority and the ID Broker operator and provides the school authorities users access to all current and future service providers.
Adding service providers is done in one configuration step for the service provider and the ID Broker operator and provides access to the service for users of all current and future school authorities.
In a future version of the document a service to de-pseudonymize a user will be introduced.
1.4.1.2. Nonfunctional requirements#
The solution has to follow European laws, this includes but is not limited to:
Data processing agreements have to be concluded with both service providers and school authorities. This is not part of the technical implementation but will be done as part of the onboarding process.
All data processing needs to be done under European jurisdiction (i.e. contracted operators and service providers need to be located in the EU).
Data storage is limited to the absolute needs for operation and functionality.
UCS versions
School authority deployments need to support initially UCS 4.4 and in 2022 UCS 5.0.
ID Broker deployment shall be based on UCS 5.0 (to avoid a later migration from UCS 4.4 to UCS 5.0).
Leading source of information is the school authority.
Number of named users is expected to be about 100.000 (one hundred thousand) initially and 1.000.000 (one million) by the end of 2022.
For all end user use cases the ID Broker has to ensure suitable response times and availability:
Relevant for these use cases are single sign-on and user information retrieval.
Suitable response times are expected as <0.5 seconds in >90% of all requests under peak load.
Peak load is initially expected to be 10% of named users per hour. This is:
Initially: 150 end user logons and information retrieval requests per minute.
By the end of 2022: 2000 end user logons and information retrieval requests per minute.
Availability of 99.99% of “learning hours”: Monday to Sunday 5:00 - 23:00.
For provisioning use cases availability and processing requests are lower:
Outages of less than 5 Minutes can occur at any time
Peak loads to be handled are:
Initial provisioning of a large school authority: 500.000 new identities and corresponding groups in 5 days.
Change of all named users and corresponding groups in 6 weeks (summer holidays).
Processed data has to be covered by contracts following EU data protection regulations (Vertrag zur Auftragsdatenverarbeitung).
1.4.2. Demarcation#
The ID Broker must not:
introduce a new account and/or new authorization information (new password) for users.
give full access to stored data to any service provider (access is only allowed in the context of an authenticated end user).
store any information not needed to process the defined use cases. Data not to be stored includes but is not limited to: passwords, contact information or any personal data, long term logs or any data that might be used for movement profiles not needed for fault analysis)
The ID Broker should not:
be visible to the end users - the ID Broker mediates, but is only visible to administrators. Exceptions might occur in case of error handling.
1.5. Stakeholder#
Stakeholders who have interest in the ID Broker and whose interests should be taken into account:
School authorities
End users (learners / students, lecturers / teachers, parents / legal guardians)
Service providers
Univention software development
Univention operations