# On-premise Active Directory

## Overview

This guide describes an example desktop client provisioning scenario in an on-premise Active Directory environment.

The guide assumes that our goal is to provision desktop clients for a set of users in a specific AD group.

Please note that it is just a reference, you should adjust it to work with your specific environment and preferred tooling.

## Generating enrollment tokens

To automate the process as much as possible we've prepared an example PowerShell script which can be used to generate enrollment tokens for all users in a specified group. The script can be downloaded [here](https://github.com/DefGuard/client/blob/555fb727d3599264996ee1ac99f5124026083146/src-tauri/resources-windows/admin-scripts/GenerateEnrollmentTokensAD.ps1).

### Prerequisites

* network access to both a Defguard instance and AD Domain controller
* `ActiveDirectory` PowerShell module; to install you can run the following command in an admin shell: `Get-WindowsCapability -Name RSAT.ActiveDirectory.DS-LDS.Tools~~~~0.0.1.0 -Online | Add-WindowsCapability -Online`

### Defguard authentication

To securely access your Defguard instance's REST API you need to generate an [API Token](https://docs.defguard.net/integrations/api-tokens#generating-api-token).

### Active Directory authentication

By default the script will use current user's credentials for AD authentication.

Alternatively if you specify a username by the `ADUsername` parameter you'll be prompted for a password.

### Required parameters

* `Url` - URL of your Defguard instance
* `ApiToken` - your API token for Defguard API access
* `GroupName` - name of user group for which to generate enrollment tokens
* `ADAttribute` - name of AD attribute where the provisioning config data will be stored

### Optional parameters

* `ADUsername` - username for domain controller authentication
* `DomainController` - your AD domain controller URL
* `EnrollmentTokenExpirationTime` - how long should the generated enrollment tokens be valid for (default is 24h); should be specified as human-readable string, e.g 24h, 1d, 2w etc

### Example script execution command

`.\GenerateEnrollmentTokens.ps1 -Url "https://defguard.example.com" -ApiToken "dg-your-generated-token" -GroupName "DgProvisioning" -ADAttribute "extensionAttribute3" -ADUsername "administrator" -DomainController "ad.example.com"`

## Client provisioning scenario

1. **Setup target users**
   * prepare a user group containing all the users you intend to perform client provisioning for
2. **User synchronization**
   * Configure two-way Active Directory synchronization as described [here](https://docs.defguard.net/features/ldap-and-active-directory-integration/two-way-ldap-and-active-directory-synchronization)
3. **Token Generation**
   * Generate enrollment tokens for users using the [helper script](#generating-enrollment-tokens)
4. **Client Installation**
   * Install the `defguard-client` application on user machines using the [MSI installer](https://docs.defguard.net/features/desktop-client-auto-provisioning/..#msi-installer-integration)
   * Pass the `PROVISIONING=1` argument to execute provisioning script during installation
   * Example command: `msiexec /i defguard-client.msi PROVISIONING=1 ADAttribute="description"`
5. **Automatic Configuration**
   * During installation, the bundled script fetches [provisioning configuration](https://docs.defguard.net/features/desktop-client-auto-provisioning/..#active-directory-configuration) from Active Directory
   * The configuration is written to the client's [data directory](https://docs.defguard.net/using-defguard-for-end-users/desktop-client#storage) as explained [here](https://docs.defguard.net/features/desktop-client-auto-provisioning/..#configuration-file-creation)
6. **User Enrollment**
   * When the user launches the client for the first time, they are guided through the enrollment process
   * The enrollment uses the pre-configured token and URL from the provisioning file
7. **Client Ready**
   * Once enrollment is complete, the user can establish VPN connections and access protected resources


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.defguard.net/features/desktop-client-auto-provisioning/auto-provisioning-in-windows-environments/on-premise-active-directory-environments.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.