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


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


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

  1. 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.


  1. 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:

  1. Starts the WinRM service and sets the service startup type to auto-start.

  2. Configures a listener for the ports that send and receive WS-Management protocol messages using either HTTP or HTTPS on any IP address.

  3. 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.


  1.  Active Directory Server IP:

The IP address of the Active Directory server. 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: 

ipconfig /all

 

From the command result, copy the IPv4 address.



  1.  Active Directory Server Username: 

The username used for logging in into the Active Directory server.

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”.


  1. Active Directory Server Password:

The password used for authenticating the user on the Active Directory server.


  1. 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.



Networking Requirements

Please ensure that the following network communication is established before executing the app actions -


  1. 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.

     


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.