Self Disclosure API manual 1.0.0

Download PDF

Self-disclosure API in context of ID Broker

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#

Fig. 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 Fig. 1.1 uses the Self-disclosure API.

_images/overview_sequence.png

Fig. 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. The response looks like the following example:

{'access_token': 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUQTU1cEt1SGVQZWFqX2wxaC1DR2xHcVYwWnpva2pBX0FQYm1TSk5scURJIn0.eyJleHAiOjE3MTk5MDg2NzUsImlhdCI6MTcxOTkwODM3NSwiYXV0aF90aW1lIjoxNzE5OTA4Mzc1LCJqdGkiOiJjYzU2MTVkNC04YjM0LTRlNGMtYWE5YS1hZDc4Yjk0ZmVhMmQiLCJpc3MiOiJodHRwczovL3Nzby1icm9rZXIuc3RhZ2luZy51bml2ZW50aW9uLWlkLWJyb2tlci5jb20vYXV0aC9yZWFsbXMvSUQtQnJva2VyIiwiYXVkIjoic2VsZi1kaXNjbG9zdXJlLWFwaSIsInN1YiI6ImI0ZTkxN2Q5MjBlYWIyZTMxNDYxM2UyMTAwODVlZDE4ZTVjNjc5ZmE5NTYxNDE0ODhiYWEwMGRkYWM4NjIzYTQ1MTBkN2VhNjNjZTQ3NjMzM2I3NTgxY2UzY2M5M2RiMmM5OTc0MmM1MmQxY2Y1ZjllMGE0YjU3YjVjODNhODNhIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoidW5pdmVudGlvbi10ZXN0LWFwcCIsIm5vbmNlIjoiSUdJZFByUU9oeTZhRDh5Q2hSdDQiLCJzZXNzaW9uX3N0YXRlIjoiMTI5YTE1ODYtNmFmMy00NjJmLWJmN2YtZmM1MzNkMGIxOTdlIiwiYWNyIjoiMSIsInNjb3BlIjoib3BlbmlkIHNlbGYtZGlzY2xvc3VyZS1hcGkiLCJzaWQiOiIxMjlhMTU4Ni02YWYzLTQ2MmYtYmY3Zi1mYzUzM2QwYjE5N2UiLCJjbGllbnRfaWQiOiJ1bml2ZW50aW9uLXRlc3QtYXBwIn0.VWN2RKaO2mXYISdIfG_LIHJ8EqdIYx6ABZofOA1gzI5bPZPEU-LzIlwsg2kMNzEw1Y-geNfwrAHLi-azP4-TTBF6szBGPR8KRWZuK85h0L6-riaUEHSlJYquninReZeax13VDISgstcBE0mKVByaJYMN0eikdopvndVKDx21oH_0vKVD5yO7OVHg_CmkVXkRGSPRBFocT_JZMxMh6ucAfyyifZTJIieyvhUBSjfNAYxyZn2pISOsYaFTx9P4gv8M5Bj231rpDiVyJSVeeAdUgo_MdzVVmaDn_7yI7tFMSGapyIk6AZXgw_UhGifGcHmoJioVCu49DRMEmSZkZGiOps-4NF2ObCH5Laav8AkMtxKOe_2SNIk-1fYPk-Hr2BnyNxOwhPbjr0oCjEkFjxm62ABHBFvRQPmHUIuq9if2wcgeCJiVmRAJCzFM0dAfUGOCFx6pnwfipFRcvK8M5siWfYnS4lk0chGoph_CDUHrI6hEIoVcSEeTHyYwgQljNk1BeolnUfGkC_vODMimtmv0XiHg5zXpwxcIQbH-o5G-CYZ_e0rZZ5gUUmopIUqHN6uP_Om0q5Z6BduS70Ly3Nb149cgQSp2UAc9D4Y0cg7TCsgZxoMRb3thvug9L-sSy5GwShopHnZXN7wGTH_AyrumWy_MoV9earY00Y2Unp7UA48',
 'expires_at': 1719908675,
 'expires_in': 300,
 'id_token': 'eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJUQTU1cEt1SGVQZWFqX2wxaC1DR2xHcVYwWnpva2pBX0FQYm1TSk5scURJIn0.eyJleHAiOjE3MTk5MDg2NzUsImlhdCI6MTcxOTkwODM3NSwiYXV0aF90aW1lIjoxNzE5OTA4Mzc1LCJqdGkiOiI5NjRjNmFjYS1lZmRmLTQ1OWYtOTdmZC04MzVmMDE2NGZlY2QiLCJpc3MiOiJodHRwczovL3Nzby1icm9rZXIuc3RhZ2luZy51bml2ZW50aW9uLWlkLWJyb2tlci5jb20vYXV0aC9yZWFsbXMvSUQtQnJva2VyIiwiYXVkIjoidW5pdmVudGlvbi10ZXN0LWFwcCIsInN1YiI6ImI0ZTkxN2Q5MjBlYWIyZTMxNDYxM2UyMTAwODVlZDE4ZTVjNjc5ZmE5NTYxNDE0ODhiYWEwMGRkYWM4NjIzYTQ1MTBkN2VhNjNjZTQ3NjMzM2I3NTgxY2UzY2M5M2RiMmM5OTc0MmM1MmQxY2Y1ZjllMGE0YjU3YjVjODNhODNhIiwidHlwIjoiSUQiLCJhenAiOiJ1bml2ZW50aW9uLXRlc3QtYXBwIiwibm9uY2UiOiJJR0lkUHJRT2h5NmFEOHlDaFJ0NCIsInNlc3Npb25fc3RhdGUiOiIxMjlhMTU4Ni02YWYzLTQ2MmYtYmY3Zi1mYzUzM2QwYjE5N2UiLCJhdF9oYXNoIjoiV1o3SjYtYURxc09kMGpDYk42dXhoZyIsImFjciI6IjEiLCJzaWQiOiIxMjlhMTU4Ni02YWYzLTQ2MmYtYmY3Zi1mYzUzM2QwYjE5N2UifQ.vgVDv7oOe4W_b_fEP85jK_Jl3RKrR2X7OQ3XZ0wAETC7bkaUv3fh_X-vf64POs11YCJwmp_nWACxdk8d8DVFp3y38WtxvuNrEuvJReyU09c0feIRtyXDBvEI-SvG4p9v55xcEmhjXXnzlFCtXDCp5YhmAaWwpe-EHVzKrWrmpbS63mCSsqpffURB_rv2NsREoFOYz-8EK_4aHkky-sZIEjDPQSH3RcQK-5j06KMYMMmAfwN6lGcLuEpvbUH8JO0aApPAU_cmv8PaTvaPKG-eVPBNqqGy1lp80lZkKpl2_ySF1dMEPn5-CP91FUb8x0mnb0G0o78cFpkXbBw2ojlEs-HvuIn-N8rSI-NlQkDyHE5n56AYhSgMLdnkQRGD6gpQhNBYtxgECYkB6iRGpcca_bdaGA5JudeNX0iYr4Oj5ZTuI1fv6FAEyRK42UIJenOt7sbAmuBbHYGy8qLDWT3BTyXOlhAZDq-LExWQMnaQVA0_6x-yyte37lE8RHMUVm9-dh6jwGXG8qrMuATeJAgVrg_TTDxh3xVS5bWJ8tAyYc94WeJUyy-8wTk2S3RDWa79sNFibkSBJfI1SUyHwcVoz6bNgShKXCQChc1RQt0Y2Ige4cF8TeUZrtV3NTnsav-O5C_8C0SEdpdeMZ_t7P8sMPsVD68qbp1wkAb5e_7G2LM',
 'not-before-policy': 1709820109,
 'refresh_expires_in': 5400,
 'refresh_token': 'eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIzNzZkZWQ4OS0xNWUyLTRmOGItYWNhMy05MzYyOWUwMjhmYWMifQ.eyJleHAiOjE3MTk5MTM3NzUsImlhdCI6MTcxOTkwODM3NSwianRpIjoiZmRmOGEzNGMtNDBjYS00YjkxLWFkMTQtMjlhOTYyMTQ4N2NhIiwiaXNzIjoiaHR0cHM6Ly9zc28tYnJva2VyLnN0YWdpbmcudW5pdmVudGlvbi1pZC1icm9rZXIuY29tL2F1dGgvcmVhbG1zL0lELUJyb2tlciIsImF1ZCI6Imh0dHBzOi8vc3NvLWJyb2tlci5zdGFnaW5nLnVuaXZlbnRpb24taWQtYnJva2VyLmNvbS9hdXRoL3JlYWxtcy9JRC1Ccm9rZXIiLCJzdWIiOiJiNGU5MTdkOTIwZWFiMmUzMTQ2MTNlMjEwMDg1ZWQxOGU1YzY3OWZhOTU2MTQxNDg4YmFhMDBkZGFjODYyM2E0NTEwZDdlYTYzY2U0NzYzMzNiNzU4MWNlM2NjOTNkYjJjOTk3NDJjNTJkMWNmNWY5ZTBhNGI1N2I1YzgzYTgzYSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJ1bml2ZW50aW9uLXRlc3QtYXBwIiwibm9uY2UiOiJJR0lkUHJRT2h5NmFEOHlDaFJ0NCIsInNlc3Npb25fc3RhdGUiOiIxMjlhMTU4Ni02YWYzLTQ2MmYtYmY3Zi1mYzUzM2QwYjE5N2UiLCJzY29wZSI6Im9wZW5pZCBzZWxmLWRpc2Nsb3N1cmUtYXBpIiwic2lkIjoiMTI5YTE1ODYtNmFmMy00NjJmLWJmN2YtZmM1MzNkMGIxOTdlIn0.dt1xmDRxNOBrp9FjEzQu01CJhHlyl9IuYW66zdAnnpU',
 'scope': 'openid self-disclosure-api',
 'session_state': '129a1586-6af3-462f-bf7f-fc533d0b197e',
 'token_type': 'Bearer',
 'userinfo': {'acr': '1',
              'at_hash': 'WZ7J6-aDqsOd0jCbN6uxhg',
              'aud': 'univention-test-app',
              'auth_time': 1719908375,
              'azp': 'univention-test-app',
              'exp': 1719908675,
              'iat': 1719908375,
              'iss': 'https://sso-broker.staging.univention-id-broker.com/auth/realms/ID-Broker',
              'jti': '964c6aca-efdf-459f-97fd-835f0164fecd',
              'nonce': 'IGIdPrQOhy6aD8yChRt4',
              'session_state': '129a1586-6af3-462f-bf7f-fc533d0b197e',
              'sid': '129a1586-6af3-462f-bf7f-fc533d0b197e',
              'sub': 'b4e917d920eab2e314613e210085ed18e5c679fa956141488baa00ddac8623a4510d7ea63ce476333b7581ce3cc93db2c99742c52d1cf5f9e0a4b57b5c83a83a',
              'typ': 'ID'}}

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. When you get an acces_token you must request the openid self-disclosure-api scopes. No other scopes are allowed for self-disclosure-api clients.

On this page