SSO instellen

Met single sign-on (SSO) loggen je medewerkers in Instructo in met het account dat ze al hebben: Microsoft Entra ID, Google Workspace, of een andere identity provider die OpenID Connect ondersteunt. Ze kiezen geen apart Instructo-wachtwoord meer.

SSO wordt door Jump voor je organisatie aangezet. Daarna vul je zelf de gegevens van je identity provider in.

Voordat je begint

Je hebt twee dingen nodig:

• Beheerrechten bij je eigen identity provider, genoeg om een app-registratie aan te maken.
• De rol Organisatiebeheerder in Instructo. Als groepbeheerder zie je deze velden niet.

Stap 1: registreer Instructo bij je identity provider

Instructo moet bij je identity provider bekend zijn als app. Dat heet een app-registratie. Je maakt die één keer aan bij je provider, en je krijgt er de gegevens uit die je in stap 2 in Instructo invult.

Daarvoor heb je de redirect-URI nodig: het adres waar je provider de medewerker na het inloggen naar terugstuurt. Die hoef je niet over te typen. Ga in het CMS naar Tenants, open je eigen organisatie en klap Module configuraties → Single sign-on (SSO) open. Bovenaan staat de Redirect-URI met een knop Kopieer. Hij ziet er zo uit:

1

https://cms.instructo.com/api/auth/sso/sso/callback

Let op twee dingen die vaak verwarring geven:

• Er staat geen naam van je organisatie in de URI. Dat is de bedoeling. Elke klant registreert exact dezelfde URI. Instructo weet uit de aanvraag zelf om welke organisatie het gaat, dus dat hoeft niet in de URI te staan. Je bent dus niets vergeten.
• De URI moet exact overeenkomen, inclusief https en zonder afsluitende slash. Identity providers vergelijken letterlijk en weigeren de login bij het kleinste verschil. Gebruik daarom de knop Kopieer.

Hoe je de app-registratie aanmaakt en waar je de gegevens vindt, verschilt per provider. Kies hieronder die van jou. Vraagt je provider welke rechten (scopes) de app krijgt? Kies dan openid, email en profile. Meer heeft Instructo niet nodig; het leest alleen het e-mailadres.

Microsoft Entra ID

1. Ga in het Microsoft Entra-beheercentrum naar App registrations en klik op New registration.
2. Geef de app een herkenbare naam, bijvoorbeeld “Instructo”. Kies bij Redirect URI het platform Web en plak de redirect-URI.
3. Klik op Register. Op de pagina Overview van de nieuwe app staan nu twee gegevens die je nodig hebt:
   • Application (client) ID: dit is je Client ID.
   • Directory (tenant) ID: dit vul je in bij Directory (tenant) ID.
4. Ga naar Certificates & secrets, klik op New client secret en kies een geldigheidsduur. Kopieer daarna direct de Value, niet de Secret ID. De Value zie je maar één keer.

Microsoft beschrijft deze stappen met schermafbeeldingen in Een toepassing registreren en Referenties toevoegen.

Google Workspace

1. Ga in de Google Cloud Console naar APIs & Services → Credentials. Heb je nog geen OAuth-toestemmingsscherm, dan vraagt Google je dat eerst in te stellen. Kies daar als gebruikerstype Internal, zodat alleen accounts van je eigen organisatie kunnen inloggen.
2. Klik op Create credentials → OAuth client ID en kies als type Web application.
3. Plak de redirect-URI onder Authorized redirect URIs en klik op Create.
4. Google toont nu de Client ID en het Client secret. Kopieer ze allebei.

Google beschrijft deze stappen in OAuth 2.0 instellen.

Een andere provider (OpenID Connect)

Maak in je provider een app of client aan van het type web application en plak de redirect-URI. Je krijgt dan een Client ID en een Client secret.

Daarnaast heb je drie adressen van je provider nodig: de Issuer-URL, het Authorization endpoint en het Token endpoint. Die staan bij vrijwel elke provider in een vast document op dit adres:

1

https://<adres-van-je-provider>/.well-known/openid-configuration

Open dat in je browser en zoek de regels issuer, authorization_endpoint en token_endpoint. Kom je er niet uit, vraag dan de beheerder van je identity provider om deze drie adressen.

Bewaar de gegevens even; je hebt ze in stap 2 nodig. Een client secret kun je bij de meeste providers na het aanmaken niet meer teruglezen.

Stap 2: vul de gegevens in Instructo in

Ga in het CMS naar Tenants, open je eigen organisatie en klap Module configuraties → Single sign-on (SSO) open.

Kies eerst het Type provider. Wat je daarna moet invullen hangt daarvan af:

Vul daarna in alle drie de gevallen in:

• Client ID: uit de app-registratie van stap 1.
• Client secret: uit stap 1.
• Label van de inlogknop (optioneel): de tekst op de knop, bijvoorbeeld “Inloggen met Microsoft”. Laat je dit leeg, dan staat er “SSO”.

