Cimitra Active Directory Integration
Instructions for Cimitra’s Active Directory Integration Module Installation and Post Installation Configuration
(No license is needed, these scripts are a free add-on to Cimitra)
The Cimitra Active Directory Integration Module installs 30 Pre-Made PowerShell Scripts and connects them into an Admin-level account that you specify.
The Cimitra Apps can do the following.
- List Active Directory Users in a Certain Context
- Get Info on a User
- Change a User’s Password
- Check a User’s Password Set Date and Time
- Unlock a User’s Account
- List Expired Users
- Set The Expired Date on a User Account
- Remove The Expire Date on a User Account
- List All Users Who Have an Expire Date
- Disable a User Account
- Enable a User Account
- List All Disabled User Accounts
- Set a User’s Office Phone Number
- Set a User’s Mobile Phone Number
- Set a User’s Department
- Set a User’s Title
- Set a User’s Description
- List All Users in The Active Directory Tree
- List All Users Who Have Not Logged Into Their Account
- Create a User
- List Users Created in The Last “X” Days
- Change a User’s First Name
- Change a User’s Last Name
- Remove a User
- List Computers in a Certain Context
- Create a Computer
- Rename a Computer
- Remove a Computer
- Search For a Computer
- List Computer Objects in an Entire Active Directory Tree
Prerequisites
First make sure to read the Cimitra Server Install documentation. Install a Cimitra Server first.
Deploy the Cimitra Agent on a Windows box that has access to your Active Directory system. It might be an Active Directory Domain Controller, or any other box that has access to your Active Directory system from a PowerShell terminal.
The Cimitra Active Directory Integration scripts depend upon Microsoft’s Remote Server Administration Tools (RSAT) for Windows operating systems. These tools are automatically installed on an Active Directory Domain Controller. The Cimitra Active Directory Integration Install script will detect if the RSAT tools are installed. If RSAT tools are not installed, the Cimitra Active Directory Integration Install script will attempt to install the RSAT tools. If that fails, you will need to install the RSAT tools yourself.
Install
From the box where you have installed the Cimitra Agent on a Windows open up a PowerShell console as Administrator.
Install the Cimitra/Active Directory Integration module by typing in the following command:
iwr https://raw.githubusercontent.com/cimitrasoftware/win-api-ad/master/install.ps1 | iex
The command above downloads and runs a script that installs the Cimitra Active Directory Integration Module.
NOTE: If you get errors trying to run the command above, then you simply need to run Internet Explorer one time.
For more information see this article:
Solving the First-Launch Configuration Error with PowerShell’s Invoke-WebRequest Cmdlet
Configuration
The Install Script will attempt to run a Setup Script. However if ever you need to run the Setup Script again, here is how you do so.
The Cimitra Active Directory Integration Module Setup Script is located in the following directory by default:
c:\cimitra\scripts\ad
The script is setup.ps1
To run the script type the following
c:\cimitra\scripts\ad\setup.ps1
You will see a menu similar to the one shown below.
Make sure to run the [CONFIGURE] menus choices before running the [INSTALL] menu choice.
Cimitra Admin Account
To begin the Cimitra/Active Directory Integration, choose Configure Cimitra Integration Admin User. When you do so you will be prompted with information that will allow the Setup script to get access to an Admin-level account in the Cimitra System in which the Cimitra Active Directory Apps (PowerShell Scripts) will be installed.
Run all of the [CONFIGURE] menu options to make sure everything is configured correctly.
Install Integration
Choose [INSTALL] which will define each of the over 30 Cimitra Active Directory Integration Apps (PowerShell Scripts) in Cimitra.
After the Install runs, when you log into the Cimitra Account that you defined, you should see a folder called ACTIVE DIRECTORY as shown below. You should be immediately able to run any of the Cimitra Apps. If they do not work, then make sure that you have configured the Active Directory Users Context and the Active Directory Computers Context correctly.
C
Excluding Apps
Every time you Update the Cimitra Active Directory Integration, the Update routine wants to make sure that every Cimitra App (PowerShell Scripts really) is registered.
However, there may be Cimitra Apps that you do not want to delegate to others to use.
If this is the case, move a Cimitra App to the “EXCLUDE” folder or the “ADMIN” folder in order to tell the Cimitra Update utility that you do not want the App to be created again in the DELEGATE folder. If you just delete the App, the App will come back the next time you Update the Cimitra Active Directory Integration. So make sure to use the EXCLUDE folder as explained.
What is The ADMIN Folder For?
Cimitra Apps placed in the ADMIN folder are treated just like the EXCLUDE folder, they have the exact same function. However, perhaps you have a couple of people that you do want to have access to Cimitra Apps that you want generally excluded. You could put the App in the ADMIN folder, and then give the people you have identified as more privileged users, access to the ADMIN folder.
Updating
The best way to see the latest version of the Cimitra Active Directory Integration Module is to go the GitHub website for this module.
Once you have determined if you need to update, you can do so in one of 2 ways.
PowerShell Terminal – Update Method
1. Open up a PowerShell Terminal session as an Administrator
2. Go to the directory where the Cimitra Active Directory Integration scripts are installed. By default the directory is: c:\cimitra\scripts\ad
cd c:\cimitra\scripts\ad
3. Run the Setup Script: setup.ps1
.\setup.ps1
4. Choose the [UPDATE] Menu Option
Cimitra Web Console – Update Method
Login to Cimitra web Administration as the Admin-level user that the Cimitra Active Directory Integration was assigned/installed to. Go to:
ACTIVE DIRECTORY | ADMIN
Micro-Administration
Let’s say there is one Cimitra App, or a few Cimitra Apps you want to share with someone, but you don’t want to share all of the Apps in the DELEGATE folder structure.
For example, let’s say you want to share with a secretary 3 Cimitra Apps.
SET USER TITLE
SET USER OFFICE PHONE
SET USER DEPARTMENT
The steps for doing so are:
-
Create a new folder object in Cimitra Web Administration that you are going to share with the secretary. Put the folder somewhere outside of the existing Cimitra/Active Directory Integration folders, just so that they don’t get confused in some manner.
-
Go the App(s) that you want to share and edit the App, and choose the “Duplicate” option.
-
Change the name of the App as needed, and then move the App to the new folder you created in step 1.
-
Share the folder you created in step 1, with the secretary.
The animation below demonstrates how to accomplish the steps explained above.
Note that the Cimitra Apps are still referencing the same underlying PowerShell scripts, so when you update the Cimitra Active Directory Integration Module, the scripts are still updated. So in short, you do not lose any functionality by using the Micro-Administration method.
Localization
Most Active Directory Administrators are familiar with “English” based administration tools.
However, with Cimitra, you are trying to allow other users to participate in accomplishing routine tasks. If the other users are not familiar with English, you can change the names of the Cimitra Apps and all of the instructions within each Cimitra App.
Properly Changing Cimitra/Active Directory Integration Folder Names
NOTE: The folder “ACTIVE DIRECTORY” should not be renamed. But all other folders below the ACTIVE DIRECTORY folder can be renamed, using the method explained below.
Rename the folder in the Cimitra Web Client
Edit the settings.cfg file as explained below to mirror the name you can to the renamed folder(s)
The names of the 5 Cimitra/Active Directory Integration Folder Names are contained in the settings.cfg file which is located in the same location where the Cimitra PowerShell scripts are installed. The Cimitra PowerShell scripts are kept in the following directory by default:
c:\cimitra\scripts\ad
Edit the settings.cfg file and locate the following 5 lines which can be changed to the names that you would like:
ACTIVE_DIRECTORY_ADMIN_FOLDER_LABEL=ADMIN
ACTIVE_DIRECTORY_DELEGATED_FOLDER_LABEL=DELEGATE
ACTIVE_DIRECTORY_EXCLUDED_FOLDER_LABEL=EXCLUDE
ACTIVE_DIRECTORY_USER_MANAGEMENT_FOLDER_LABEL=USER MANAGEMENT
ACTIVE_DIRECTORY_COMPUTER_MANAGEMENT_FOLDER_LABEL=COMPUTER MANAGEMENT
Change the value on the right-hand side of the equals sign to reflect the names you changed the folders to in the Cimitra Web Client.
Customization
Cimitra Apps can be customized in a variety of ways. Here are a list of things you can do to a Cimitra App to customize it:
- Change the name of the App
- Change the allowed characters that can be passed to a script, warning do not allow characters such as ampersand (&), semicolon (;), quotes(” or ‘), pipe ( | ) and other characters that can compromise the fact that these scripts and commands are executed on a Windows box in a PowerShell session.
- Add an emoji character from the Internet that you can copy and paste into the App name or instructions.
FAQs
Q: Does the Cimitra Integration give me features that are not in Active Directory Users and Computers Administration?
A: Yes. For example, there are reports and actions in Cimitra that you can take, that are not readily available in Users and Computers Administration.
Q: How does Cimitra “Integrate” with Active Directory?
A; The Cimitra/Active Directory Integration Module is a collection of PowerShell scripts that use the Microsoft Remote Server Administration Tools (RSAT) APIs to read and change and get information in Active Directory.
Q: How do I get support for the Cimitra/Active Directory Integration Module?
A: The Cimitra/Active Directory Integration Module is free. However, most customers will want to purchase Cimitra. To get support fro Cimitra and the Cimitra/Active Directory Integration module, please contact a Cimitra Authorized Distributor/Reseller. You can contact Cimitra at [email protected] and Cimitra can refer you to a Distributor/Reseller.
Q: Can I tie other commands or scripts into Cimitra?
A: Yes, the options are limitless. There are several scripts at Cimitra’s website, but there are limitless scripts available online that you can share with Cimitra to further the notion of delegating routine IT tasks.