¶ Synchronisation der docuvita Benutzer mit dem Active Directory
ADSync synchronisiert und aktualisiert Benutzer und Benutzergruppen in docuvita aus Active Directory.
¶ Systemvoraussetzungen
- Windows Server ab 2012 64-bit, alternativ Windows 10/11 64-bit
- docuvita Version 20.1.xx und höher
- .NET-Framework ab Version 4.8
- Eine Internetverbindung für die Aktivierung und die regelmäßige Validierung der Lizenz
- AD Server
¶ Installation
Um die AD Synchronisation verwenden zu können, sind folgende Schritte notwendig:
¶ Installationskomponenten
| Komponente | Erforderlich | Beschreibung |
|---|---|---|
| dvs.ADSync | Ja | Der dvs.ADSync ist ein eigenständiger Windows Dienst, der dafür zuständig ist, Benutzer und Benutzergruppen vom Active Directory abzurufen und in docuvita anzulegen bzw. zu aktualisieren. |
| fd.Password.Encrypt | Optional | Mit diesem Programm können Sie Ihre Passwörter verschlüsseln und diese dann in der Konfigurationsdatei speichern. |
Komponenten
Nach erfolgreicher Installation sind die einzelnen Komponenten in dem Installationsverzeichnis zu finden. Der Standardinstallationsordner lautet C:\Program Files (x86)\docuvita\fd.ADSync\.
¶ Installation
Dieses Kapitel enthält Informationen, die für eine erfolgreiche Installation des ADSync durchzuführen sind.
Aministrator Rechte
Für die Installation des ADSync sind Administratorrechte erforderlich.
Führen Sie die Datei fd.ADSync xx.xx.xx.msi aus.
Zum Download...
Im nachfolgenden Schritt erscheint ein Fenster. Klicken Sie auf Weiter um mit der Installation zu beginnen.
Lesen Sie sich die Lizenzvereinbarung durch und bestätigen Sie diese.
Lizenzvertrag
Der Lizenzvertrag ist nach der Installation im help-Ordner zu finden.
Im nächsten Schritt werden Sie nach dem Lizenzschlüssel gefragt.
Lizenzdatei
Nach erfolgreicher Installation muss die Lizenzdatei noch direkt in das Installationsverzeichnis abgelegt werden.
Im nächsten Schritt haben Sie die Möglichkeit den Ablageort für die Log-Dateien anzupassen.
Im darauf folgenden Fenster können Sie den Installationsordner sowie die zu installierenden Komponenten auswählen.
Anschließend kann die Installation gestartet werden, in dem Sie auf Installieren klicken.
Nach einer erfolgreichen Installation erscheint abschließend folgendes Fenster.
¶ docuvita Einstellungen
In diesem Kapitel finden Sie alle notwendigen Einstellungen, die Sie in Ihrem docuvita vornehmen müssen.
¶ docuvita Benutzer anlegen *
Die komplette Kommunikation des ADSync mit docuvita erfolgt über die docuvita API. Aus diesem Grund muss ein docuvita-API-Benutzer im System vorhanden sein. Eine Anleitung zum Anlegen eines neuen Benutzers finden Sie hier.
¶ ActiveDirectory Integration
Bei der Verwendung von ActiveDirectory können die E-Mail-Adressen direkt per LDAP Abfrage des AD-Servers gelesen werden. Diese so ermittelten Adressen werden dann auch für die Vergabe der Zugriffsrechte auf die archivierten E-Mails verwendet. Wird eine E-Mail archiviert und gibt es dazu keinen passenden Benutzer in docuvita, so kann dieser auch automatisch angelegt werden. Folgende Einstellungen werden für den docuvita Benutzer hinterlegt:
- Standardmäßig wird die primäre SMTP-Adresse als Benutzername verwendet. In der Konfigurationsdatei des ADSync können weitere Konfigurationen zur Namens- und Passwortvergabe hinterlegt werden.
- Die primäre SMTP-Adresse des ActiveDirectory-Benutzers wird in das Feld E-Mail-Adresse eingetragen.
- Die Anlage des Benutzers erfolgt in der docuvita-Gruppe UserParentObjectId der jeweiligen Postbox-Konfiguration.
Bei der Verwendung der ActiveDirectory Integration müssen die E-Mail-Adressen nicht mehr im docuvita Benutzerstamm gepflegt werden. Es können hier aber zusätzliche E-Mail-Adressen eingetragen werden.
¶ Konfiguration
Im folgenden Abschnitt werden wir Ihnen zeigen, wie der ADSync zu konfigurieren ist. Die Konfigurationsdatei befindet sich im Installationsodner im Unterordner Config. Sie enthält die Beschreibung von einem oder mehreren AD-Servern, deren Konfiguration ihrerseits mehrere Sektionen beinhalten, die hier der Reihenfolge nach beschrieben werden.
Änderung der Konfiguration
Nach einer Änderung der Konfigurationsdatei ist ein Neustart des Dienstes fd.ADSync zwingend notwendig.
¶ ADServers
Klicken Sie hier, um die ADServers-Konfiguration zu sehen
"ADServers": [
"Settings": [],
"SmtpSettings": [],
"ADSettings": [],
"ADFieldMappingsSettings": [],
"DocuvitaSettings": [],
"SyncSettings": []
]
| Feldname | Beschreibung |
|---|---|
| Settings | Allgemeine Einstellungen |
| SmtpSettings | Smtp Einstellungen für Benaxchrichtigungsversand |
| ADSettings | Active Directory Einstellungen |
| ADFieldMappingsSettings | Active Directory Feldzuordnungen |
| DocuvitaSettings | docuvita Einstellungen |
| SyncSettings | Synchronisierungs-Einstellungen |
¶ Settings
Klicken Sie hier, um die Settings-Konfiguration zu sehen
"Settings": [
{
"FieldName": "SimulationMode",
"FieldTyp": "B",
"FieldValue": false,
"FieldDesription": "If true no changes will be written to docuvita and no notification mails will be sent"
},
{
"FieldName": "SyncIntervall",
"FieldTyp": "N",
"FieldValue": 5,
"FieldDesription": "Time in minutes between two batch runs (synchronisation interval)"
}
]
| Feldname | Typ | Beschreibung |
|---|---|---|
| SimulationMode | String | Simulationsmodus; wenn true, werden keine Änderungen nach docuvita geschrieben und keine Mailmitteilungen verschickt |
| SyncIntervall | Numeric | Intervall zwischen Synchronisierungsläufen in Minuten |
¶ SMTP
Klicken Sie hier, um die SMTP-Konfiguration zu sehen
"SmtpSettings": [
{
"FieldName": "SmtpHost",
"FieldTyp": "S",
"FieldValue": "localhost",
"FieldDesription": "Hostname or IP address of the SMTP server for sending mail notifications"
},
{
"FieldName": "SmtpPassword",
"FieldTyp": "S",
"FieldValue": "Sercret",
"FieldDesription": "SMTP password for sending emails"
},
{
"FieldName": "SmtpUser",
"FieldTyp": "S",
"FieldValue": "username",
"FieldDesription": "SMTP username"
},
{
"FieldName": "SmtpPort",
"FieldTyp": "N",
"FieldValue": 587,
"FieldDesription": "SMTP server port "
},
{
"FieldName": "SmtpSecure",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "Determines wether to use SMTP with SSL or not"
},
{
"FieldName": "AcceptAllCertificates",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "Determines wether to accept all SSL-certificates or not"
},
{
"FieldName": "MailNewUserFromAddress",
"FieldTyp": "S",
"FieldValue": "administrator@dev.local",
"FieldDesription": "The email adress which should be used for sending emails"
},
{
"FieldName": "MailNewUserNotification",
"FieldTyp": "B",
"FieldValue": false,
"FieldDesription": "Determines wether to send a notification when a new user has been created or not. Set to false if you are using the windows login provider (default)"
},
{
"FieldName": "MailNewUserToAddress",
"FieldTyp": "S",
"FieldValue": "Email to send to",
"FieldDesription": "If set, a notification with username and password is sent to this mail address when a new user has been created."
},
{
"FieldName": "UserNotificationSubject",
"FieldTyp": "S",
"FieldValue": "Für Sie wurde ein docuvita-Benutzer angelegt",
"FieldDesription": "Subject text for user notification mails.Placeholders can be used: @@Username@@, @@Password@@, @@docuvitaURL@@"
},
{
"FieldName": "UserNotificationBodyText",
"FieldTyp": "S",
"FieldValue": "Sehr geehrter doucvita Anwender,\n soeben wurde für Sie ein neuer docuvita - Benutzer angelegt.\n Hier sind Ihre Zugangsdaten:\nBenutzername: @@USERNAME@@\nPasswort: @@Password@@\n\nHier können Sie sich direkt anmelden: @@docuvitaURL@@\nBei der ersten Anmeldung müssen Sie Ihr Passwort ändern.\n\nMit freundlichen Grüßen\nIhr docuvita Team - support@docuvita - online.de",
"FieldDesription": "Body text for user notification mails.Placeholders can be used: @@Username@@, @@Password@@, @@docuvitaURL@@"
},
{
"FieldName": "AdminNotificationSubject",
"FieldTyp": "S",
"FieldValue": "docuvita-Benutzer @@USERNAME@@ wurde automatisch angelegt",
"FieldDesription": "Subject text for admin notification mails.Placeholders can be used: @@Username@@, @@Password@@, @@docuvitaURL@@"
},
{
"FieldName": "AdminNotificationBodyText",
"FieldTyp": "S",
"FieldValue": "Folgender docuvita-Benutzer wurde soeben neu angelegt: @@USERNAME@@",
"FieldDesription": "Body text for admin notification mails.Placeholders can be used: @@Username@@, @@Password@@, @@docuvitaURL@@"
}
]
| Feldname | Typ | Beschreibung |
|---|---|---|
| SmtpHost | String | Host oder IP-Adresse des SMTP-Server |
| SmtpPassword | String | SMTP-Passwort |
| SmtpUser | String | SMTP-Benutzer |
| SmtpPort | Numeric | SMTP-Port |
| SmtpSecure | Boolean | Wenn true, wird SSL beim Senden verwendet. |
| AcceptAllCertificates | Boolean | Akzeptiert alle SSL-Zertifikate (auch ungültige). |
| MailNewUserFromAdress | String | Absender-E-Mail-Adresse für die Benachrichtigungen |
| MailNewUserNotification | Boolean | Wenn true, wird eine Benachrichtigungs E-Mail, bei der Erstellung eines neuen Benutzer, an die Benutzer E-Mail-Adresse gesendet. |
| MailNewUserToAdress | String | Zusätzlich kann auch bei der Erstellung eines neuen Benutzers eine Benachrichtigung (Admin) an diese Adresse gesendet werden. |
| UserNotificationSubject | String | E-Mail Betreff der Benutzerenachrichtigungs-E-Mail. Folgende Platzhalter können verwendet werden:
|
| UserNotificationBodyText | String | Nachricht der Benutzerbenachrichtigungs-E-Mail. Folgende Platzhalter können verwendet werden:
|
| AdminNotificationSubject | String | Subjekt der Benutzerbenachrichtigungs-E-Mail. Folgende Platzhalter können verwendet werden:
|
| AdminNotificationBodyText | String | Nachricht der Adminbenachrichtigungs-E-Mail. Folgende Platzhalter können verwendet werden:
|
¶ ADSettings
Klicken Sie hier, um die ADSettings-Konfiguration zu sehen
"ADSettings": [
{
"FieldName": "Server",
"FieldTyp": "S",
"FieldValue": "DEVSRVAD",
"FieldDesription": "Active Directory Server: Servername or IP-address of the LDAP / AD Server"
},
{
"FieldName": "GroupPath",
"FieldTyp": "S",
"FieldValue": "CN=Users,DC=dev,DC=local",
"FieldDesription": "Full qualified LDAP Path where to search for users e.g. OU=docuvita groups,DC=domain,DC=com"
},
{
"FieldName": "UserPath",
"FieldTyp": "S",
"FieldValue": "CN=Users,DC=dev,DC=local",
"FieldDesription": "Full qualified LDAP Path where to search for users e.g. OU=docuvita groups,DC=domain,DC=com"
},
{
"FieldName": "UseNTLMAuth",
"FieldTyp": "B",
"FieldValue": false,
"FieldDesription": "If false you must specify Username and Password for the LDAP server"
},
{
"FieldName": "AuthenticationConfigurationId",
"FieldTyp": "N",
"FieldValue": 1,
"FieldDesription": "ID of the Authentication module responsible for AD-Users"
},
{
"FieldName": "Username",
"FieldTyp": "S",
"FieldValue": "Testuser",
"FieldDesription": "Username for the LDAP server"
},
{
"FieldName": "Password",
"FieldTyp": "S",
"FieldValue": "Geheim1234",
"FieldDesription": "Password for the LDAP server"
},
{
"FieldName": "UserQueryString",
"FieldTyp": "S",
"FieldValue": "(!cn=HealthMailbox*)(!cn=SystemMailbox*)(!cn=FederatedEmail.*)(!cn=Migration.*)(!cn=DiscoverySearchMailbox*)",
"FieldDesription": "A query string to filter the user result. You can use the ADSI Editor to generate valid queries"
},
{
"FieldName": "GroupQueryString",
"FieldTyp": "S",
"FieldValue": "(!cn=WinRMRemoteWMIUsers__)(!cn=DnsAdmins)(!cn=DnsUpdateProxy)",
"FieldDesription": "A query string to filter the group result. You can use the ADSI Editor to generate valid queries"
},
{
"FieldName": "IsDominoServer",
"FieldTyp": "B",
"FieldValue": false,
"FieldDesription": "If false you must specify Username and Password for the LDAP server"
}
]
| Feldname | Typ | Beschreibung |
|---|---|---|
| Server | String | Name oder IP-Adresse des LDAP-/AD-Servers. |
| GroupPath | String | Vollqualifizierter LDAP-Pfad, wo Gruppen gesucht werden sollen. |
| UserPath | String | Vollqualifizierter LDAP-Pfad, wo Benutzer gesucht werden sollen. |
| UseNTLMAuth | Boolean | Gibt an, ob NTLM Authentifizierung verwendet wird. Wenn false, muss ein Benuztzername und Passwort für den LDAP-Server angegeben werden. |
| AuthenticationConfigurationId | Numeric | Id des Authentifizierungsmoduls in docuvita für AD-Benutzer. |
| Username | String | Benutzername für den LDAP-Server. |
| Password | String | Benutzerpasswort für den LDAP-Server. |
| UserQueryString | Eine Abfrage als String, die verwendet wird, um Benutzerergebnisse zu filtern. | |
| GroupQueryString | Eine Abfrage als String, die verwendet wird, um Gruppeergebnisse zu filtern. | |
| IsDominoServer | Boolean | Wenn true, dann handelt es sich um einen Domino-Server und nicht um einen ActiveDirectory-Server. (Beta-Status) |
¶ ADFieldMappingsSettings
Klicken Sie hier, um die ADFieldMappingsSettings-Konfiguration zu sehen
"ADFieldMappingsSettings": [
{
"FieldName": "displayName",
"FieldTyp": "S",
"FieldValue": "OBJ_DESCRIPTION",
"FieldDesription": "Display name of the Object"
},
{
"FieldName": "givenName",
"FieldTyp": "S",
"FieldValue": "VORNAME",
"FieldDesription": "First name"
},
{
"FieldName": "sn",
"FieldTyp": "S",
"FieldValue": "NACHNAME",
"FieldDesription": "Surname"
},
{
"FieldName": "telephoneNumber",
"FieldTyp": "S",
"FieldValue": "TELEFON",
"FieldDesription": "Telephone number"
},
{
"FieldName": "proxyAddresses",
"FieldTyp": "S",
"FieldValue": "USER_MAILADDRESS",
"FieldDesription": "Email addresses"
},
{
"FieldName": "mail",
"FieldTyp": "S",
"FieldValue": "mail",
"FieldDesription": "The main email address"
}
]
| Feldname | Typ | Beschreibung |
|---|---|---|
| displayName | String | Anzeigename des Objektes |
| givenName | Numeric | Vorname |
| sn | String | Nachname |
| telephoneNumber | String | Telefonnummer |
| proxyAddresses | String | E-Mail-Adressen des Benutzers |
| String | Primäre E-Mail-Adresse des Benutzers |
¶ DocuvitaSettings
Klicken Sie hier, um die DocuvitaSettings zu sehen
"DocuvitaSettings": [
{
"FieldName": "DvServerAddress",
"FieldTyp": "S",
"FieldValue": "localhost",
"FieldDesription": "URI of the docuvita server"
},
{
"FieldName": "DvSystemId",
"FieldTyp": "N",
"FieldValue": 1,
"FieldDesription": "ID of the docuvita system"
},
{
"FieldName": "DvSystemAlias",
"FieldTyp": "S",
"FieldValue": "default",
"FieldDesription": "Alias of the docuvita system"
},
{
"FieldName": "DvApiUsername",
"FieldTyp": "S",
"FieldValue": "administrator",
"FieldDesription": "Username of the docuvita API-user"
},
{
"FieldName": "DvApiPassword",
"FieldTyp": "S",
"FieldValue": "docuvita1",
"FieldDesription": "Password of the docuvita API-user"
},
{
"FieldName": "DvUseSingleSignOn",
"FieldTyp": "B",
"FieldValue": false,
"FieldDesription": "Use the docuvita integrated windows login instead of username/password for API-user"
},
{
"FieldName": "UserNameMode",
"FieldTyp": "N",
"FieldValue": 1,
"FieldDesription": "Username mode in docuvita: 0 = ActiveDirectory Name (z.B. mydomain\\user1) 1 = userPrincipalName - z.B. user@mydomain.local (default)"
},
{
"FieldName": "UserParentObjectId",
"FieldTyp": "N",
"FieldValue": 4,
"FieldDesription": "ID of the parent object for new users"
},
{
"FieldName": "SecurityGroupsParentObjectId",
"FieldTyp": "N",
"FieldValue": 0,
"FieldDesription": "ID of the parent object for new security groups"
},
{
"FieldName": "UserObjectType",
"FieldTyp": "N",
"FieldValue": 1,
"FieldDesription": "Object type ID for user in docuvita - usually 1"
},
{
"FieldName": "GroupObjectType",
"FieldTyp": "N",
"FieldValue": 2,
"FieldDesription": "Object type ID for groups in docuvita - usually 2"
},
{
"FieldName": "DistributionGroupsParentObjectId",
"FieldTyp": "N",
"FieldValue": 0,
"FieldDesription": "ID of the parent object for new distribution groups"
},
{
"FieldName": "NewUserGeneratePassword",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "If set docuvita will generate a random password for new users.else the system's standard password will be used."
},
{
"FieldName": "NewUserPasswordStrength",
"FieldTyp": "N",
"FieldValue": 16,
"FieldDesription": "Length of generated passwords for new users"
}
]
| Feldname | Typ | Beschreibung |
|---|---|---|
| DvServerAddress | String | URL des docuvita-Servers |
| DvSystemId | Numeric | Id des docuvita Systems (Default: 1) |
| DvSystemAlias | String | Alias des docuvita Systems |
| DvApiUsername | String | Benutzername des docuvita API-Benutzers |
| DvApiPassword | String | Passwort des docuvita API-Benutzers (mit fd.Password.Encrypt verschlüsselt) |
| DvUseSingleSignOn | Boolean | Wenn true, wird die Windows-Anmeldung verwendet. Der Dienstebenutzer wird für die Anmeldung bei docuvita verwendet. |
| UserNameMode | Numeric | Wie soll der Benutzername in docuvita gebildet werden:
|
| UserParentObjectId | Numeric | Objekt-Id des übergeordneten Objekts, in dem neue Benutzer angelegt werden. |
| SecurityGroupsParentObjectId | Numeric | Objekt-Id des übergeordneten Objekts, in dem neue Benutzergruppen angelegt werden. |
| UserObjectType | Numeric | Objekttyp-Id für Benutzer in docuvita (Default: 1) |
| GroupObjectType | Numeric | Objekttyp-Id für Benutzergruppen in docuvita (Default: 2) |
| DistributionGroupsParentObjectId | Numeric | Objekttyp-Id für Distributiongruppen in docuvita |
| NewUserGeneratePassword | Boolean | Wenn true, wird ein zufälliges Passwort für neu erstellte Benutzer automatisch generiert. |
| NewUserPasswordStrength | Numeric | Die Länge des automatisch generierten Passworts für neue Benutzer. |
Verwendung von Single Sign On
Bei der Verwendung von SSO muss in docuvita ein entsprechender Anmeldeprovider hinterlegt sein.
¶ SyncSettings
Klicken Sie hier, um die SyncSettings-Konfiguration zu sehen
"SyncSettings": [
{
"FieldName": "MoveUsers",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "If true existing docuvita users will be moved under the Object with ID=UserParentObjectId"
},
{
"FieldName": "DeleteUserLinks",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "If true existing userlinks in groups (found with GroupQueryString) will be deleted"
},
{
"FieldName": "DeleteUnusedUserLinksOnly",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "If true existing userlinks in groups (found with GroupQueryString) will be deleted if no user no longer groupmember"
},
{
"FieldName": "MoveGroups",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "If true existing docuvita groups will be moved under the Object with ID=GroupParentObjectId"
},
{
"FieldName": "SyncUsers",
"FieldTyp": "B",
"FieldValue": true,
"FieldDesription": "determines wether to synchronise AD-user into docuvita or not"
},
{
"FieldName": "SyncSecurityGroups",
"FieldTyp": "B",
"FieldValue": false,
"FieldDesription": "Synchronises security groups from AD to docuvita. Note: Secutrity groups can also be distribution groups"
},
{
"FieldName": "SyncDistributionGroups",
"FieldTyp": "B",
"FieldValue": false,
"FieldDesription": "Sync distribution groups from AD to docuvita. Distribution groups in AD are groups which are not security enabled. If you use ADSync in non Exchange environments you can use these groups to manage your mail distribution groups."
}
]
| Feldname | Typ | Beschreibung |
|---|---|---|
| MoveUsers | Boolean | Wenn true, werden existierende docuvita Benutzer unterhalb des Objektes mit ID=UserParentObjectId verschoben. |
| DeleteUserLinks | Boolean | Wenn true, werden existierende Benutzerverknüpfungen in Gruppen gelöscht |
| DeleteUnusedUserLinksOnly | Boolean | Wenn true, werden existierende Benutzerverknüpfungen in Gruppen gelöscht |
| MoveGroups | Boolean | Wenn true, werden existierende docuvita Gruppen unterhalb des Objektes mit ID=GroupParentObjectId verschoben. |
| SyncUsers | Boolean | Wenn true, werden die Benutzer aus dem Active Directory synchronisiert. |
| SyncSecurityGroups | Boolean | Wenn true, werden die Sicherheitsgruppen des Active Directoriesynchronisiert. |
| SyncDistributionGroups | Boolean | Wenn true, werden Distributionsgruppen synchronisiert. Distributiongruppen sind in AD Gruppen ohne aktivierte Sicherheit. Wenn ADSync in Nicht-Exchange-Umgebungen eingesetzt wird, können dies Gruppen benutzt werden, um Emailverteiler zu verwalten. |
¶ Changelog und Download
Version 22.9 oder höher
Um die Version 22.9. oder höher zu verwenden wird mindestens die docuvita Version 22.1 benötigt.
| Version | Anmerkungen |
|---|---|
| 24.9.11 | Umstellung des Dienstnamens, aller Konfigurationsdateinamen und der Protokollnamen auf das Präfix fd. |
| 24.4.9 | Downgrade auf log4net 2.0.12 wegen Abhängigkeiten zu internen dlls |
| 24.4.4 | Update WixToolset auf Version 4.0.5 |
| 24.2.0 | Update WixToolset auf Version 4.0.3 |
| 23.5.4 | Update docuvita.contract auf Version 23.1 |