Klik op Save.

Over het client secret

Het secret wordt versleuteld opgeslagen. Na het opslaan zie je het veld leeg terug, ook al staat er wel iets in. Dat is geen fout.

Dat betekent ook: laat het veld leeg als je het secret niet wil wijzigen. Sla je op met een leeg veld, dan blijft het bestaande secret gewoon staan. Wil je het secret vervangen, bijvoorbeeld omdat het bij je provider verloopt, vul dan het nieuwe in en sla op.

Waarom je de toegestane e-maildomeinen niet kunt wijzigen

Bij de SSO-instellingen staat ook Toegestane e-maildomeinen. Dat veld kun je lezen maar niet aanpassen; Jump vult het bij het aanzetten van SSO voor je in.

Dat is geen willekeurige beperking. Dat veld bepaalt welke e-mailadressen jouw identity provider mag aanleveren. Zonder die grens zou een verkeerd geconfigureerde of gecompromitteerde identity provider een adres van een andere organisatie kunnen opgeven en zo bij de gegevens van die organisatie komen. Omdat jij zelf beheert waar Instructo naartoe verwijst voor de login, mag jij niet ook nog bepalen welke adressen daar geldig zijn.

Een domein kan bovendien maar bij één organisatie tegelijk horen. Instructo gebruikt dezelfde lijst namelijk ook om op het CMS-inlogscherm automatisch de juiste organisatie te herkennen (zie stap 3) — zonder die eenduidigheid zou die herkenning niet werken. Instructo weigert daarom een domein dat al ergens anders in gebruik is.

Moet er een domein bij, bijvoorbeeld na een naamswijziging of een overname? Neem contact op met Jump.

Stap 3: test de login

Op het inlogscherm van het CMS typt een gebruiker eerst zijn e-mailadres in. Instructo herkent aan het domein van dat adres welke organisatie het is en toont automatisch de bijbehorende SSO-knop — niemand hoeft dus een organisatienaam of -code op te zoeken of in te vullen. Valt het domein niet onder de toegestane e-maildomeinen, dan blijft de SSO-knop weg en kan diegene gewoon met wachtwoord of inloglink verder.

Laat één medewerker uitloggen en opnieuw inloggen via de SSO-knop. Werkt dat, dan staat het goed.

Gaat het mis, dan komt de gebruiker terug op het inlogscherm met een melding. De meldingen zijn met opzet kort gehouden, zodat ze niet verklappen welke e-mailadressen bestaan. Dit is wat ze betekenen:

Zie je iets anders, of blijft het bij Sign-in failed, geef dan het tijdstip door aan Jump: dat staat in de logboeken met de precieze oorzaak erbij.

Nieuwe medewerkers krijgen geen account door SSO

Dit is het punt waarop de meeste verwachtingen misgaan: SSO maakt geen accounts aan. Iemand die kan inloggen bij jouw identity provider maar geen Instructo-account heeft, komt er niet in.

Nieuwe medewerkers gaan dus nog steeds via een uitnodiging, precies zoals nu (zie Uitnodigingen maken). Het verschil is dat ze bij het voltooien van hun account geen wachtwoord meer hoeven te kiezen: dat kan ook via SSO. Rol en groep komen uit de uitnodiging, dus jij bepaalt wat iemand mag, niet de identity provider.

SSO verplichten

Staat SSO goed en werkt het voor iedereen, dan kun je SSO verplichten aanzetten. Vanaf dat moment kunnen de gebruikers van jouw organisatie:

• niet meer inloggen met een Instructo-wachtwoord;
• geen inloglink per e-mail meer aanvragen; de knop verdwijnt van het inlogscherm.

Alleen nog SSO dus. Dat is precies het punt: je wilt dat toegang tot Instructo verloopt via het account dat je bij vertrek van een medewerker centraal uitzet.

Zet dit pas aan als SSO bewezen werkt. Valt je identity provider daarna uit, dan kan niemand van jouw organisatie meer inloggen. Beheerders van Jump kunnen dan nog wel met wachtwoord inloggen om je te helpen, dus je bent nooit definitief buitengesloten, maar je bent dan wel afhankelijk van hen.

Wat Instructo tijdens de login doet

Kort, voor wie het wil weten of moet verantwoorden:

1. De gebruiker klikt op de SSO-knop en gaat naar jouw identity provider.
2. Daar logt hij in; Instructo ziet zijn wachtwoord nooit.
3. Jouw provider stuurt hem terug met een eenmalige code.
4. Instructo wisselt die code rechtstreeks bij jouw provider om voor een token, controleert of het token echt van jouw provider komt en of het e-mailadres binnen de toegestane domeinen valt.
5. Alleen dan zoekt Instructo het bestaande account op en start de sessie.

De heenweg is beveiligd met PKCE en een eenmalige, ondertekende cookie, zodat een onderschepte code niet opnieuw te gebruiken is.