Artica Authentication Agent Installation on Artica Proxy Server

Back to Artica Authentication Agent main section

Agent Installation on your Artica Proxy Server.

Install the Feature

Go to Your System → Features menu.
Search for Artica Authentication Agent.
Click Install.

During installation, Artica removes the native proxy authentication; therefore, a short downtime is expected.

Import the Client Certificate

Communication between Artica and the Windows Authentication Agents is secured using mutual TLS (mTLS), providing a zero-trust connection.

Export the client certificate from the Windows Authentication Agent.
In the Artica Web Console, import the ZIP file into Your System → Certificate Center.

Agent Settings

Navigate to Artica Auth Agent → Settings.

Two tabs are available:

Main – Configure communication, health checks, cache, and emergency modes.
Agents – Add and manage Windows Authentication Agents.

Main Tab

This tab allows you to configure communication, health checks, cache, and emergency modes.

Note: Settings here control how Artica Proxy are configured:

artica-auth-helper is used for auth_param negotiate (authentication).
artica-groups-helper is used for external_acl parameters (group-based access control).

Authentication Settings

Option Name	Description	Allowed Values
Authentication Mode	Select the method of authentication.	`Negotiate`, `NTLM`, or `Basic`
Distribution Mode	How to distribute requests across multiple agents.	`single` Auto-set when only one agent is configured. `failover` Uses the highest-priority healthy agent. Switches to the next agent only on failure. Default when 2+ agents are configured. `load-balance` Distributes requests across all healthy agents proportionally to their `weight`. Agents marked `failover: true` are only used when all active agents are down.
Workers	Number of concurrent goroutines for proxy authentication. Only applies to Basic Authentication; NTLM and Negotiate are limited to 1 due to per-connection session requirements.	`Integer`
Basic authentication for users outside the domain	Allow automatic fallback to Basic Authentication if the browser does not support Kerberos or NTLM.	`On` / `Off`

Healthcheck Settings

Option Name	Description	Allowed Values
Enable	Enable periodic health checks.	`On` / `Off`
Interval	Time in seconds between health check probes.	`Integer (seconds)`
Timeout	Maximum time to wait for a health check response.	`Integer (seconds)`
Failure threshold	Consecutive failures before marking an agent unhealthy.	`Integer`
Success threshold	Consecutive successes before marking an agent healthy again.	`Integer`

Emergency mode Settings

Ensures network access continues when all authentication agents are unavailable. When disabled, users lose internet access if all agents are unreachable.

Option Name	Description	Allowed Values
Enable	When enabled, if all agents are unreachable, the helper returns OK for every request instead of blocking users.	`On` / `Off`
Timeout	How long to wait before declaring agent failure when emergency mode is active.	`Integer (seconds)`

Cache Settings

Controls caching of authentication and group lookup results

Option Name	Description	Allowed Values
Enable	Enable or disable caching entirely.	`On` / `Off`
Authentication TTL	TTL for successful Negotiate and Basic authentication results. During this period, repeat logins with the same credentials are served from cache without contacting the agent. NTLM authentication can't be cached!.	`Integer (minutes)`
Groups TTL	TTL for group membership lookups. Cached group results avoid repeated LDAP queries.	`Integer (minutes)`
Negative TTL	TTL for failed authentication attempts. Rate-limits brute-force and password-spraying attacks by rejecting repeated failed attempts without contacting the agent. Applies to all auth types.	`Integer (seconds)`

Logging Settings

Choose the Logging verbosity.
Default logs location:
Authentication: /var/log/squid/artica-auth.log
Groups Lookups: /var/log/squid/artica-groups.log

Option Name	Description	Allowed Values
Level	Minimum log level.	`info` / `debug` / `warn` / `error`
Max Size (MB)	Maximum megabytes before log rotation.	`Integer (mb)`
Max Backups to Keep	Number of rotated log files to keep.	`Integer`
Max Days to Keep	Days to retain rotated log files.	`Integer (days)`

Agents Tab

This tab allows you Add, Edit, Remove and Monitor agents

Add a New Agent

Ensure that TCP ports 8443 (gRPC) and 8444 (Status API) are open and reachable from your Artica Proxy server to the Windows agent host.

Click New Agent.
Select the Agent Certificate previously imported into Artica Certificate Center.
Enter the IP address or hostname of the machine where the Windows Agent is installed.
Configure the gRPC communication port (default: 8443).
Configure the API status port (default: 8444).
Specify the Priority used in failover mode.
Lower values indicate higher priority (1 = primary).
Specify the Weight used in load-balancing mode.
Higher values receive more traffic.
Enable or disable Failover.
When enabled, the agent operates in standby mode and is used only if all non-failover agents are unhealthy.
Select the bind Network Interface. Leave empty to use the default route.
Click Save.

Monitor the Agent

After adding the agent, it appears in the table where you can monitor its status and connectivity.

Edit Agent

In the Agents table, click the agent name or agent IP/Hostname to edit its configuration.

Delete Agent

In the Agents table, click on Delete button.