Overview
Perform operations on users, groups, and computers in Microsoft on-premise Active directory.
This app communicates with the on-premise active directory using the orchestration server. Active Directory PowerShell commandlets are used by this integration to perform actions on the Active Directory.
Recommended Powershell Version: 5.1
Disclaimer
The recommended PowerShell version is 5.1, any other versions apart from this may result in unexpected responses of app actions.
Description
Orchestration apps let you automate repeatable tasks and actions that span across a diverse set of systems and applications using workflows. The list of actions supported for this app include:
User Management
1. Create User
2. Delete User
3. Get User
4. Add User To Group
5. Remove User From Group
6. Disable User
7. Reset Password
8. Enable User
9. Is User Account Locked
10. Is User Enabled
11. Unlock Account
12. Update Users Home Location
13. Update User
14. Add User to Multiple Groups
15. Get User with UPN
16. Get User with Email
17. Move User to Another Organizational Unit
18. Remove User to Multiple Groups
Group Management
1. Create Group
2. Delete Group
3. Get Group
4. Is User In Group
Computer Management
1. Delete Computer
2. Disable Computer
3. Enable Computer
4. Is Computer Enabled
5. Get Computer OU
Object Management
1. Move an object to a location specified by GUID
Working Principle
The app communicates with the on-premise active directory with the help of the Orchestration server, which resides in the same private network as the Active Directory server and acts as an agent.
The Orchestration server establishes an outbound secure connection over port 443, from inside the private network and looks for any incoming app requests.
Once it receives the app request over the outbound connection, Orchestration server will then communicate with the on-premise Active Directory residing in the same private network using WinRM - Windows Remote Management.
Prerequisites
Orchestration Server Installation
Orchestration server should be installed using the installer, on a windows server. This installer can be found in your Freshservice tenant in the “Admin” module.
Admin >
> Orchestration Centre > Orchestration Server > “Download Windows Installer”.
To know more about the orchestration server installation please refer to the Orchestration Server solution article.
It is recommended to install the Orchestration server on a separate windows server with access to the Active directory server(domain controller) over the WinRM listener port.
WinRM quickconfig Command
You’ll need to configure the WinRM listener on the Active Directory server (domain controller), this will ensure that the Orchestration server is able to communicate with the Active Directory server over WinRM.
Configuring WinRM listener over HTTP
1. Open up a powershell terminal on the Active Directory server (domain controller).
2. Run the following command in the powershell terminal:
winrm quickconfig
Note: The above command will configure the WinRM listener on port 5985.
Configuring WinRM listener over HTTPS
winrm quickconfig -transport:https
Note: The above command will configure the WinRM listener on port 5986.
For detailed information on configuring the WinRM listener using SSL, please refer to the official Microsoft documentation.
Once you execute the winrm quickconfig command based on your connection type (SSL or otherwise), you can verify the WinRM listener port with the following command -
winrm enumerate winrm/config/listener
For WinRM listener over HTTPS you’ll get a response in the following manner, unless port is specified explicitly -
Listener
Address = *
Transport = HTTPS
Port = 5986
Hostname = heimdalls.internal.com
Enabled = true
URLPrefix = wsman
CertificateThumbprint = <your-cert-thumbprint>
ListeningOn = 10.0.3.15, 127.0.0.1, 169.254.195.74, ::1, fe80::5efe:10.0.3.15%4, fe80::5efe:169.254.195.74%7, fe80::153e:398e:1707:f6c6%3, fe80::cd13:eaaf:6931:c34a%2
For WinRM listener over HTTP you’ll get a response in the following manner, unless port is specified explicitly -
Listener
Address = *
Transport = HTTP
Port = 5985
Hostname
Enabled = true
URLPrefix = wsman
CertificateThumbprint
ListeningOn = 10.0.3.15, 127.0.0.1, 169.254.195.74, ::1, fe80::5efe:10.0.3.15%4, fe80::5efe:169.254.195.74%7, fe80::153e:398e:1707:f6c6%3, fe80::cd13:eaaf:6931:c34a%2
What does the “winrm quickconfig” Command Do?
The "winrm quickconfig" command performs these operations:
Starts the WinRM service and sets the service startup type to auto-start.
Configures a listener for the ports that send and receive WS-Management protocol messages using either HTTP or HTTPS on any IP address.
Defines ICF(Internet Connection Firewall) exceptions for the WinRM service, and opens the ports for HTTP and HTTPS.
Note
The winrm quickconfig command creates a firewall exception only for the current user profile. If the firewall profile is changed for any reason, you should run winrm quickconfig to enable the firewall exception for the new profile; otherwise, the exception might not be enabled. For more information please refer to the documentation here.
Installation Parameters
The app requires the following parameters during installation, these parameters will be used to authenticate the calls from the app to the on-premise Active Directory server.
Active Directory Server IP:
The IP address of the Active Directory domain controller. It can be a private IP or a public IP depending upon the server configurations.
The private IP address can be retrieved using a powershell terminal with the following command:
From the command result, copy the IPv4 address.
Active Directory Server Username:
The username used for logging in into the Active Directory domain controller.
IMPORTANT
The login credentials used in the app configuration should be either of an Administrator or an user who has been added to the built-in group “Remote Management Users”.
Active Directory Server Password:
The password used for authenticating the user on the Active Directory domain controller.
WinRM Port:
The default WinRM port is 5985 for communication over HTTP, and 5986 for communication over HTTPS, unless WinRM port is explicitly configured.
5. Use SSL Connection?
- Specify whether the connection to Active Directory server is over HTTPS (SSL certificate configured) or over HTTP (no SSL certificate configured).
- If set to 'true' communication to Active Directory server will be over HTTPS. If set to 'false' communication to Active Directory server will be over HTTP.
6. Disable SSL Certificate Verification? (Optional)
- Specifies whether SSL certificate verification should take place or not.
- If set to ‘true’ SSL certificate verification will not take place.
- If set to ‘false’ SSL certificate verification will take place.
Default value is ‘true’, by default SSL certificate verification will not take place.
Note: Currently self signed certificate and certificate acquired from private ca is not supported, in case of self signed certificate, verification(Disable SSL Certificate Verification) should be disabled.
Networking Requirements
Please ensure that the following network communication is established before executing the app actions -
Communication on default WinRM port (or a custom port based on your configurations), from the Orchestration server to the Microsoft AD server should be enabled. You can use telnet utility to verify the open WinRM port.
Verify Connection Using “Test App Action”
You can also use the “Test App Action” functionality inside the Workflow Automator’s App Node to verify the connection between the Orchestration server and On-Premise Active Directory.
Disclaimer:
Using the “Test App Action” will actually execute the action in your Active Directory.
Using Custom Attributes
Currently supported syntax in MS AD - Orch application
Given examples can be used with MS AD Create User and Update User action to set custom attributes. You can set/update multiple attributes in a single action.
Usecases
Now that you've successfully installed the Microsoft On-Premise Active Directory orchestration app, please have a look at the sample use case below to show how the app can be used efficiently.
Check out the FAQ article for troubleshooting. More info here
