Single Sign On (SSO) in ControlOffice
Veel organisaties gebruiken één centraal systeem voor het identificeren en authentiseren van gebruikers, zoals bv. Entra ID van Microsoft. Dit noemen we een Identity & Access Management systeem (IAM). ControlOffice ondersteunt het OpenID Connect protocol om op zo’n IAM-systeem aan te sluiten.
Hybride oplossing
ControlOffice ondersteunt dit op een hybride manier. Dit betekent, dat het mogelijk is om in ControlOffice tegelijkertijd met ControlOffice- als met SSO-gebruikers te werken. Een SSO gebruiker kan herkend worden door het vinkje “Logt in via SSO” aangevinkt op de detailkaart van de gebruiker. Zo’n gebruiker kan niet met een gebruikersnaam en wachtwoord inloggen in ControlOffice, maar moet inloggen via de “Single Sign-On” knop in het inlogscherm.
Handmatig opvoeren
Om gebruikers middels SSO in te laten loggen, moeten ze bekend gemaakt worden in ControlOffice. Dit kan door zo’n gebruiker handmatig in te voeren, op dezelfde wijze als een “normale” ControlOffice gebruiker; een gebruiker wordt opgevoerd, gekoppeld aan gebruikersgroepen en aan een medewerker (of er wordt een nieuwe medewerker opgevoerd in ContolOffice).
De koppeling zelf is gebaseerd op de gebruikersnaam; deze moet overeenkomen met de waarde in één van de “claims” die door het IAM-systeem. Dit kan bv. het email-adres van die gebruikers zijn. Bij het inrichten van de koppeling met het IAM-systeem kan bepaald worden welke “claim” gebruikt moet worden. Daarnaast moet het vinkje “Logt in via SSO” aangezet worden. Hierdoor herkent ControlOffice deze gebruiker als een SSO gebruiker.
Koppelen met IAM
Client in IAM-systeem
In het IAM-systeem moet een z.g. client geregistreerd worden. De benaming hiervoor verschilt per IAM-systeem (in Entra ID heet dit een “App registration”).
Deze client hoeft alleen inloggen en het lezen van het gebruikersprofiel te ondersteunen (in Entra ID is dit de API permissie “User.Read”).
Zorg er bij de configuratie voor, dat de client zowel access tokens als ID tokens kan maken.
Vanuit ControlOffice worden, bij het inlogproces, de OpenID Connect scopes “openid”, “email” en “offline_access” opgegeven. Zorg er voor, dat het IAM-systeem hier mee om kan gaan.
Ook is een redirect-URI nodig. Deze URI wordt gebruikt om, nadat het inloggen in het IAM-systeem in gelukt, terug te gaan naar ControlOffice. De redirect-URI is de URL naar de ControlOffice-website, gevolgd door “/signin-oidc”, dus bv. “https://uwbedrijf.controloffice.nl/signin-oidc”.
Koppeling registreren
Het registreren van een IAM koppeling moet door de ControlOffice back-office uitgevoerd worden; dit kan niet vanuit ControlOffice zelf ingesteld worden.
Om een koppeling te realiseren moeten in ControlOffice de volgende zaken geregistreerd worden:
- Authority: authority- of issuer-URI
voor Entra ID is dit https://login.microsoftonline.com/{tenant ID}/v2.0, dit tenant ID staat in de “overview blade” van een app registration
- Client ID: het ID waarmee het IAM-systeem de client identificeert
voor Entra ID is dit een UUID, die onder de naam “Application (client) ID” in de “overview blade” van een app registration
- Client Secret: het secret, waarmee toegang tot de client geautoriseerd wordt
in Entra ID kan een client gemaakt worden voor een app registration onder “Manage -> Certificates & secret”
- Username claim: de naam (volledig) van de claim die vergeleken wordt met de in ControlOffice opgeslagen gebruikersnaam
Om een email-adres te gebruikers als gebruikersnaam in ControlOffice, gebruik je bv. de claim “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress”