Your boss walks in and says “Jim just quit so he can go drive a train, so YOU are the new specialist for the software running on his servers. Get to it!” This guide is for System Administrators that have never worked with Ithicos Solutions software. It is intended to quickly get you up-to-speed and supporting our software.
Who is Ithicos Solutions? We are a small software and consulting company based in Honolulu, Hawaii and Colorado Springs, Colorado. The company was founded in 2006 by Jim McBee (Exchange and Active Directory trainer, writer, and consultant) and Matt Supatana (C#, ASP.NET, and Web application developer.) We are supported by a experienced team of part-time and full-time developers and system administrators.
Our mission? To design, develop, and sell simple, affordable, easy-to-use Web-browser based software that allows System Administrators to empower their end users and to better leverage the capabilities of Microsoft’s Active Directory.
Our software platform? All of our applications are ASP.NET-based Web-browser applications; they run on Windows 2012 R2 and later and require Internet Information Server, the .NET Framework, and ASP.NET components of Windows Server.
Our user interfaces? End users access our software interface through any compatible Web browser, such as Internet Explorer 11, Edge, Google Chrome, or Firefox.
Our database? We directly reference data found in the Microsoft Active Directory; we have no intermediate database. Queries are performed against the Active Directory and updates are performed directly against the Active Directory. We use the LDAPv3 protocol and the Microsoft Active Directory Services Interface (ADSI) to interact with Active Directory.
Customizing? More on this in a moment, but all fields (user attributes) on the interface, all field labels, and all text are customizable by the System Administrator. Don’t want to see the Fax Number field on the user interface? Hide it. Want to call the Office Phone field “Desk Phone” instead? Change the label.
Licensing? Most of our software is licensed on a per-Active Directory domain basis. A single domain license is required for each domain in which you will have users that use the software. This is a very simple, reasonable, and affordable mechanism of licensing. The software license is perpetual, meaning you can use it forever (or for as long as it will continue to work as server operating systems and web browsers are updated.) Software maintenance and support is available which allows you to get relevant ongoing technical support and software upgrades at no additional charge other than the cost of the software maintenance.
Active Directory Permissions? By design, we use a service / proxy user account that you create and delegate permissions. All queries and updates are performed using this user account. You can make the account a member of the Domain Admins group, the domain’s Administrators group, the domain’s Account Operators group, or give it some custom set of permissions. As long as the account has been delegated the necessary permissions in Active Directory, do what works best for you.
We sell five separate software programs; they are all similarly installed and managed. Our customers only need to purchase the software package that has the features they need, though many customers own more than one software package.
Directory Update – Our original software package, Directory Update provides end users with a self-service Web interface through which they can update their *own* Active Directory information (office phone, city, street address, title, department, manager, etc…) The administrator controls which fields (attributes) are visible and the validation rules that can be used for each field. Changes can be logged to CSV audit logs and email notifications can be sent when a user makes a change.
Directory Manager Standard – This web interface allows an authorized user (by default, a member of the “Directory Update Managers” group) to search for other users and to update their information. Usually authorized users are people in Human Resources or a department secretary. All visible fields and field validation rules are controlled by the System Administrator.
Directory Manager Advanced – This web interface includes all of the features of Directory Manager Standard plus the ability to create user accounts based on templates of differing user types, add users to groups, remove users from groups, disable user accounts, or delete user accounts. Users can be “soft” deleted in case the System Administrator is concerned user accounts could be deleted by accident.
Directory Password – This product is an add-on or enhancement product for Directory Update. Users answer a series of security questions or set up a smart phone-based authentication app. If a user locks out their user account or they forget their password, they can visit a web page which will allow them to authenticate and re-enable their account.
Directory Search – This web application allows the System Administrator to turn your Active Directory in to a phone book. This custom search interface allows you to search for users or contacts based on name, department, email address, city, title, etc… and display the results on a Web page. The System Administrator controls which Active Directory fields are visible, such as email address, mailing address, department, photograph, etc…
During the installation of our software, we require that you provide a username and password and password of an account to be used as a service/proxy account. The account is not really a service account since there is no service running; the account is used by our software to query and update the Active Directory. The software will not function if the account is not working correctly.
For an existing installation of any of our software, you can find the service account by running the application’s Configuration Wizard or by opening up RegEdit.exe and navigating to HKLM/Software/Ithicos. Under that key, look for a key such as DirectoryUpate. Under that key, you will find a key named for your Active Directory domain. Look for a value under that key called ADUser.
The service/proxy account password is also stored in this key, but it is encrypted and cannot be viewed.
The service/proxy account is a common source of problems. Always check the service account to make sure that the password has not changed, that the account is enabled, and that it has adequate permissions. Requirements for the service/proxy account include: • Service/proxy account must not be set to expire • Service/proxy account password must not be set to expire • Service/proxy account must be delegated necessary permissions to Active Directory objects such as by adding it to the domain’s Administrator or Account Operators group.
All of our customer-editable configuration files are XML files. These are essentially simple text files, but each configuration item has an 'open tag' and a 'close tag'. XML files are very similar to HTML files except that XML is *much* pickier. We strongly recommend that you download a copy of Notepad++ and use it to edit your XML files (as well as other types of text files. And that prior to editing any configuration files, you make a backup copy of the files.
Our user interfaces are flexible and customizable. Almost all customization work is done in XML-based text files. Let’s take as an example, the Directory Update application. By default, the Directory Update software is installed in to this folder:
Under the DirectoryUpdate folder is the .\Settings folder. In this folder, you will find our configuration XML files. Not all applications will have all files.
DirectorySettings.XML – This file controls which fields are visible on the interface, which fields are editable, required, have a default value, the field type (text or dropdown list), the values of dropdown lists, the field labels, the LDAP attribute name, and our internal field ID. Each field on the interface will have a line in the DirectorySettings.XML file. Here is an example of the Office field.
<field id="office" label="Office" attribute="physicalDeliveryOfficename" visible="true" editable="true" type="dropdown" maxLength="128"> <value>Galactica CIC</value> <value>Galactica Hanger Deck</value> <value>Pegasus CIC</value> <value>Pegasus Hanger Deck</value> <value>Colonial One - Presidents Office</value> </field>
The above field tag includes not only the field information but also a list of potential dropdown list values. Let’s look at these options for the office field.
id is our internal identification for this field. This should not be changed.
label the field label the end user sees on the screen
attribute is the LDAP attribute name in the Active Directory. LDAP attribute names are not always particularly friendly or intuitive.
visible indicates if the field is visible on the user interface or not. Values for this field are “true” or “false
editable defines whether the field is read only or can be edited. Values for this field are “true” or “false”
type defines type field type. Permitted values are “text”, “dropdown”, or “combo”. A combo box uses a dropdown list but allows users to type in their own values.
maxLength is the maximum number of characters that the field can contain, as defined by the Active Directory schema.
required indicates if the field must have a value. If the field is empty, the user will not be allowed to save the other data on the screen. Values for this field are “true” or “false”
defaultValue allows you to define a default value for the field. If the field has any data in it at all, this value will not be used.
example allows you to specify example text
multiline indicates whether the field on the interface should have multiple lines. Values for this field are “true” or “false”
horizontalForm defines whether the field label is above the field value or to the left of it. Values for this field are “true” or “false”
validationFormat defines a validation format. The validation format must be one of the validation formats found in the DirectorySettings.XML file.
AppSettings.XML – This file allows you to define settings such as the logo file, help text, email notifications, the tabs that are enabled on the user interface, auditing to a text file, and other settings.
PasswordSettings.XML – This file defines the password strength that you require for your organization, allows you to define a list of passwords that cannot be used, and, for customers that use Directory Password, defines a list of security questions and options for using an external authentication service.
SubSettings.XML – The file allows you to define (for Directory Update and Directory Manager) a relationship between two fields, such as Country and Office. If you select a specific country, such as Japan, in the Office drop-down list you will see a list of offices that you have defined to be in Japan.
AddressSettings.XML – This file allows you to define a single field that, when selected, automatically fills in the values for multiple attributes. This is most commonly used for the Office field; a user selects an Office name and the street address, city, state, postal code, and country are automatically populated.
Web.Config – The web.config file is the IIS web site / web application configuration file. The only value you would need to change in this file is the authentication mode (either Forms or Windows.)
For most of our software, we release between three and five “point” releases each year, such as from v3.1.2 to v3.1.3. We target a new “dot” release once every 10 to 15 months (from v3.1 to v3.2). We categorize major releases, such as from v4 to v5, when we have a significant user interface change, the configuration file format changes significantly, or we move to a new major underlying version of the .NET Framework (such as moving from .NET Framework 2 to 4.)
Point releases are usually fixing minor issues and are not considered critical; the exception to this is if we find an issue that we feel is important that all customers address.
Dot releases usually include new features as well as all previous updates. Almost always, “dot” releases require new license keys.
Ithicos Solutions offers ongoing software maintenance and support at a very reasonable price (usually 18% to 25% depending on the product) of the purchase price of the software. As long as your software support and maintenance is current, this entitles your company to:
Email is the *only* mechanism we use to notify customers of new releases, expired software maintenance, or important patches being available. If you are a new to supporting Ithicos Solutions applications, please email us at firstname.lastname@example.org and make sure we add your email address to our contact database. Make sure that you include the DNS domain name of your Active Directory domain so that we can properly match you up with an existing customer record.
Better yet, create a shared mailbox or a distribution list with a common alias that vendors like Ithicos Solutions can use; this would be an alias *not* associated with an individual. Examples might include: IT.Help.Desk@yourcompany.com, IT.Software.Licensing@yourcompany.com, Web.Application.Team@yourcompany.com.
As system administrator, the most important elements of our software that you should maintain are:
Most Ithicos Solutions customers host our application on Windows Servers that are virtualized using VMWare, HyperV, or some other server virtualization technology. If this is the case, we recommend keeping snapshots of these server images that would allow you to restore a server image that is no more than 24 hours old in the event of a full server loss.
As much as we would like to be able to provide direct installation support, upgrade support, writing scripts, and customization of the user interface, our business and pricing model does not allow for significant amounts of time to do such things. Our support model is intended to help you resolve issues or get past problems that you encounter as you are installing or managing the software.
Our expectation is that you read all relevant documentation and that you will attempt to install, upgrade, or customize the software yourself. If you run in to problems, please contact us.
Before you contact us, please do the following:
Our first line of technical support is email. Our technical support email address is email@example.com. This is an email distribution list that sends email to everyone in the company though you may only receive an answer from one or two of us. If you receive an email and need to respond to it, please “Reply All” so that the email distribution group is included.In your initial email, please include: