Add IT admin guide for allowing Dodona in Microsoft Entra ID

Dodona now signs users in with its own Microsoft app registration instead
of the one managed by Ghent University. Institutions that lock down which
third-party applications their users may consent to have to allow the new
one explicitly, so this page gives their IT department the application
details, the requested permissions, and the ways to allow it.

The page is linked from the sign-in modal in the app and is what we send
to a university IT department when we ask them to allowlist us.

Also cross-links it from the accounts FAQ in both languages.

Author: TomNaessens

en/faq/accounts/index.md

@@ -12,6 +12,8 @@ Accounts on Dodona are automatically created when you log in for the first time.
 
 It is not possible to manually create an account on Dodona with a username and password.
 
+If your institution signs in with Microsoft and restricts which applications its users may consent to, your IT department can find everything they need in [Allowing Dodona in Microsoft Entra ID](/en/guides/general/microsoft-entra/).
+
 ## I work in several schools, how does this work?
 
 Your account on Dodona is linked to the way you log in. For example, if you have Smartschool accounts at several schools, each of them will be linked to a different Dodona account.

en/guides/general/microsoft-entra/index.md

@@ -0,0 +1,109 @@
+---
+title: "Allowing Dodona in Microsoft Entra ID"
+description: "For IT administrators: reviewing and allowing Dodona's Microsoft application in your own Microsoft Entra tenant."
+order: 2
+---
+
+# Allowing Dodona in Microsoft Entra ID
+
+This page is written for the IT administrators of a school, college or university. It contains everything you need to review Dodona's Microsoft application and to allow it in your own Microsoft Entra tenant, so that your users can sign in to Dodona with their institutional Microsoft account.
+
+Students and teachers don't need anything on this page. They simply sign in at [dodona.be](https://dodona.be) and pick their institution.
+
+## About Dodona
+
+<!--@include: ../../_what-is-dodona.md-->
+
+Dodona is developed and operated by Dodona Learning Technologies BV. Using Dodona is free of charge for educational institutions.
+
+## Why you might be reading this
+
+Dodona uses Microsoft Entra ID (formerly Azure AD) to sign in users with their institutional Microsoft 365 account. Some institutions restrict which third-party applications their users may consent to. In that case Microsoft blocks the sign-in, and someone from your IT department has to allow the Dodona application explicitly before your users can get in.
+
+::: warning We now use our own application registration
+
+Until recently, signing in to Dodona with a Microsoft account went through an application registration managed by Ghent University. Dodona now has its own application registration, the one described below.
+
+If your institution explicitly allowed the previous application, that approval doesn't carry over. You need to allow this application as well.
+:::
+
+## The application registration
+
+| | |
+| --- | --- |
+| Display name | `Dodona` |
+| Application (client) ID | `060c642b-473b-4423-a9f6-dfc67066deb6` |
+| Publisher | Dodona Learning Technologies BV |
+| Publisher domain | `dodona.be` |
+| Supported account types | Accounts in any organizational directory (multitenant) and personal Microsoft accounts |
+| Redirect URI | `https://dodona.be/users/auth/microsoft/callback` |
+
+The application is [publisher verified](https://learn.microsoft.com/en-us/entra/identity-platform/publisher-verification-overview) by Microsoft, which means Microsoft has verified that Dodona Learning Technologies BV is the organisation publishing it. You can recognise this by the blue `Verified` badge on the consent prompt and on the application's page in the Microsoft Entra admin center.
+
+## Which permissions Dodona requests
+
+Dodona requests three **delegated** Microsoft Graph permissions, and nothing else:
+
+- `openid`: sign the user in and receive an ID token. This is the permission that makes single sign-on work at all.
+- `email`: read the primary email address of the signed-in user.
+- `profile`: read the basic profile of the signed-in user, such as their name.
+
+These are the three [OpenID Connect scopes](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc) that Microsoft describes as the minimum for basic sign-in. All three are in the tier that does **not** require administrator consent.
+
+::: tip Dodona makes no Microsoft Graph API calls
+
+Dodona never calls the Microsoft Graph API. The permissions above exist only so that Microsoft issues an ID token when someone signs in. Dodona reads a few [claims](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference) from that token and then discards the token itself:
+
+- `oid` and `tid`: the immutable identifiers of the user and of your tenant. Dodona uses these to recognise a returning user and to link the account to your institution.
+- `email`, `given_name`, `family_name`, `preferred_username` and `name`: the user's email address and name, used to fill in their Dodona profile.
+
+That is the complete list. There is no background service, no refresh token, and nothing with which Dodona could query your directory.
+:::
+
+Concretely, this means that:
+
+- Dodona never receives, stores or asks for the user's Microsoft password. Authentication happens entirely on Microsoft's own sign-in pages.
+- Dodona requests no access to mail, files, calendars, Teams or directory data.
+- Dodona has no access to anything in your tenant beyond the sign-in itself.
+
+What Dodona does with the personal data it receives is described in our [data policy](https://dodona.be/en/data/).
+
+## Allowing the application
+
+Which of the following applies depends on your tenant's consent configuration. Granting tenant-wide admin consent is the most predictable option, and the one we usually ask for.
+
+### Reviewing the application in your tenant
+
+Once at least one of your users has attempted to sign in, the Dodona application appears in your tenant under `Enterprise applications` in the [Microsoft Entra admin center](https://entra.microsoft.com). Search for `Dodona`, or filter on the application ID above if you have several results. Microsoft documents this in [View enterprise applications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/view-applications-portal).
+
+From the application's `Permissions` page you can see exactly which permissions have been requested and granted.
+
+### Granting tenant-wide admin consent
+
+Granting admin consent on behalf of your organisation means your users are never prompted for consent themselves. You do this from the application's `Permissions` page under `Enterprise applications`, as described in [Grant tenant-wide admin consent to an application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent).
+
+If the application isn't in your tenant yet, you can also start the consent flow directly. Open the following URL while signed in with an account that may consent on behalf of your organisation, and replace `{tenant}` with your tenant ID or one of your verified domain names:
+
+```
+https://login.microsoftonline.com/{tenant}/adminconsent?client_id=060c642b-473b-4423-a9f6-dfc67066deb6
+```
+
+Granting consent requires a role such as `Cloud Application Administrator` or `Privileged Role Administrator`.
+
+### Your user consent settings
+
+If you'd rather not consent on behalf of everyone, your users can consent for themselves, depending on the user consent setting of your tenant. You can find it under `Enterprise applications` > `Consent and permissions` > `User consent settings`, documented in [Configure how users consent to applications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-user-consent).
+
+- `Allow user consent for apps`: your users can consent to Dodona themselves and you don't need to do anything.
+- `Allow user consent for apps from verified publishers, for selected permissions`: Dodona is publisher verified, so it meets the publisher half of this policy. The requested permissions also have to be classified as low impact in your tenant. If they aren't, add `openid`, `email` and `profile` to your [permission classifications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-permission-classifications), or grant admin consent instead.
+- `Do not allow user consent`: an administrator has to consent. Either grant tenant-wide admin consent as described above, or enable the [admin consent workflow](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-admin-consent-workflow) so that users can request approval from within the sign-in flow.
+
+### Restricting who can sign in
+
+Allowing the application doesn't oblige you to open it up to everyone. You can set `Assignment required` on the application and then assign only the users or groups that should be able to sign in to Dodona, as described in [Assign users and groups to an application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal). Note that applications requiring assignment always need administrator consent, even when your user consent settings would otherwise allow users to consent themselves.
+
+## Still stuck?
+
+If sign-in keeps failing after you allowed the application, or if you need something we haven't listed here (a DPA, an extra security questionnaire, a different redirect URI for a test setup), use the contact form at [dodona.be/en/contact](https://dodona.be/en/contact). We're happy to help, and all comments and suggestions are more than welcome.
+
+For questions about accounts on Dodona in general, see the [FAQ about accounts and settings](/en/faq/accounts/).

nl/faq/accounts/index.md

@@ -12,6 +12,8 @@ Accounts op Dodona worden automatisch aangemaakt wanneer je voor de eerste keer
 
 Het is niet mogelijk om handmatig een account aan te maken op Dodona met een gebruikersnaam en wachtwoord.
 
+Meldt je instelling zich aan met Microsoft en beperkt ze aan welke applicaties haar gebruikers toestemming mogen geven? Dan vindt je IT-dienst alles wat ze nodig heeft in [Dodona toelaten in Microsoft Entra ID](/nl/guides/general/microsoft-entra/).
+
 ## Ik werk op verschillende scholen, hoe werkt dit?
 
 Je account op Dodona is gekoppeld aan de manier waarop je inlogt. Als je bijvoorbeeld Smartschool-accounts hebt op verschillende scholen, dan wordt elk van hen gekoppeld aan een andere Dodona-account.

nl/guides/general/microsoft-entra/index.md

@@ -0,0 +1,109 @@
+---
+title: "Dodona toelaten in Microsoft Entra ID"
+description: "Voor IT-beheerders: de Microsoft-applicatie van Dodona nakijken en toelaten in je eigen Microsoft Entra-tenant."
+order: 2
+---
+
+# Dodona toelaten in Microsoft Entra ID
+
+Deze pagina is bedoeld voor de IT-beheerders van een school, hogeschool of universiteit. Ze bevat alles wat je nodig hebt om de Microsoft-applicatie van Dodona na te kijken en toe te laten in je eigen Microsoft Entra-tenant, zodat je gebruikers zich op Dodona kunnen aanmelden met hun institutionele Microsoft-account.
+
+Studenten en lesgevers hebben niets van deze pagina nodig. Zij melden zich gewoon aan op [dodona.be](https://dodona.be) en kiezen daar hun instelling.
+
+## Over Dodona
+
+<!--@include: ../../_what-is-dodona.md-->
+
+Dodona wordt ontwikkeld en beheerd door Dodona Learning Technologies BV. Het gebruik van Dodona is gratis voor onderwijsinstellingen.
+
+## Waarom je hier terechtkomt
+
+Dodona gebruikt Microsoft Entra ID (vroeger Azure AD) om gebruikers aan te melden met hun institutionele Microsoft 365-account. Sommige instellingen beperken aan welke externe applicaties hun gebruikers toestemming mogen geven. In dat geval blokkeert Microsoft de aanmelding, en moet iemand van je IT-dienst de Dodona-applicatie eerst expliciet toelaten voor je gebruikers binnen geraken.
+
+::: warning We gebruiken nu onze eigen app-registratie
+
+Tot voor kort verliep het aanmelden op Dodona met een Microsoft-account via een app-registratie die beheerd werd door de Universiteit Gent. Dodona heeft nu een eigen app-registratie, degene die hieronder beschreven staat.
+
+Als je instelling de vorige applicatie expliciet toeliet, geldt die goedkeuring niet automatisch voor de nieuwe. Je moet ook deze applicatie toelaten.
+:::
+
+## De app-registratie
+
+| | |
+| --- | --- |
+| Weergavenaam | `Dodona` |
+| Toepassings-ID (client) | `060c642b-473b-4423-a9f6-dfc67066deb6` |
+| Uitgever | Dodona Learning Technologies BV |
+| Domein van de uitgever | `dodona.be` |
+| Ondersteunde accounttypes | Accounts in elke organisatiemap (multitenant) en persoonlijke Microsoft-accounts |
+| Omleidings-URI | `https://dodona.be/users/auth/microsoft/callback` |
+
+De applicatie is [publisher verified](https://learn.microsoft.com/en-us/entra/identity-platform/publisher-verification-overview) bij Microsoft. Microsoft heeft dus geverifieerd dat Dodona Learning Technologies BV de organisatie is die de applicatie publiceert. Je herkent dat aan het blauwe `Verified`-label op het toestemmingsscherm en op de pagina van de applicatie in het Microsoft Entra-beheercentrum.
+
+## Welke machtigingen Dodona vraagt
+
+Dodona vraagt drie **gedelegeerde** machtigingen op Microsoft Graph, en verder niets:
+
+- `openid`: de gebruiker aanmelden en een ID-token ontvangen. Dit is de machtiging die single sign-on überhaupt mogelijk maakt.
+- `email`: het primaire e-mailadres van de aangemelde gebruiker lezen.
+- `profile`: het basisprofiel van de aangemelde gebruiker lezen, zoals de naam.
+
+Dat zijn de drie [OpenID Connect-scopes](https://learn.microsoft.com/en-us/entra/identity-platform/scopes-oidc) die Microsoft zelf beschrijft als het minimum om te kunnen aanmelden. Alle drie zitten ze in de categorie die **geen** toestemming van een beheerder vereist.
+
+::: tip Dodona doet geen enkele oproep naar de Microsoft Graph API
+
+Dodona roept de Microsoft Graph API nooit aan. De machtigingen hierboven dienen er enkel voor dat Microsoft een ID-token uitreikt wanneer iemand zich aanmeldt. Dodona leest een handvol [claims](https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference) uit dat token en gooit het token daarna weg:
+
+- `oid` en `tid`: de onveranderlijke identificatoren van de gebruiker en van je tenant. Dodona gebruikt die om een terugkerende gebruiker te herkennen en om het account aan je instelling te koppelen.
+- `email`, `given_name`, `family_name`, `preferred_username` en `name`: het e-mailadres en de naam van de gebruiker, om het Dodona-profiel in te vullen.
+
+Dat is de volledige lijst. Er is geen achtergrondproces, geen vernieuwingstoken, en niets waarmee Dodona je directory zou kunnen bevragen.
+:::
+
+Concreet betekent dat:
+
+- Dodona ontvangt, bewaart of vraagt nooit het Microsoft-wachtwoord van de gebruiker. Het aanmelden gebeurt volledig op de aanmeldpagina's van Microsoft zelf.
+- Dodona vraagt geen toegang tot e-mail, bestanden, agenda's, Teams of gegevens uit je directory.
+- Dodona heeft geen toegang tot iets in je tenant buiten de aanmelding zelf.
+
+Wat Dodona doet met de persoonsgegevens die het ontvangt, staat in ons [gegevensbeleid](https://dodona.be/nl/data/).
+
+## De applicatie toelaten
+
+Wat op jou van toepassing is, hangt af van de toestemmingsinstellingen van je tenant. Beheerderstoestemming voor de hele organisatie is de meest voorspelbare optie, en degene die we meestal vragen. De labels tussen backticks hieronder zijn de Engelstalige benamingen uit het Microsoft Entra-beheercentrum.
+
+### De applicatie nakijken in je tenant
+
+Zodra minstens één van je gebruikers geprobeerd heeft zich aan te melden, verschijnt de Dodona-applicatie in je tenant onder `Enterprise applications` in het [Microsoft Entra-beheercentrum](https://entra.microsoft.com). Zoek op `Dodona`, of filter op het toepassings-ID hierboven als je meerdere resultaten krijgt. Microsoft documenteert dit in [View enterprise applications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/view-applications-portal).
+
+Op de pagina `Permissions` van de applicatie zie je precies welke machtigingen gevraagd en toegekend zijn.
+
+### Beheerderstoestemming geven voor de hele organisatie
+
+Als je toestemming geeft namens je organisatie, krijgen je gebruikers zelf nooit een toestemmingsscherm te zien. Dat doe je vanaf de pagina `Permissions` van de applicatie onder `Enterprise applications`, zoals beschreven in [Grant tenant-wide admin consent to an application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/grant-admin-consent).
+
+Staat de applicatie nog niet in je tenant, dan kan je de toestemmingsflow ook rechtstreeks starten. Open de volgende URL terwijl je aangemeld bent met een account dat namens je organisatie toestemming mag geven, en vervang `{tenant}` door je tenant-ID of door een van je geverifieerde domeinnamen:
+
+```
+https://login.microsoftonline.com/{tenant}/adminconsent?client_id=060c642b-473b-4423-a9f6-dfc67066deb6
+```
+
+Toestemming geven vereist een rol zoals `Cloud Application Administrator` of `Privileged Role Administrator`.
+
+### Je instellingen voor gebruikerstoestemming
+
+Als je liever geen toestemming geeft namens iedereen, kunnen je gebruikers dat zelf doen, afhankelijk van de instelling voor gebruikerstoestemming van je tenant. Je vindt die onder `Enterprise applications` > `Consent and permissions` > `User consent settings`, gedocumenteerd in [Configure how users consent to applications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-user-consent).
+
+- `Allow user consent for apps`: je gebruikers kunnen zelf toestemming geven aan Dodona en je hoeft niets te doen.
+- `Allow user consent for apps from verified publishers, for selected permissions`: Dodona is publisher verified en voldoet dus aan het eerste deel van deze policy. De gevraagde machtigingen moeten daarnaast in je tenant als `low impact` geklasseerd staan. Is dat niet zo, voeg dan `openid`, `email` en `profile` toe aan je [permission classifications](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-permission-classifications), of geef beheerderstoestemming.
+- `Do not allow user consent`: een beheerder moet toestemming geven. Geef ofwel beheerderstoestemming zoals hierboven beschreven, ofwel schakel je de [admin consent workflow](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/configure-admin-consent-workflow) in, zodat gebruikers vanuit de aanmeldflow zelf een goedkeuring kunnen aanvragen.
+
+### Beperken wie zich mag aanmelden
+
+De applicatie toelaten verplicht je niet om ze voor iedereen open te zetten. Je kan `Assignment required` instellen op de applicatie en daarna enkel de gebruikers of groepen toewijzen die zich op Dodona mogen aanmelden, zoals beschreven in [Assign users and groups to an application](https://learn.microsoft.com/en-us/entra/identity/enterprise-apps/assign-user-or-group-access-portal). Let op: applicaties die toewijzing vereisen hebben altijd beheerderstoestemming nodig, ook als je instellingen voor gebruikerstoestemming gebruikers anders zelf zouden laten beslissen.
+
+## Nog vragen?
+
+Blijft het aanmelden mislukken nadat je de applicatie toegelaten hebt, of heb je iets nodig dat hier niet staat (een verwerkersovereenkomst, een bijkomende veiligheidsvragenlijst, een andere omleidings-URI voor een testopstelling)? Gebruik dan het contactformulier op [dodona.be/nl/contact](https://dodona.be/nl/contact). We helpen je graag verder, en alle opmerkingen en suggesties zijn meer dan welkom.
+
+Voor algemene vragen over accounts op Dodona kan je terecht bij de [FAQ over accounts en instellingen](/nl/faq/accounts/).