Page Comparison

Prerequisites:

If you don’t have PowerShell installed on your machine. Please refer to this documentation

Our Active Directory integration uses a script to pull a CSV containing all of the accounts within the Organizational Units that you will set. To automate this, we store the CSV onto an sFTP Server that either Zilla or you can host, and Zilla pulls the information from there. For more information on this process, please see this documentation. You have the option to do this manually, but the automated approach is recommended.

Prerequisites:

This setup requires the following

1. Ensure that powershell is up to date and installed on your server (odds are it is). For more info, please refer to this documentation

2. That you have Admin access to the microsoft servers containing your domain controller

3. If you’d like this process to be automated, we require a service account on AD with domain user access that can be used. We will also require an SSH Public/Private Key made in RSA Format. To do this, do the following:

   1. Run the following command:

      Code Block
      ssh-keygen -b 2048 -t rsa

   2. This will generate a public/private key in the filepath that you defined. If you didn’t it will be stored at /home/user_name/.ssh/id_rsa

   3. If you are using Zilla’s sFTP server, you will need to provide the public key to you Zilla Technical Contact.

   4. take note of this filepath for later configuration. You will also need the private key value as well.

4. You will need to add an on-prem AD Application inside of Zilla. To do this, login to Zilla as an admin, select Add Application, then search for On-Prem AD and add it as an app.

Configuring the script for use

1. Download the script

   View file
   name ADscript_version-R-12.ps1

2. Edit this file and update the following fields. NEED update to next section

3. Identify the distinguished name (DN) for the Domain, and decide if you will be pulling the entirety of the domain to the directory or certain Organization Units (OUs). This will be defined under the DNS section of config.yaml .

   If individual OUs the config yaml will need to have line for the DN of each OU, example:

   Code Block- OU=Sales,DC=zillasecurity,DC=com - OU=IT,

   Open the file in an editor like VS Studio, and define what Organizational Units Zilla Will Pull Accounts from. You will do this by editing the below variable:

   1. $DNs = @("DC=yourdomain,DC=com") - this variable is used to define what Organizational Units Zilla Will Pull Accounts from. For example, if my OU is zillasecurity.com, then this line would look like this: $DNs = @("DC=zillasecurity,DC=com

   2. Alternatively, include a single specifying the DN of the domain, example:

      Code Block
      - DC=zillasecurity,DC=com

       

4. On initial use, run with SftpEnabled = false this will simplify the first tests to avoid using an SFTP server to ensure the necessary data is collected from AD. A file, directory.csv , will be created in the current directory.

Complete the below steps if ready to connect script with SFTP, otherwise continue to “Steps to run the Script”

5. Navigate to the Zilla web UI to create the directory application

   1. From Applications, select Add Application, follow by selecting Custom Application.

      Image Removed

   2. Name the directory application, and complete any other desired values.

   3. Select the Custom Application you recently created.

   4. Finally, navigate to Applications, search for and select the Custom Application you created and set as a directory. The Application ID is required for the sftp configuration, this is found in the URL. Copy the value and replace <application-id> in the config.yaml file.

      Image Removed

       

6. (Optional for SFTP Only) If using the Zilla SFTP server an ssh key pair will need to be created, this must be in the RSA format and can be generated by performing the following.

   Code Block
   ssh-keygen -b 2048 -t rsa

   This will run you through a few prompts to generate a private and public key pair, the private key should be placed in a secure directory. The public key will need to be shared with Zilla support to configure SFTP for authentication.

7. Update config.yaml to specify the path of the ssh private key, SFTP username, and the SFTP server hostname.

Steps to run the Script

1. (Optional for SFTP Only) Open PowerShell with run as administration in Windows, or a terminal window on Mac and Linux which you have launched in PowerShell by running the command pwsh, enter the below command to install Posh SSH PowerShell module for SFTP.

Install-Module -Name Posh-SSH

2. (Optional for SFTP Only) When prompted, Press Y to install the Posh SSH PowerShell module.

3. Now, Enter the below command to install PowerShell module to support YAML.

Install-Module powershell-yaml

5. When prompted, Press Y to install the PowerShell-YAML module.

6. Add config values to config.yaml file.

7. Run the script by below command:

./ADscript.ps1

Note:

Private key for SFTP authentication should be in RSA format not in OpenSSH format. You can convert the format with this command:

ssh-keygen -m pem -f /path/to/key

Steps 1 to 6 are one time setup. Afterwards you just need to cd into that directory and execute 7th step only.

...

1. 1. "). You can add multiple OUs by comma separating each OU’s domain name. NEED TO FINISH ONCE I GET CLARIFICATION

2. If you want to automate this script, you will also need to adjust the following parameters in the file:

   1. $isSftpEnabled = $false - this determines whether the CSV gets sent to an sFTP server. By default, this is turned off.

   2. $sftpHost = "sftp.zillasecurity.com" - this is the hostname of the sFTP server we are sending the CSV to. If you are sending it to an sFTP server hosted by Zilla, then the default value (sftp.zillasecurity.com) can be left. If you are hosting this on your own sFTP server, then change the value to the hostname on your server.

   3. $sftpUsername = "<your domain.com>" - this is the username of the service account that will need to be created on your sFTP server. If you are using Zilla, the value for this will be the domain that is affiliated with your tenant. You can view this inside of Zilla by logging in as an admin, going to the settings on the left hand side panel, and looking at the first domain inside of your internal domains

      Image Added

   4. $applicationId = "<application-id>" - the application ID can be found by navigating to your active directory application inside of Zilla:

      Image Added

      and copying the string that appears inside of the URL:

      Image Added

   5. $sftpPrivateKeyPath = "<location of your private key>" - this is the filepath where you have stored your SSH Private Key. Please see the 3rd prerequisite for more details.

   6. $Csvfile = "$path\directory.csv" - you can use this setting to change the name of the CSV file that is generated. You can leave this as is

3. Once the script is configured, use task scheduler to automate the running of the script using the service account you created in the prerequisites. This guide goes through how to accomplish this.

Setup sFTP Server

For Security reason, Zilla recommends that you have Zilla Support create an sFTP server that will store the generated CSVs. You can also host it on-premise; however, this would require you to create an outbound port 22 rule for Zilla to fetch the CSV. The process is outlined in this documentation.

Zilla Configuration

1. Navigate to the application that you created in step 5 in the prerequisites section.

2. Select the gear icon inside of the application:

...

3. Upload one of the CSV exports that you generated to Zilla. See this guide on uploading a CSV.

4. Enable the Accounts & Permissions CSV File Upload section, then toggle on Use sFTP to automate CSV import.

...

4. Fill out the attributes in the form. Please see this section on guidance for how to fill these out.

5. Select Sync Now to kickoff the automated syncs.

Help:

Having trouble? Please refer to this documentation