OAuth2-Provider

In DocBee können Sie externe OAuth2- bzw. OpenID-Connect‑Provider anbinden, um sich mit Single Sign‑On (SSO) anzumelden und Benutzer zentral zu verwalten.

Generelle Informationen

Was sind OAuth2-Provider?

OAuth2‑Provider stellen einen externen Identitätsanbieter dar (z.B. Keycloak, Microsoft Entra ID), über den sich Benutzer bei DocBee anmelden. Die Authentifizierung findet beim Provider statt, DocBee erhält lediglich ein Token mit den relevanten Benutzerdaten.

Wann sollten Sie OAuth2-Provider verwenden?

Wir empfehlen den Einsatz eines OAuth2‑Providers, wenn:

• Sie bereits ein zentrales Identity‑/Access‑Management im Unternehmen einsetzen.
• Benutzer sich mit denselben Anmeldedaten in mehreren Systemen anmelden sollen (Single Sign‑On).
• Benutzer- und Rolleninformationen möglichst automatisiert aus einem Verzeichnisdienst kommen sollen.

Konfiguration OAuth2-Provider

Die Konfiguration erfolgt über den Dialog OAuth2‑Provider‑Konfiguration.

Allgemeine Felder

Die folgenden Felder stehen unabhängig vom gewählten Provider‑Typ zur Verfügung.

Feld	Beschreibung
Name	Bezeichnung des Providers in DocBee, erscheint z.B. in der Login‑Auswahl.
Provider‑Typ	Auswahl des Typs (Keycloak oder Benutzerdefiniertes OpenIdConnect).
API‑Key	Client‑ID des OAuth2‑Clients beim Provider.
API‑Secret	Client‑Secret des OAuth2‑Clients beim Provider.
Scope	Liste der Scopes, die beim Login angefordert werden (z.B. openid profile email).
Session Dauer	Dauer der aktiven Session in Minuten, bevor der Benutzer sich erneut anmelden muss.
Benutzerkennung Eigenschaftsname	Claim‑Name im Token, der die eindeutige Benutzerkennung enthält (z.B. sub oder preferred_username).
Redirect URL	Von DocBee verwendete Redirect‑/Callback‑URL. Diese muss im Provider als erlaubte Redirect‑URL hinterlegt werden.

Optionen zur Benutzerverwaltung

Im unteren Bereich steuern Sie, wie DocBee mit Benutzern umgeht, die sich über den OAuth2‑Provider anmelden.

Verknüpfen von Benutzern erlaubt

• Wenn aktiviert, wird eine automatische Zuordnung zu bestehenden DocBee‑Benutzern vorgenommen.
• Für die Verknüpfung wird ein zusätzliches Pflichtfeld für die Verknüpfung eingeblendet.

Feld	Beschreibung
Verknüpfungs‑Benutzerkennung Eigenschaftsname	Claim im Token, über den ein bestehender Benutzer in DocBee gefunden wird. Der Wert dieses Datensatzes muss im Benutzer im Feld OAuth Kennung hinterlegt sein.

Typisches Szenario: Es existieren bereits Benutzer in DocBee, die über die OAuth2‑Kennung eindeutig identifiziert werden sollen.

Erzeugen von neuen Benutzern erlaubt

• Wenn aktiviert, dürfen aus erfolgreichen Logins neue DocBee‑Benutzer erzeugt werden.
• Für die Anlage werden zusätzliche Felder für die Eigenschafts-Verknüpfungen eingeblendet.

Aktualisieren von Benutzern erlaubt

• Wenn aktiviert, werden Benutzerdaten bei jeder Anmeldung aus den Token‑Daten aktualisiert.
• Die Konfiguration der zu aktualisierenden Felder entspricht der für das Erzeugen von Benutzern.

Eigenschafts-Verknüpfungen für Benutzer

Sowohl beim Erzeugen als auch beim Aktualisieren von Benutzern stehen dieselben Verknüpfungs‑Felder zur Verfügung. Tragen Sie hier die Claim‑Namen ein, wie sie im ID‑ oder Access‑Token Ihres Providers vorkommen. Nicht verwendete Felder können leer bleiben.

