Inloggen & identiteit Beschikbaar
Single sign-on (OIDC)
OpenID Connect per organisatie, ingesteld op één scherm. Je bewijst dat de verbinding werkt voordat je hem verplicht stelt, en er is altijd een weg terug.
Wat je nodig hebt
- Een identiteitsprovider met OpenID Connect discovery: Google Workspace, Microsoft Entra ID, Authentik, Keycloak, Auth0.
- Het recht settings.auth.manage; eigenaar en beheerder hebben dat standaard.
- Rechten bij die provider om een web-applicatie met clientgeheim te registreren (een confidential client).
- Een installatie die publiek over HTTPS bereikbaar is, met een reverse proxy waarvan de API de headers vertrouwt.
Zo koppel je het
- 1 Open Instellingen → Single sign-on en kopieer bovenaan het veld Callback-URL. Dat adres is niet instelbaar: het is altijd
https://jouw-host/api/v1/auth/oidc/callback, gebouwd uit je geverifieerde eigen domein of uit de subdomeinnaam van je organisatie. - 2 Registreer bij je provider een web-applicatie met clientgeheim en plak die callback-URL letterlijk in het veld voor redirect-URI's. Bij Google is dat Google Cloud Console → APIs & Services → Credentials → OAuth client ID → Web application; voor een bureau dat alleen Workspace gebruikt, zet je het toestemmingsscherm op
Internal. - 3 Geef de applicatie de scopes
openid email profile. Meer wordt er niet gevraagd, enemailis verplicht: een login die geen e-mailclaim teruggeeft, wordt geweigerd. Een 'Authorized JavaScript origin' is niet nodig, want dit is een server-side redirect en geen browserflow. - 4 Vul op het instellingenscherm Discovery-URL, Client-ID en Clientgeheim in, plus een Weergavenaam. Die naam staat op de inlogknop.
- 5 Kies de Rol voor nieuwe gebruikers en beslis over Maak bij de eerste keer inloggen een lidmaatschap aan. Staat dat uit, dan kunnen alleen mensen inloggen die hier al toegang hebben.
- 6 Zet Single sign-on inschakelen aan, druk op Opslaan en daarna op Verbinding testen. De server haalt het discovery-document op en noemt bij succes de issuer; gaat het mis, dan zie je de melding van de provider zelf.
- 7 Log eerst zelf in met de nieuwe knop. Pas daarna, als je dat wilt, zet je Single sign-on verplichten aan. De API weigert dat op te slaan zolang de huidige verbindingsgegevens geen geslaagde test achter zich hebben.
Testen voordat je verplicht stelt
'Verbinding testen' haalt het discovery-document server-side op en controleert het. Slaagt dat, dan krijg je de issuer terug; faalt het, dan zie je de fout van de provider ongewijzigd, zodat je niet hoeft te raden. Pas na een geslaagde test accepteert de API 'Single sign-on verplichten'. Wijzig je daarna de discovery-URL, het client-ID of het geheim, dan vervalt die markering en vraagt de app om een nieuwe test.
- Het clientgeheim is write-only: de app meldt alleen of er een is opgeslagen. Laat het veld leeg bij een volgende bewerking om het bestaande geheim te behouden.
- Staat SCHAKL_SECRET_KEY nog op de meegeleverde standaardwaarde en is er geen SCHAKL_ENCRYPTION_KEY, dan waarschuwt het scherm: zet een echte sleutel voordat je in productie een geheim opslaat.
- PKCE (S256) en state gaan altijd mee. Het is geen instelling en geen keuze.
Verplichten, en de weg terug
Verplichten zet inloggen met wachtwoord uit voor iedereen in de organisatie, dus elke sessie loopt vanaf dat moment langs de MFA- en conditional-accessregels van je provider. Ligt die provider eruit, dan zet de beheerder van de installatie SCHAKL_FORCE_LOCAL_LOGIN op true bij de API-container en herstart: wachtwoordinloggen werkt weer, wat er ook is opgeslagen. Inloggen, SSO repareren of uitzetten, variabele weer weghalen.
- Verplichten schakelt ook de hele tweestapsverificatie van die organisatie uit, inclusief het instellen ervan; de identiteitsprovider levert de MFA.
- SCHAKL_FORCE_LOCAL_LOGIN staat in infra/compose.yaml en infra/compose.tunnel.yaml, maar niet in infra/compose.portainer.yml: op zo'n stack voeg je hem zelf toe.
- Uitloggen blijft altijd bereikbaar, ongeacht deze instellingen.
Wie er binnenkomt, en wie niet meer
Automatisch aanmaken gaat over het eerste contact met deze organisatie, niet over 'heeft nu geen lidmaatschap'. Verwijder je iemand in Instellingen → Team & gebruikers, dan komt die persoon bij de volgende SSO-login niet stilletjes terug: de app onthoudt dat. Toegang teruggeven is een bewuste handeling met de rol die je bedoelt. Iemand die de provider wel herkent maar hier geen lidmaatschap heeft, krijgt helemaal geen sessie en leest op de inlogpagina dat hij een beheerder om toegang moet vragen.
- Een bestaand lokaal account wordt alleen aan een SSO-identiteit gekoppeld als de provider email_verified bevestigt; dat beschermt tegen providers met zelfregistratie.
- De profielfoto uit de provider wordt bij elke login ververst; heb je zelf een foto geüpload, dan wint die.
- Nieuwe gebruikers krijgen de rol die je in 'Rol voor nieuwe gebruikers' hebt gekozen, standaard lid.
De valkuil bij de eerste keer
Bijna elke mislukte eerste poging ziet er hetzelfde uit: de provider antwoordt met redirect_uri_mismatch en in de details staat een redirect-URI die met http:// begint. De app vertrouwt dan de headers van je reverse proxy niet en gebruikt het interne schema. Dat los je op in je deployment, niet op het instellingenscherm.
- Draai de API-container met --proxy-headers en --forwarded-allow-ips="*", en zorg dat het publieke verzoek echt HTTPS is (bijvoorbeeld Cloudflare 'Always Use HTTPS').
- Zet SCHAKL_AUTH_COOKIE_SECURE op true in productie.
- Bij Google kan een wijziging aan de redirect-URI's een paar minuten duren voordat hij overal is doorgevoerd.
- Een discovery-URL op http:// mag bewust wel: een Keycloak of Authentik op je eigen netwerk is een ondersteund geval.
Rechten
Geef deze rechten aan de rol die deze koppeling beheert (Instellingen → Rollen). Standaard alleen voor beheerders, en nooit voor de rol client.
-
settings.auth.manageGeeft toegang tot Instellingen → Single sign-on: de instellingen lezen, opslaan en de verbinding testen. Standaard alleen beheerder; de eigenaar heeft het recht via zijn wildcard.
Wat het bewust niet doet
- De redirect-URI is niet instelbaar. Er is geen omgevingsvariabele om hem te overschrijven, en providers vergelijken teken voor teken.
- SSO regelt alleen inloggen, geen toegang tot de Google Workspace-API. Agenda, Gmail en Drive zijn een aparte koppeling met een eigen toestemming.
- De oude SCHAKL_OIDC_*-variabelen zijn vervallen: ze worden genegeerd en mogen uit je compose-bestand.
- Een discovery-URL die doorverwijst, wordt geweigerd; het document wordt opgehaald zonder redirects te volgen (bescherming tegen SSRF).
- Eén sessie hoort bij één organisatie: inloggen op de hostname van organisatie A geeft geen sessie bij organisatie B, ook niet als je lid bent van allebei.
- Er verschijnt geen SSO-knop zolang de configuratie uit staat of discovery-URL, client-ID of geheim ontbreekt.
Waar je het vindt Instellingen → Single sign-on, plus de knop 'Inloggen met ...' op de inlogpagina.
Lees de handleiding