Active Directory Synchronization command line tool
The Active Directory Synchronization command line tool is utility that can be used to synchronize the users within an Active Directory with the list of users registered within the AllUsers table within a Smartsite database.
It basically works the same as the Smartsite Active Directory membership provider, well at least as far as querying the Active Directory for users and retrieving the Active Directory groups a user is member of is concerned.
Most of the appSettings (see below), also correspond with the settings available on this provider.
Use case
Typical use case for this command line tool is creating a Windows scheduled task which runs this tool once a day.
But you can also run it manually from the command prompt on a regular basis, or as a test.
Settings
Using the config file, several appSettings are available, some of them are required.
| Name | Required | Explanation |
|---|---|---|
| ConnectionUsername | yes | The username for connecting to the Active Directory. |
| ConnectionPassword | yes | The password for connecting to the Active Directory. |
| SearchBase | no | Limits the scope when querying for Active Directory users. |
| GroupSearchBase | no | Limits the scope when querying group membership for groups. |
| ObtainPrimaryGroup | no | Boolean, indicating whether or not the primary group should be obtained. Defaults to true. |
| ObtainParentGroupsForPrimaryGroup | no | Boolean, indicating whether or not the parent groups of the primary group should be obtained (recursively). Defaults to true. |
| MaxParentGroupRecursionDepth | no | Numeric setting to limit the recursion on obtaining parent groups on groups. When set to 0 (the default), the recursion process will not be limited. Usually, it is not needed to use this setting and specifying a GroupSearchBase is a better choice. |
| SmartsiteAccessGroup | yes |
Name of an Active Directory group, which will be used to determine whether or not an Active Directory user should be granted access to Smartsite. When an Active Directory user is a member of this group (direct or indirect), the user will be granted Visitor access (the user account will be created with the Visitor role). |
| ManagerAccessGroup | yes |
Name of an Active Directory group, which will be used to determine whether or not an Active Directory user should be granted access to the Manager. When an Active Directory user is a member of this group (direct or indirect), the user will be granted User access (the user account will be created with the User role). |
| FixedUserGroups | no |
Optional setting which can be used to specify a comma separated list of Smartsite Usergroups (by code). When (re)setting the group membership for an user account, each user will become a member of these specified groups. |
| UserPrincipalNameAsLoginName | no | Boolean, indicating whether or not the UserPrincipalName should be used as LoginName (instead of the SamAccountName). Defaults to false. |
| UpdatePrimaryGroup | no | Boolean, indicating whether or not the Primary Group for a user account must be updated when updating an existing Smartsite user account. Defaults to false. |
| UpdateGroupMembership | no | Boolean, indicating whether or not the group membership (only externally managed groups) should be reset when updating an existing Smartsite user account. Defaults to true. |
| DisableNotFoundExternalUsers | no | Boolean, indicating whether or not user accounts which do have an ExternalId set and which are not found within the Active Directory should be set disabled. Defaults to true. |
| LogLevelToConsole | no | Debug setting (numeric), to specify which loglevel should be written to the console window (as well). Defaults to 1, which means the most important log messages will be written to the console window as well. |
| TestRun | no | Debug setting (boolean), which can be used to execute a Test Run. No actual changes will be made, however, you can review the log file and/or the messages written to the console window to get a detailed overview of the accounts that would have been created, updated or disabled when running this tool without this setting enabled. |
Connection strings
The application config file should also contain a connectionStrings element, in which the database connection string and the Active Directory connection string must be specified. They are identified by DbConnection and ActiveDirectoryConnection respectively (see example below).
The synchronization process
This command line tool queries the Active Directory for users (which can be limited to a specific OU using the SearchBase appSetting) and synchronizes these users with the user accounts as registered within the AllUsers table of the specified Smartsite database.
The Active Directory's objectSid attribute is used to match Active Directory users with user accounts within the AllUsers table.
When there's a match (AllUsers' ExternalID column), the user account within the AllUsers table will be updated.
When there's no matching record with ExternalID equals objectSid, then an attempt is made to match the loginname with the SamAccountName or UserPrincipalName. If a match is found, this user account will be updated and the ExternalID column will be set to the AD account's objectSid.
Otherwise, a new user account will be created.
Active Directory groups vs. Usergroups
When an user is retrieved from the Active Directory, the Active Directory groups this user is a member of will also be retrieved.
This is implemented as a recursive process. The groups a user is a direct member of, will be recursed to find the parent groups which these groups are a member of, etcetera.
This way, within Active Directory, users don't have to be a direct member of the Smartsite Access groups, or any other Usergroup within Smartsite that has been marked as externally managed.
The recursion process can be limited by specifying the GroupSearchBase appSetting. Active Directory groups that are not part of this OU, will not be recursed to retrieve its parent groups.
SmartsiteAccessGroup and ManagerAccessGroup
For each user, the group membership on the Active Directory domain is taken into account. An Active Directory user must be a member of one of the specified access groups.
When the user is a member of the specified SmartsiteAccessGroup and there's no corresponding user account within the AllUsers table, an user account with the Visitor "role" will be created.
When the user is (also) a member of the specified ManagerAccessGroup and there's no corresponding user account within the AllUsers table, an user account with the User"role" will be created.
If there's a corresponding user account already, the type of user role will be adjusted accordingly, dependent on the access groups membership.
When an Active Directory user isn't a member of either of these groups, no user account will be created. If there's already a corresponding user account within the database for this AD user, it will be disabled.
Externally managed groups
When creating or updating an user account within the AllUsers table, the group membership of the user account will also be (re)set.
This concerns only usergroups which have been marked as externally managed.
So, within Smartsite, the user will be added as a member of every group which he/she is a member of within Active Directory and for which a corresponding Usergroup exists within Smartsite, matched by the AD group's common name (cn) attribute, and that has been marked as externally managed.
Any group membership for other groups for existing users will be kept intact.
You can also set the optional FixedUserGroups appSetting, and specify one or more (comma separated) codes of Usergroups. Every user account that is created or updated will be set as a member of these groups.
Configuration
A typical ActiveDirectorySync.exe.config file looks like this:
| XML |
Copy Code
|
|---|---|
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<configSections>
<section name="Smartsite.ConfigurationSource"
type="Smartsite.Diagnostics.LoggingBase.Common.Configuration.ConfigurationSourceSection, Smartsite.Diagnostics.Logging, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5fdb12a67e027fb6" />
</configSections>
<appSettings>
<!-- login credentials for AD -->
<add key="ConnectionUsername" value="username@domain.nl" />
<add key="ConnectionPassword" value="*****" />
<!-- settings to limit the scope of the AD search -->
<add key="SearchBase" value="OU=UsersOU,DC=your,DC=domain" />
<add key="GroupSearchBase" value="OU=GroupsOU,DC=your,DC=domain" />
<add key="ObtainPrimaryGroup" value="true" />
<add key="ObtainParentGroupsForPrimaryGroup" value="true" />
<add key="MaxParentGroupRecursionDepth" value="0" /> <!-- 0 means no limit on recursion depth -->
<!-- Access groups -->
<add key="SmartsiteAccessGroup" value="smartsiteaccesslocal" />
<add key="ManagerAccessGroup" value="manageraccesslocal" />
<add key="FixedUserGroups" value="CMS_USERS,CONTENTEDITORS" />
<!-- no need to specify the GUESTS group here, it will be added automatically -->
<add key="UserPrincipalNameAsLoginName" value="false" />
<!-- Update settings for existing Smartsite accounts -->
<add key="UpdatePrimaryGroup" value="false" />
<add key="UpdateGroupMembership" value="true" />
<add key="DisableNotFoundExternalUsers" value="true" />
<!-- debug settings -->
<add key="LogLevelToConsole" value="3" />
<add key="TestRun" value="false" />
</appSettings>
<connectionStrings>
<add name="ActiveDirectoryConnection" connectionString="LDAP://your.domain"/>
<add name="DbConnection" connectionString="Data Source=machinename;Persist Security Info=True;initial catalog=catalogname;user id=username;password=password"/>
</connectionStrings>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.5.2" />
</startup>
<Smartsite.ConfigurationSource selectedSource="File Configuration Source">
<sources>
<add name="File Configuration Source"
type="Smartsite.Diagnostics.LoggingBase.Common.Configuration.FileConfigurationSource, Smartsite.Diagnostics.Logging, Version=1.0.0.0, Culture=neutral, PublicKeyToken=5fdb12a67e027fb6"
filePath="Smartsite.Logging.Config" />
</sources>
</Smartsite.ConfigurationSource>
</configuration>
|
|
Logging
The Active Directory Synchronization command line tool uses the standard Smarsite Diagnostics logging mechanism, as configured using the Smartsite.ConfigurationSource element.
The Smartsite.logging.config included is a simplified version, which only contains a definition of the XmlFile Trace Listener.
However, when needed, you can use any of the available listeners. Just add its definition to the listeners element.
This command line tool uses the log category System only.