Feld	Beschreibung
Standard‑Rolle	Rolle, die neuen Benutzern zugewiesen wird, sofern keine Rolle aus dem Token zugewissen oder gefunden wurde.
Eigenschaftsname Benutzername	Claim im Token, der den Benutzernamen enthält (z.B. preferred_username).
Eigenschaftsname Name	Claim mit dem vollständigen Namen (z.B. name).
Eigenschaftsname E‑Mail	Claim mit der E‑Mail‑Adresse (z.B. email).
Eigenschaftsname Rolle	Optionaler Claim, dessen Wert den Namen einer Rolle in DocBee enthält.
Eigenschaftsname Mobil	Optionaler Claim mit der Mobilnummer.
Eigenschaftsname Telefon	Optionaler Claim mit der Telefonnummer.
Eigenschaftsname Externe ERP Nummer	Optionaler Claim mit der externen ERP‑Nummer.
Eigenschaftsname Kürzel	Optionaler Claim mit dem Benutzer‑Kürzel.
Eigenschaftsname Abteilung	Optionaler Claim mit dem Abteilungsnamen.

Provider-Typen

Provider‑Typ „Keycloak“

Bei Verwendung des Provider‑Typs Keycloak erscheinen folgende zusätzlich benötigte Felder.

Feld	Beschreibung
Provider Base URL	Basis‑URL des Keycloak‑Servers, z.B. https://keycloak.example.com.
Realm	Name des Realms, in dem der Client konfiguriert ist.

Die Endpunkte für Authorization und Token werden aus diesen Angaben automatisch abgeleitet.

Provider‑Typ „Benutzerdefiniertes OpenIdConnect“

Für generische OpenID‑Connect‑Provider steht der Typ „Benutzerdefiniertes OpenIdConnect“ zur Verfügung.

Feld	Beschreibung
AccessToken endpoint	Vollständige URL des Token‑Endpunkts, z.B. https://idp.example.com/oauth2/token.
Authorization Base URL	Basis‑URL für den Authorization‑Endpunkt, z.B. https://idp.example.com/oauth2/authorize.

Hinweise:

• Stellen Sie sicher, dass der konfigurierte Client im Provider die in DocBee verwendete Redirect‑URL erlaubt.
• Aktivieren Sie mindestens den Scope openid, damit ein ID‑Token mit Benutzerinformationen ausgegeben wird.
• Prüfen Sie, welche Claims der Provider ausliefert, und tragen Sie diese in den Feldern für die Benutzerattribute ein.

Beispielkonfigurationen

Beispielkonfiguration Keycloak

Einstellung	Wert (Beispiel)
Provider‑Typ	Keycloak
Provider Base URL	https://keycloak.example.com
Realm	docbee
API‑Key	Client‑ID aus Keycloak, z.B. docbee-web
API‑Secret	Zugehöriges Client‑Secret
Scope	openid profile email
Benutzerkennung Eigenschaftsname	preferred_username

Beispielkonfiguration Microsoft Entra ID (Azure AD)

Microsoft Entra ID (früher Azure AD) kann über den Typ „Benutzerdefiniertes OpenIdConnect“ angebunden werden.

Schritte in Microsoft Entra ID

1. In der Azure‑Portal‑Navigation Microsoft Entra ID > App-Registrierungen öffnen.
2. Neue Registrierung anlegen:
   • Name frei wählen (z.B. DocBee SSO).
   • Unterstützte Kontotypen nach Bedarf wählen (z.B. „Nur Konten in diesem Organisationsverzeichnis“).
   • Umleitungs-URI (Web) auf die in DocBee angezeigte Redirect‑URL setzen.
3. Nach dem Anlegen:
   • Unter Zertifikate & Geheimnisse einen neuen geheimen Clientschlüssel anlegen und den Wert notieren (API‑Secret).
   • Unter API-Berechtigungen die Microsoft Graph Berechtigungen openid, profile, email hinzufügen.
   • Im Bereich Authentifizierung sicherstellen, dass die Option „ID-Token“ für Web‑Anwendungen aktiviert ist.

Typische Claims im ID‑Token sind z.B. preferred_username, name und email.

Einstellungen in DocBee (Entra ID)

Einstellung	Wert (Beispiel)
Provider‑Typ	Benutzerdefiniertes OpenIdConnect
API‑Key	Anwendungs‑/Client‑ID der App‑Registrierung
API‑Secret	Geheimer Clientschlüssel
Scope	openid profile email
AccessToken endpoint	https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/token
Authorization Base URL	https://login.microsoftonline.com/<TENANT_ID>/oauth2/v2.0/authorize
Benutzerkennung Eigenschaftsname	z.B. preferred_username oder oid
Eigenschaftsname Benutzername	preferred_username
Eigenschaftsname Name	name
Eigenschaftsname E‑Mail	email

Ersetzen Sie <TENANT_ID> durch die Mandanten‑ID Ihres Entra‑Verzeichnisses oder verwenden Sie alternativ die Domain (z.B. contoso.onmicrosoft.com).