Firmenanmeldung¶

Mit einer Firmenanmeldung melden sich die Personen Ihrer Organisation bei OS mit dem Konto an, das sie bereits bei Ihrem eigenen Identitätsanbieter haben, etwa Microsoft Entra ID, Google Workspace oder Okta, über OpenID Connect oder SAML. Diese Seite zeigt, wie Sie eine Firmenanmeldung einrichten, ausprobieren und verpflichtend machen, wer sich auch ohne sie anmelden darf, wer sich selbst anschließen kann und wie Sie sie wieder entfernen. Dafür gibt es noch keinen Bildschirm: Ein Administrator nutzt die API von OS, mit den Routen unten.

Wer was darf¶

Ein org-admin der Organisation kann die Firmenanmeldung einrichten, ändern und entfernen. Wer sie einrichtet, muss auch die Domain verwalten dürfen, zu der sie gehört (Rollen verwalten). Jedes Mitglied kann lesen, wie die Anmeldung steht.

Eine Organisation hat höchstens eine Firmenanmeldung. Sie gehört zu einer Domain, die Ihre Organisation nachgewiesen hat, zum Beispiel jansen.de (Domains und Adressen). Weisen Sie die Domain also zuerst nach.

Eine OpenID-Connect-Anmeldung einrichten¶

1. Legen Sie bei Ihrem Identitätsanbieter eine Anwendung für OS an. Sie erhalten eine Client-ID und ein Geheimnis.

2. Richten Sie die Anmeldung mit PUT /api/v1/organisations/{id}/company-login und dem Header If-Match: "0" ein:

   Feld	Was Sie eintragen
   kind	oidc
   display_name	der Name auf der Anmeldeseite, höchstens 64 Zeichen, zum Beispiel Jansen
   domain	die nachgewiesene Domain, zum Beispiel jansen.de
   authorization_url, token_url, jwks_url, issuer	die Adressen Ihres Anbieters; sie stehen im Discovery-Dokument des Anbieters (/.well-known/openid-configuration)
   client_id, client_secret	was Ihr Anbieter Ihnen gegeben hat
   client_auth_method	client_secret_basic oder client_secret_post, wie Ihr Anbieter es verlangt

3. OS antwortet mit 202 und der Anmeldung im Status pending. Lesen Sie in der Antwort redirect_uri und tragen Sie diese Adresse bei Ihrem Anbieter als Weiterleitungsadresse der Anwendung ein. Sie endet auf /broker/os-<ID Ihrer Organisation>/endpoint.

Jede Adresse muss mit https:// beginnen, einen Hostnamen nennen (keine IP-Adresse), darf nur den Port 443 haben und höchstens 2.048 Zeichen lang sein. Das Geheimnis steht in keiner Antwort: OS bewahrt es verschlüsselt auf, bis die Anmeldung aktiv ist, und verwirft es dann.

Eine SAML-Anmeldung einrichten¶

Richten Sie die Anmeldung mit derselben Route und kind: saml ein:

Geben Sie Ihrem Anbieter danach die Adresse aus metadata_url in der Antwort: Dort steht alles, was Ihr Anbieter über OS wissen muss. OS verlangt signierte Antworten und die E-Mail-Adresse als NameID.

Was der Status sagt¶

OS legt die Anmeldung in Keycloak an, dem Anmeldedienst von OS, und liest sie danach zurück. GET /api/v1/organisations/{id}/company-login zeigt, wie weit das ist:

Lehnt der Anmeldedienst eine Änderung an einer bereits funktionierenden Anmeldung ab, funktioniert die vorherige Version weiter: applied_version nennt diese Version. Hat der Anmeldedienst die neuen Einstellungen angenommen und ist danach ein weiterer Schritt gescheitert, gelten die neuen Einstellungen bereits; prüfen Sie sie und richten Sie die Anmeldung erneut ein, mit dem Geheimnis.

Die Anmeldung ausprobieren¶

OS ruft Ihren Anbieter nie selbst auf, daher gibt es keine Schaltfläche, die die Anmeldung testet. Probieren Sie sie selbst aus: Öffnen Sie ein privates Fenster, rufen Sie OS auf und melden Sie sich mit einer Adresse in Ihrer Domain an. Die Antwort nennt auch sign_in_hint; damit schickt OS eine Person direkt zu Ihrem Anbieter. Tun Sie das, bevor Sie die Anmeldung verpflichtend machen.

