Die folgende Konfigurationsanleitung zeigt am Beispiel von Okta, wie Sie Ihre DocuWare Organisation mit einem Identity Provider verbinden, um Single-Sign-On in DocuWare zu nutzen.
Die wesentlichen Schritte sind bei anderen Identity Providern ähnlich, können sich aber im Detail unterscheiden.
1. In DocuWare Single Sign-on aktivieren
Wählen Sie unter DocuWare Konfiguration > Organisations-Einstellungen > Sicherheit die Option Single-Sign-On bei Ihrem Identity Provider aktivieren.
Klicken Sie auf Verbindung für Single-Sign-On konfigurieren.
.png "image(77).png")
Es öffnet sich ein neuer Dialog. Wählen Sie als Identity Provider die Option Generischer OpenID Connect Provider. Daraufhin werden eine Reihe von Feldern für die Konfiguration angezeigt – siehe den Screenshot unten. Die Einträge für diese Felder (bis auf Callback URL) übernehmen Sie aus Ihrer Octa Plattform, nachdem Sie dort eine Anwendung und einen Authorization Server für die Verbindung mit Docuware angelegt haben.
.png "image(78).png")
2. In Okta neue Anwendung für DocuWare erstellen
Wechseln Sie zu Ihrer Octa Plattform und legen Sie dort eine neue App an, in der die Einstellungen der Verbindung zu DocuWare gespeichert werden:
Okta > Applications > Create App Integration
.png "image(79).png")
Als Sign-in Methode wählen Sie OIDC – OpenID Connect und als Anwendungstyp Web Application, wie im folgenden Screenshot gezeigt.
.png "image(80).png")
Mit Next gelangen Sie zu den General Settings.
Geben Sie der App einen Namen, z.B. DocuWare. Der Name ist frei wählbar. Er ist nur in der Okta Plattform zu sehen.
Aktivieren Sie in den General Settings zudem den Grant type: Client Credentials und kopieren Sie aus DocuWare die Callback URL in die Zeile Sign-in Redirect URIs.
.png "image(81).png")
Sie finden die Callback URL im Dialog Single-Sign-On-Verbindung konfigurieren in den DocuWare Organisationseinstellungen (siehe auch Punkt 1).
.png "image(82).png")
Wählen Sie nun unter Assignments die gewünschte Zugangsart und speichern Sie die neue App:
.png "image(83).png")
3. In Okta Authoriztation Server für DocuWare erstellen
Gehen Sie zu Okta > Security > API > Authorization Servers > Add Authorization Server:
.png "image(84).png")
Der Name für den Authorization Server ist wie im Falle der App frei wählbar. In das Feld Audience geben Sie wie gezeigt api://docuware ein.
.png "image(85).png")
Anschließend wird der neue Authorization Server im Bereich API von Okta aufgelistet:
.png "image(86).png")
4. Provider URL aus Okta in DocuWare eintragen
In den Einstellungen vom Authorization Server finden Sie die Metadata URI. Dies ist die URL, mit der DocuWare Okta als Identity Provider aufrufen kann.
Okta > Security > API > Authorization Servers > Your Authorization Server for DocuWare > Settings > Metadata URI.
.png "image(87).png")
Kopieren Sie die Metadata URI und geben Sie diese in DocuWare in das Feld Issuer URL ein:
.png "image(88).png")
5. Client ID und Client Secret aus Okta übertragen
In den Einstellungen der App, die Sie in Schritt 2 angelegt haben, finden Sie die Client ID und können den Client Secret generieren. Dies sind Kennungen, mit deren Hilfe sich die Applikationen untereinander identifizieren können.
Gehen Sie zu Okta > Applications > Your application for DocuWare > General.
.png "image(89).png")
Client ID und Client Secret tragen Sie in DocuWare in die Felder Client ID und Client Secret Key ein.
6. In Okta eine Access Policy hinzufügen
Mit der Access Policy verbinden Sie in Okta den Authorization Server und die App, die Sie für DocuWare angelegt haben.
Gehen Sie zu Okta > Security > API > Authorization Servers > Your Authentication Server for DocuWare > Access Policies > Add Policy.
.png "image(90).png")
Name und Beschreibung sind für die neue Policy frei wählbar.
Wählen Sie unter Assign to die Anwendung aus, die Sie in Schritt 2 für DocuWare angelegt haben, und erstellen Sie die Policy.
.png "image(91).png")
Fügen Sie dann mit dem Button Add Rule der Policy eine neue Regel hinzu.
.png "image(92).png")
Aktivieren Sie für die Regel folgende Einstellungen (empfohen):
Grant type > Client acting on behalf of itself > Client Credentials
Grant type > Client acting on behalf of a user > Authorization Code
Grant type > Client acting on behalf of a user > Implicit (hybrid)
Grant type > Client acting on behalf of a user > Resource Owner password
Grant type > Client acting on behalf of a user > SAML 2.0 Assertion
Grant type > Client acting on behalf of a user > Device Authorization
Grant type > Client acting on behalf of a user > Token Exchange
AND
User is: Any user assigned the app
AND
Scopes requested: Any scopes
AND
Use this inline hook: None(disabled)
AND
Access token lifetime is 1 Hour
AND
Refresh token lifetime is: Unlimited but will expire if not used every 7 Days
.png "image(93).png")
7. Attribute definieren und zuordnen
Damit die DocuWare Benutzer den Identitäten, die in Okta hinterlegt sind, zugeordnet werden können, definieren Sie zunächst in Okta die Eigenschaften für die Identitäten und tragen dann diese Eigenschaften in DocuWare ein.
Ein Hinweis zur Begriffsklärung: Die Eigenschaften der Identitäten werden in DocuWare „Attribute“ genannt und in Okta „Claims“.
DocuWare fragt für das Mapping vier Attribute ab:
E-Mail
Benutzername
Externe ID
ID des externen Providers
Die Attribute werden in Docuware im Dialog Single-Sign-On-Verbindung konfigurieren eingegeben (siehe Schritt 1):
.png "image(94).png")
Um die Eigenschaften in Okta zu definieren, öffnen Sie in Okta den Authorization Server, den Sie für DocuWare angelegt haben:
Okta > Security > API > Authorization Servers > Authorization Server for DocuWare.
Klicken Sie auf Add Claim.
.png "image(95).png")
Erstellen Sie einen Claim für das Attribut „E-Mail".
Der Name – hier „dw_mail" ist frei wählbar. Wichtig ist nur, dass der Name, den Sie hier eingeben, genau so bei DocuWare eingegeben wird.
Der Wert (value) user.email ist von Okta vordefiniert und muss hier genau so mit den hier gezeigten eingegeben werden.
Include in token type: ID Token / Always
Value Type: Expression
Value: user.email
Disable claim: none
Include in: Any scope
.png "image(96).png")
Erstellen Sie einen Claim für das Attribut „Username“.
Der Name – hier „dw_username“ ist frei wählbar. Wichtig ist nur, dass der Name, den Sie hier eingeben, genau so bei DocuWare eingegeben wird.
Der Wert (value) user.username ist von Okta vordefiniert und muss hier genau so eingegeben werden.
Include in token type: ID Token / Always
Value Type: Expression
Value: user.username
Disable claim: none
Include in: Any scope
.png "image(97).png")
Erstellen Sie einen Claim für das Attribut „Externe ID“.
Die externe ID ist die eindeutige Nummer des Benutzers in Okta. Der Name für diesen Claim – hier „dw_externalid“ ist frei wählbar. Wichtig ist nur, dass der Name, den Sie hier eingeben, genau so bei DocuWare eingegeben wird.
Der Wert (value) user.id ist von Okta vordefiniert und muss hier genau so eingegeben werden.
Include in token type: ID Token / Always
Value Type: Expression
Value: user.id
Disable claim: none
Include in: Any scope
.png "image(98).png")
Damit die Identitäten aus Okta in DocuWare übernommen werden können, stellen Sie sicher, dass das Attribut External ID wirklich user.id zugeordnet wird.
Erstellen Sie einen Claim für das Attribut „External Provider“.
Der Name für diesen Claim – hier „dw_provider“ ist frei wählbar. Wichtig ist nur, dass der Name, den Sie hier eingeben, genau so bei DocuWare eingegeben wird.
Den Wert (value) finden Sie im Okta Authorization Server für DocuWare. Sie finden die ID in der Übersicht der Authentication Server, wie es hier auf dem Screenshot gezeigt wird.
.png "image(99).png")
Geben Sie diesen Wert in dies Zeile value mit Anführungszeichen ein.
Include in token type: ID Token / Always
Value Type: Expression
Value: “xxxxxxxxxx”
Disable claim: none
Include in: Any scope
.png "image(100).png")
In dem bisher beschriebenen Beispiel werden also folgende Okta Claims in DocuWare als Attribute eingetragen:
.png "image(101).png")
Damit ist die Konfiguration fertig und Sie können Single Sign-on in DocuWare verwenden.
8. Benutzer zur DocuWare Anwendung in Okta hinzufügen
Die Benutzer, die sich in DocuWare mit Single Sign-on anmelden können sollen, müssen der DocuWare Anwendung in Okta zugewiesen sein.
Rufen Sie dafür in Okta die Anwendung für DocuWare auf: Applications > Application X (DocuWare) auf. Wechseln Sie zu Assignments.
.png "image(102).png")
Vergewissern Sie sich, dass bei der Zuweisung eines Benutzers das Feld für den Benutzernamen mit seiner E-Mail-Adresse ausgefüllt ist.
.png "image(103).png")
9. In DocuWare die Option "Vorhandene Benutzere automatisch zuordnen" aktivieren
Damit Single Sign-On mit Okta funktioniert, aktivieren Sie in der DocuWare Konfiguration in den Organisationseinstellungen > Sicherheit die Option Bestehende Benutzer bei Anmeldung automatisch verknüpfen.
.png "image(104).png")
Außerdem muss der Benutzername in DocuWare mit dem vorderen Teil des Okta-Benutzernamens übereinstimmen:
Okta-Benutzername: peggy.jenkins@petersengineering.com
DocuWare-Benutzername: peggy.jenkins
Bei der ersten Anmeldung eines Benutzers in DocuWare mit Okta Single Sign-On wird der entsprechende DocuWare Benutzer anhand des Benutzernamens identifiziert. Sobald die Benutzer in beiden Systemen einmal zugeordnet wurden, wird der DocuWare Benutzer anhand seiner externen Objekt-ID erkannt. Das heißt, auch wenn der Benutzername nicht mehr übereinstimmt, wird der Benutzer noch erkannt.