1. Self-disclosure API in context of ID Broker

The Univention ID Broker eases 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.

To use the API and request information about users like students and teachers, the service provider needs an authentication token. The user’s browser receives the authentication token from the Identity Provider (IDP) of their school authority and passes it to the service provider. With the authentication the service provider can then request additional information about the user from the Self-disclosure API.

1.1. Sequence diagram

Figure 1.1 shows the complete flow of a user that logs in to a service through a school’s portal website. The ID Broker provides user data through the Self-disclosure API. Step 8 in Figure 1.1 uses the Self-disclosure API.

Figure 1.1 ID Broker sequence: authentication and user data retrieval sequence

The Self-disclosure API only returns service provider specific pseudonyms instead of real personal information. Two different service providers receive different pseudonyms for the same real user.

Note

At the time of writing some user data isn’t pseudonymized yet.

1.2. Authentication token

In step 6 the Univention ID Broker responds with an authentication token for the user that wants to sign in. A token looks like the following example:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJuRHBjM2szTkFzZGc4YndJbGRZRnk5MjVQYWxBR2g5bDNnYjJxZUhhdnYwIn0.eyJleHAiOjE2NDM4MDE1ODQsImlhdCI6MTY0MzgwMTI4NCwiYXV0aF90aW1lIjoxNjQzNzk3MjkyLCJqdGkiOiIzNjk2OTJmYi0yNTA2LTQ0NDYtOTlhMC1hMzYxZGJkMWM2YTQiLCJpc3MiOiJodHRwczovL2xvZ2luLmtleWNsb2FrLmlkYnJva2VyLmludHJhbmV0L2F1dGgvcmVhbG1zL0lELUJyb2tlciIsImF1ZCI6ImFjY291bnQiLCJzdWIiOiJmOmQ3ZTRjZTE0LWNmMDctNGUxZi04MDNjLWRlOTk2ZGQyNGRhNzo1YmY2NDRlNi0xNzhlLTEwM2MtODQ1MS00OWI0ZjU2YjFiYzAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJweXRob24tY2xpZW50Iiwic2Vzc2lvbl9zdGF0ZSI6IjEzNGVhZTgzLTk3MGEtNGQzYS04NGE1LWE4ZTMzMWJlN2QyMiIsImFjciI6IjAiLCJhbGxvd2VkLW9yaWdpbnMiOlsiIl0sInJlYWxtX2FjY2VzcyI6eyJyb2xlcyI6WyJvZmZsaW5lX2FjY2VzcyIsImRlZmF1bHQtcm9sZXMtaWQtYnJva2VyIiwidW1hX2F1dGhvcml6YXRpb24iXX0sInJlc291cmNlX2FjY2VzcyI6eyJhY2NvdW50Ijp7InJvbGVzIjpbIm1hbmFnZS1hY2NvdW50IiwibWFuYWdlLWFjY291bnQtbGlua3MiLCJ2aWV3LXByb2ZpbGUiXX19LCJzY29wZSI6Im9wZW5pZCBlbWFpbCBwcm9maWxlIiwic2lkIjoiMTM0ZWFlODMtOTcwYS00ZDNhLTg0YTUtYThlMzMxYmU3ZDIyIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJuYW1lIjoic3R1ZGVudCBvbmUgb25lIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNWJmNjQ0ZTYtMTc4ZS0xMDNjLTg0NTEtNDliNGY1NmIxYmMwIiwiZ2l2ZW5fbmFtZSI6InN0dWRlbnQgb25lIiwiZmFtaWx5X25hbWUiOiJvbmUifQ.tip2fcB6it5EcMfUXRbEoZfvc9ofpBjbrGXQJHD6yXYyWnImGJsWBd8-6wfukxwIu433sVCIFy5k0bYkyqO9OHDs5RZJ4o6FTN8EEy4rN1Ne0r4WR_3kAoJPxiQMrC9K-6_1GgtsOQyAbQns74zVeBj2zis1JlcusSNyIDidQ6beqsVBQalfdgnzrhejvh3LnVjPOedNtrFurUdbZ-JIsWsv3uwo_OX6ZrtvUCvBzNEFT85gmq1uPqFTk4stW7jpVZSc5-UKMcFNjVsMCHTDRaTffIL2WiUVPWQh239M7Q4NSPN7JBDm_pMBtowOBgVEAda9YeXDgJUlrqc2cYjdZGX1GQ6dGtApeVCiCOv6OpmhFQmT4-fKKmpqatc_Aia5NinJ21PstJDRIXe4F8T43KYtfAwxjwAcMxGzyiuvdDphrbDDTNxBsUH7IFDUw1QCyuzUavus3r8vw0z9XOiNINq_-BuXnQrC0fkPLhqzshFnZGFJ8vJO24Fn2vhkaSh3CKctfusSEB1SRA9Kl2icT5BRZ_bNeEvyXk-hzmZ_NhCiVdOPfIw4i_Cfb8KRd6BW0Nk68BSmWdTV1AAFRF3x9UB5sEOZooLK4gYwkX0kEduZ-aGxK6t2Tz45XLCR_vsTonKe7o6F5D47b-VVhm4N8PQHQgq28Bd8VCZlyTqipUU",
    "expires_in": 300,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI3ZWEwMDYzNi0yZTBlLTQ0YzMtOGRhMS1kMGM1M2U5ZTg0MTAifQ.eyJleHAiOjE2NDM4MDMwODQsImlhdCI6MTY0MzgwMTI4NCwianRpIjoiMmZhNjdmZGUtNzUwNy00NDYzLTlhYzAtZGJmMDIzMTg3ZDkzIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi5rZXljbG9hay5pZGJyb2tlci5pbnRyYW5ldC9hdXRoL3JlYWxtcy9JRC1Ccm9rZXIiLCJhdWQiOiJodHRwczovL2xvZ2luLmtleWNsb2FrLmlkYnJva2VyLmludHJhbmV0L2F1dGgvcmVhbG1zL0lELUJyb2tlciIsInN1YiI6ImY6ZDdlNGNlMTQtY2YwNy00ZTFmLTgwM2MtZGU5OTZkZDI0ZGE3OjViZjY0NGU2LTE3OGUtMTAzYy04NDUxLTQ5YjRmNTZiMWJjMCIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJweXRob24tY2xpZW50Iiwic2Vzc2lvbl9zdGF0ZSI6IjEzNGVhZTgzLTk3MGEtNGQzYS04NGE1LWE4ZTMzMWJlN2QyMiIsInNjb3BlIjoib3BlbmlkIGVtYWlsIHByb2ZpbGUiLCJzaWQiOiIxMzRlYWU4My05NzBhLTRkM2EtODRhNS1hOGUzMzFiZTdkMjIifQ.DkTZc2H_yqN8QJPV4YuUk1tqdbdpzCd56sCKZ7pDDQQ",
    "token_type": "Bearer",
    "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJuRHBjM2szTkFzZGc4YndJbGRZRnk5MjVQYWxBR2g5bDNnYjJxZUhhdnYwIn0.eyJleHAiOjE2NDM4MDE1ODQsImlhdCI6MTY0MzgwMTI4NCwiYXV0aF90aW1lIjoxNjQzNzk3MjkyLCJqdGkiOiJhODBiZjhkMy0zMjE5LTQ2MGQtYWU2Ny1lMzU0YzZlOWE4OGYiLCJpc3MiOiJodHRwczovL2xvZ2luLmtleWNsb2FrLmlkYnJva2VyLmludHJhbmV0L2F1dGgvcmVhbG1zL0lELUJyb2tlciIsImF1ZCI6InB5dGhvbi1jbGllbnQiLCJzdWIiOiJmOmQ3ZTRjZTE0LWNmMDctNGUxZi04MDNjLWRlOTk2ZGQyNGRhNzo1YmY2NDRlNi0xNzhlLTEwM2MtODQ1MS00OWI0ZjU2YjFiYzAiLCJ0eXAiOiJJRCIsImF6cCI6InB5dGhvbi1jbGllbnQiLCJzZXNzaW9uX3N0YXRlIjoiMTM0ZWFlODMtOTcwYS00ZDNhLTg0YTUtYThlMzMxYmU3ZDIyIiwiYXRfaGFzaCI6Ik5FWmZtU0YwcVBzWVA4LWhuZ1VodmciLCJhY3IiOiIwIiwic2lkIjoiMTM0ZWFlODMtOTcwYS00ZDNhLTg0YTUtYThlMzMxYmU3ZDIyIiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJuYW1lIjoic3R1ZGVudCBvbmUgb25lIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiNWJmNjQ0ZTYtMTc4ZS0xMDNjLTg0NTEtNDliNGY1NmIxYmMwIiwiZ2l2ZW5fbmFtZSI6InN0dWRlbnQgb25lIiwiZmFtaWx5X25hbWUiOiJvbmUifQ.gVaJTVNwWwNRh04aat9BV8ObWaVuGZtSlOMybLktzwERjrG8TBJ8wpk9rWzaym7vl34QJ30cLmCLdLgHHXN_rYpLiAkE6_L6sjfIwPqPHSCzMFCtohpnwdwHI-tA0ii3eR6ms4EqutXNVrZNluR3ApI9GW8owGEit4SQQstBm_qwYYMR5dfkAuIxh24g1U2NvGO5ZrtBU2o7zc0M26hgWQ6y9MAaMa-PYaVecK-u21d_MkWbccm2Kg-j2ErNDX4N_1l6WELdZjppzSnH-zYY-TV7FbhV_jgS2FPoVt3SDOhsH6CBjxm4J5t48Vowjlf0vk0V6lm_ys5batZ5Z1fvcd9-DcY8RjmHuvU_T5ocKrrK2dKcKNnjrnBZUiwQzoszjNY9t02HLmAI8mfL5nzyO-OM6jX9YDa0jy_6QkeInQXN4Dgh2YNd333F9lPrnJph5oul2V9-5lV6scD2hPRSwrnPVBAsVcW14WA2nttvYEQoJ-J637oXokP2XCqftcd5zYFV3mjzDEyuH0GMvkO8kpK6_4s2hh9KFDzeIWTRoFfSbLhq5b_rpSasGzEb3tfR20YlCTAQo1j06iBsAkBdebopn8TKU_eLFpExxc90pXOooNmznWGmZT36buIUQJIfiJh0C2WIWvU7au_gVKzU9cFuu54F2xUmQA97JEKsDCU",
    "not-before-policy": 0,
    "session_state": "134eae83-970a-4d3a-84a5-a8e331be7d22",
    "scope": "openid email profile"
}

The acces_token, refresh_token and the id_token are JSON web tokens (JWT) of the type bearer, also called JWT bearer tokens. The Self-disclosure API uses the token information to provide pseudonymized data to the service provider. Based on the data the service provider decides what content it presents to each user.