Die Anmeldung verpflichtend machen¶

Ist die Anmeldung verpflichtend, gelangt ein Mitglied nur dann in Ihre Organisation, wenn es sich über die Firmenanmeldung angemeldet hat. Schalten Sie das mit PATCH /api/v1/organisations/{id}/company-login und {"required": true} ein, mit der gelesenen Version in If-Match.

OS lehnt das ab (409), solange die Anmeldung nicht aktiv ist oder wenn Sie sich nicht selbst über die Anmeldung angemeldet haben, keine Ausnahme sind und die Organisation nicht von oben verwalten. So sperren Sie sich nicht mit einer Anmeldung aus, die nicht funktioniert.

Ein Mitglied, das sich auf andere Weise angemeldet hat, erhält 403 mit dem Problemtyp company-login-required und dem sign_in_hint Ihrer Anmeldung; OS meldet es dann ab und über die Firmenanmeldung wieder an. Ein Administrator eines Partners, der Ihre Organisation von oben verwaltet, unterliegt der Regel seiner eigenen Organisation, nicht Ihrer.

Ausnahmen¶

Für den Tag, an dem Ihr Anbieter nicht funktioniert, dürfen Sie höchstens drei Mitglieder benennen, die sich auch auf andere Weise anmelden dürfen. PUT /api/v1/organisations/{id}/company-login/exemptions/{membership_id} fügt ein Mitglied hinzu, DELETE auf dieselbe Adresse nimmt es wieder heraus. Die Antwort nennt sie unter exemptions. Eine Ausnahme endet, wenn die Mitgliedschaft deaktiviert oder entfernt wird. Jedes Mal, wenn sich eine Ausnahme auf andere Weise anmeldet, steht das im Prüfprotokoll.

Sie können auch jemanden einladen, dessen Adresse außerhalb der Domain liegt, die Ihre Anmeldung steuert, etwa eine externe Beraterin, mit einer der drei Ausnahmen: "company_login_exempt": true im Body von POST /api/v1/organisations/{id}/invitations. Die Einladung zählt dann zu den dreien und steht sofort unter exemptions; die Person behält die Ausnahme, wenn sie annimmt, und sie endet, wenn die Einladung zurückgezogen wird oder abläuft.

Sich selbst anschließen¶

joining bestimmt, was mit einer Person geschieht, die sich über die Firmenanmeldung mit einer Adresse in Ihrer Domain anmeldet, aber noch kein Mitglied ist:

Ändern Sie es mit PATCH und {"joining": "automatic"}. Das Anschließen funktioniert auch bei einer Person, die sich zum ersten Mal über die Firmenanmeldung anmeldet: OS akzeptiert dafür ihre Adresse, weil sie in Ihrer nachgewiesenen Domain liegt und die Person über Ihre eigene Anmeldung gekommen ist.

Die Anmeldung ändern¶

Senden Sie die ganze Anmeldung erneut mit PUT, mit der gelesenen Version in If-Match und dem Geheimnis dabei. Die Art (oidc oder saml) lässt sich nicht ändern; entfernen Sie die Anmeldung dann und richten Sie eine neue ein. Bis der Anmeldedienst die Änderung annimmt, funktioniert die vorherige Version weiter.

Die Anmeldung entfernen¶

DELETE /api/v1/organisations/{id}/company-login, mit If-Match, entfernt die Anmeldung. Sie ist dann sofort nicht mehr verpflichtend, und die Ausnahmen enden. Die Mitglieder und ihre Konten bleiben: Wer auch ein Passwort hat, meldet sich damit an; wer sich nur über die Firmenanmeldung angemeldet hat, legt über Passwort vergessen? auf der Anmeldeseite ein Passwort fest. Geben Sie die Domain auf, verschwindet die Anmeldung mit ihr (Domains und Adressen).

Wenn OS ablehnt¶

Was OS überwacht¶

Alle fünf Minuten prüft OS, ob Ihre Anmeldung im Anmeldedienst noch so steht, wie OS sie eingerichtet hat, und stellt wieder her, was jemand außerhalb von OS geändert hat. Dafür müssen Sie nichts tun. Jede Änderung, die Sie vornehmen, steht im Prüfprotokoll, ohne das Geheimnis.