Bedrijfslogin¶

Met een bedrijfslogin loggen de mensen van je organisatie in OS in met het account dat ze al bij jullie eigen identiteitsprovider hebben, zoals Microsoft Entra ID, Google Workspace of Okta, via OpenID Connect of SAML. Deze pagina laat zien hoe je een bedrijfslogin instelt, uitprobeert, verplicht maakt, wie zich zonder kan aanmelden, wie zich zelf kan aansluiten en hoe je hem weer verwijdert. Er is hiervoor nog geen scherm: een beheerder gebruikt de API van OS, met de routes die hieronder staan.

Wie wat mag¶

Een org-admin van de organisatie kan de bedrijfslogin instellen, wijzigen en verwijderen. Wie de bedrijfslogin instelt, moet ook het domein mogen beheren waar hij bij hoort (Rollen beheren). Elk lid kan lezen hoe de login staat.

Een organisatie heeft hoogstens één bedrijfslogin. Die hoort bij één domein dat je organisatie heeft bewezen, bijvoorbeeld jansen.nl (Domeinen en adressen). Bewijs het domein dus eerst.

Een OpenID Connect-login instellen¶

1. Maak bij je identiteitsprovider een applicatie aan voor OS. Je krijgt een client-id en een geheim.

2. Stel de login in met PUT /api/v1/organisations/{id}/company-login en de kop If-Match: "0":

   Veld	Wat je invult
   kind	oidc
   display_name	de naam op de inlogpagina, hoogstens 64 tekens, bijvoorbeeld Jansen
   domain	het bewezen domein, bijvoorbeeld jansen.nl
   authorization_url, token_url, jwks_url, issuer	de adressen van je provider; ze staan in het discovery-document van de provider (/.well-known/openid-configuration)
   client_id, client_secret	wat je provider gaf
   client_auth_method	client_secret_basic of client_secret_post, zoals je provider het vraagt

3. OS antwoordt 202 met de login, status pending. Lees in het antwoord redirect_uri en voeg dat adres bij je provider toe als redirect-adres van de applicatie. Het adres eindigt op /broker/os-<id van je organisatie>/endpoint.

Elk adres moet met https:// beginnen, een hostnaam noemen (geen IP-adres), geen poort behalve 443 hebben en hoogstens 2.048 tekens lang zijn. Het geheim staat in geen enkel antwoord: OS bewaart het versleuteld tot de login actief is en gooit het dan weg.

Een SAML-login instellen¶

Stel de login in met dezelfde route en kind: saml:

Geef je provider daarna het adres uit metadata_url in het antwoord: daar staat alles wat je provider over OS moet weten. OS vraagt om ondertekende antwoorden en om het e-mailadres als NameID.

Wat de status zegt¶

OS zet de login in Keycloak, de inlogdienst van OS, en leest hem daarna terug. GET /api/v1/organisations/{id}/company-login laat zien hoe ver dat is:

Weigert de inlogdienst een wijziging van een login die al werkte, dan blijft de vorige versie werken: applied_version noemt die versie. Nam de inlogdienst de nieuwe instellingen wel aan en mislukte daarna een volgende stap, dan gelden de nieuwe instellingen al; controleer ze en stel de login opnieuw in, met het geheim.

De login uitproberen¶

OS roept je provider zelf nooit aan, dus er is geen knop die de login test. Probeer hem zelf: open een privévenster, ga naar OS en log in met een adres in je domein. Het antwoord noemt ook sign_in_hint; daarmee stuurt OS iemand meteen naar je provider. Doe dit voordat je de login verplicht maakt.

De login verplicht maken¶

Is de login verplicht, dan komt een lid alleen in je organisatie als hij via de bedrijfslogin is ingelogd. Zet het aan met PATCH /api/v1/organisations/{id}/company-login en {"required": true}, met in If-Match de versie die je las.

OS weigert dat (409) zolang de login niet actief is, of als je zelf niet via de login bent ingelogd, geen uitzondering bent en de organisatie niet van boven beheert. Zo sluit je jezelf niet buiten met een login die niet werkt.

Een lid dat op een andere manier is ingelogd, krijgt 403 met het probleemtype company-login-required en de sign_in_hint van je login; OS logt hem dan uit en opnieuw in via de bedrijfslogin. Een beheerder van een partner die je organisatie van boven beheert, valt onder de regel van zijn eigen organisatie, niet onder die van jou.

Uitzonderingen¶

Voor de dag dat je provider niet werkt, mag je hoogstens drie leden aanwijzen die ook op een andere manier mogen inloggen. PUT /api/v1/organisations/{id}/company-login/exemptions/{membership_id} voegt een lid toe, DELETE op hetzelfde adres haalt hem weg. Het antwoord noemt ze onder exemptions. Een uitzondering vervalt als het lidmaatschap wordt gedeactiveerd of verwijderd. Elke keer dat een uitzondering op een andere manier inlogt, staat in het auditlog.

Je kunt ook iemand uitnodigen van wie het adres buiten het domein van je login valt, zoals een externe adviseur, met een van de drie uitzonderingen: "company_login_exempt": true in de body van POST /api/v1/organisations/{id}/invitations. De uitnodiging telt dan mee voor de drie en staat meteen onder exemptions; de persoon houdt de uitzondering bij het accepteren, en ze vervalt als de uitnodiging wordt ingetrokken of verloopt.

Zelf aansluiten¶

joining bepaalt wat er gebeurt met iemand die via de bedrijfslogin inlogt met een adres in je domein, maar nog geen lid is:

Wijzig het met PATCH en {"joining": "automatic"}. Aansluiten werkt ook voor iemand die voor het eerst via de bedrijfslogin inlogt: OS neemt zijn adres daarvoor aan omdat het in je bewezen domein ligt en hij via jullie eigen login binnenkwam.

De login wijzigen¶

Stuur de hele login opnieuw met PUT, met in If-Match de versie die je las, en het geheim erbij. Het soort (oidc of saml) kan niet veranderen; haal de login dan weg en stel een nieuwe in. Tot de inlogdienst de wijziging aanneemt, blijft de vorige versie werken.

De login verwijderen¶

DELETE /api/v1/organisations/{id}/company-login, met If-Match, haalt de login weg. Hij is dan meteen niet meer verplicht en de uitzonderingen vervallen. De leden en hun accounts blijven: wie ook een wachtwoord heeft, logt daarmee in; wie alleen via de bedrijfslogin inlogde, stelt een wachtwoord in via Wachtwoord vergeten? op de inlogpagina. Geef je het domein op, dan verdwijnt de login vanzelf mee (Domeinen en adressen).

Wanneer OS weigert¶

Wat OS bewaakt¶

OS controleert elke vijf minuten of je login in de inlogdienst nog staat zoals OS hem zette, en zet terug wat iemand buiten OS veranderde. Daar hoef je niets voor te doen. Elke wijziging die je maakt, staat in het auditlog, zonder het geheim.