Set up Zero Trust Client
The procedures on this page describe how to set up, download, and distribute the desktop version of Zero Trust Client.
Before you begin
- Allow access to Akamai domains and IP addresses in your firewall solution. Configure your network settings to bypass SSL inspection and authentication for Akamai domains. See Prepare for ZTC setup to learn more.
Upgrade from the EAA or ETP Client to Zero Trust Client
- The Akamai Zero Trust Client installer automatically uninstalls the standalone EAA and ETP Clients if they are detected on your computer. Your local ETP configuration will be retained and migrated to the new client. Note that the installer doesn't automatically migrate your EAA configuration.
- If you are using the EAA Client, copy your IdP hostname before installing ZTC. You will need your IdP hostname to configure Access in ZTC. To learn how to copy your IdP hostname from the EAA Client, refer to the EAA documentation.
- Make sure that you disable the installation of the standalone clients in your software deployment solution to prevent it from overwriting ZTC.
- To set up ZTC silently and use install parameters, see the silent install section.
- If you intend to perform a rollback for any reason, refer to Rollback to the standalone EAA or ETP Client.
To ensure a smooth transition, you may start with a small group of workstations as a pilot phase.
Download and install Akamai Zero Trust Client on Windows
A Zero Trust Client (ZTC) administrator or a delegated administrator can download Zero Trust Client. Enterprise Center also allows you to access and download all previously released versions of the client. To learn how to download the client, see Manage Zero Trust Client.
Before you begin
- Confirm that your environment meets the system and network requirements.
- You need Windows administrator rights to install the client.
- Uninstall the ZTC beta version (5.0) of the client if you have it installed.
How to
- Download the ZTC installer from a link provided by your IT administrator.
- Open the location where you download files and double-click the
AZTClient-<version>-windows.msifile. - Follow the on-screen instructions to complete the installation.
After the installation completes, the Akamai Zero Trust Client icon appears in your taskbar.
Next, you can configure your Akamai Zero Trust Client.
Download and install Akamai Zero Trust Client on macOS
A Zero Trust Client (ZTC) administrator or a delegated administrator can download Zero Trust Client. Enterprise Center also allows you to access and download all previously released versions of the client. To learn how to download the client, see Manage Zero Trust Client.
Before you begin
- Confirm that your environment meets the system and network requirements.
- Uninstall the ZTC beta version (5.0) of the client if you have it installed.
- Allow client network extensions if you've enabled transparent traffic interception in SIA.
How to
- Download the ZTC installer from a link provided by your IT administrator.
- Open the location where you download files and double-click the
AZTClient-<version>-macos.pkgfile. - Follow the on-screen instructions to complete the installation.
During the installation process, you may see a pop-up window requesting permission to allow the installer to modify apps on your Mac. Click OK to complete the installation.
Apple silicon users (MacBook M1 or later) are asked to install Rosetta during the installation procedure if it's not detected on the machine. Click Install to complete the installation. Rosetta enables a Mac with Apple silicon to use apps built for a Mac with an Intel processor.
After the installation completes, the Akamai Zero Trust Client icon appears in your menu bar.
Next, you can configure your Akamai Zero Trust Client.
Akamai Zero Trust Client silent installation
You might want to install ZTC in the background on many computers using software deployment solutions such as KACE, JAMF, or SCCM. You can execute the installation in command line mode. Command line installation for every software differs considerably. You can use this as a reference and update as required to suit your environment.
To perform a silent install you need to download the relevant files based on whether you want to deploy on a Windows or Mac platform.
You can append optional arguments to the installation command to pre-configure ZTC with an IdP hostname, or ETP entitlement or activation code.
If an existing version of ZTC is already installed (regardless of the version), the silent install first removes the existing installation before installing the new version.
Akamai Zero Trust Client silent install on Windows
How to
- Download the latest ZTC packages for Windows from Enterprise Center.
- Open the command line (
cmd) and enter the following command to start the silent installation. Replace<version>with the version number of the client you are installing.
msiexec /i <AZTClient-<version>-windows.msi> /quiet
You can also pass the following optional arguments:
| Parameter | What it does |
|---|---|
IDP="youridphostname.com" | Use this parameter if you want ZTC to authenticate with a pre-configured IdP hostname after the installation is complete. Enter the IdP hostname without the https:// protocol prefix. |
TOKEN="ETP activation or entitlement code" | Use this parameter if you want ZTC to activate Threat Protection with a pre-configured ETP entitlement or activation code after the installation is complete. If you're using the command line to distribute the Zero Trust Client across many computers with device management software, enter the entitlement code. If you're activating the client on a user's personal computer, you can enter an entitlement code or an activation code. |
AUTO_START="no" | By default, ZTC starts immediately after successful installation. Using this parameter with a no value prevents the GUI from launching automatically after the installation is complete. Note that if the user manually starts the client, it will automatically start from then on at OS boot, unless START_ON_BOOT=”no” is specified.This parameter isn't usually needed. Use it only if you have a strong reason to do so. |
START_ON_BOOT="no" | By default, the ZTC GUI loads automatically at OS startup. Use this parameter with a no value to disable this functionality. This parameter suppresses the auto start functionality, even if the user has manually started the client in the past.With Threat Protection enabled in Enterprise Center, ZTC onboards traffic to SIA even if the GUI is not running. With Access enabled in Enterprise Center, ZTC doesn’t onboard traffic to EAA if the GUI is not running or the user is not authenticated. |
MINIMIZED="yes" | By default, ZTC displays the GUI window after successful installation. Use this parameter with a yes value to start the GUI minimized. Note that this parameter applies only if autostart isn’t disabled with the AUTO_START="no" parameter. |
AZTC_LANG="language" | Use this parameter to change the language. English is the default display language. Available values are the following: Japanese, Brasil. |
FORWARD_PROXY="enable" | Proxy is disabled by default. Specifying this parameter starts the client with Remote Proxy enabled after the installation is complete. This lets ZTC use your manually configured OS proxy settings. To learn more about using proxies with Zero Trust Client, refer to the proxy documentation. |
FORWARD_PROXY_URL=<protocol>://<host>:<port> | With FORWARD_PROXY enabled, this parameter lets you use a PAC file and specify your forward proxy’s protocol, hostname, and port.Accepted protocols: httpsAccepted hosts: IPv4, IPv6, and domain name If you’d like to use an IPv6 address in a URL, encase it in a bracket. For example: https://[2001:db8::1]:80If your organization uses a PAC file, you need to modify it for it to work with Zero Trust Client. Contact your Akamai account representative for assistance. To learn more about using proxies with Zero Trust Client, refer to the proxy documentation. |
GC_OFFLINE_INSTALL="true"|"false" | When set to true, Segmentation is installed using the Agent version provided within the installer (network connectivity to the Aggregator is not required). |
GC_SERVER_ADDRESSES="<aggregator_address>:<aggregator_port>,<aggregator_address>:<aggregator_port>" | Comma-separated Aggregator IP addresses or hostnames. Addresses are to be provided by the Centra Technical platform owner. |
GC_PASSWORD="<password>" | Agent installation passphrase. Retrieve from the Centra UI: Administration → System → Configuration → Agents installation → Agents installation password |
GC_DATA_PATH="<dir>" | Set custom installation path for the Segmentation data files (certificates, log files, configuration, and storage). |
GC_LOGGING_PROFILE="<profile>" | Set the logging rotation profile for the Agent ('min', 'max' or 'medium'). |
GC_PROFILE="<profile>" | Install agent modules from a specific profile. |
GC_LABELS="<key1:value1,..,keyN:valueN >" | List of labels in the form of key1:value1,key2:value2 for labeling the agent instance. |
GC_OVERRIDE_UUID_FILE _RELOAD="true" | Don't use semi-persistent UUID file to mark agent UUID (Windows 2003 and above). |
WITH_ETP="false"Available in version 6.1.0 and later | Use this parameter to disable Threat Protection. When set to false, this parameter permanently disables the Threat Protection service on the workstation even if it’s available in your contract and configured in Enterprise Center.To enable Threat Protection again, reinstall the client without this flag. |
ALLOW_DOWNGRADE="yes"Available in version 6.1.0 and later | By default, Zero Trust Client prevents end-users from manually downgrading to an older version of the client. If the end-user attempts to install a version of the client that is older than the version they are currently running, the installation fails and client operation remains uninterrupted. By specifying this parameter, you allow your end-users to downgrade the client using an older version of the Zero Trust Client installer. Note that this parameter applies only to manual downgrade attempts. You can deploy a client downgrade from Enterprise Center regardless of the status of this parameter. |
Example
The following command silently installs ZTC with a pre-configured IdP hostname:
msiexec /i <AZTClient-<version>-windows.msi> IDP="connect.company.com" /quiet
Next, you can configure your Akamai Zero Trust Client.
Akamai Zero Trust Client silent install on macOS
How to
- Download the latest ZTC packages for macOS from Enterprise Center.
- You can define the following optional arguments in
aztc-install.cfgbefore you install the client:
aztc-install.cfgneeds to be placed in the same directory as the installer package. The configuration file gets deleted automatically after a successful installation.
| Parameter | What it does |
|---|---|
IDP=youridphostname.com | Use this parameter if you want ZTC to authenticate with a pre-configured IdP hostname after the installation is complete. Enter the IdP hostname without the https:// protocol prefix. |
TOKEN=ETP activation or entitlement code | Use this parameter if you want ZTC to activate Threat Protection with a pre-configured ETP entitlement or activation code after the installation is complete. If you're using the command line to distribute the Zero Trust Client across many computers with device management software, enter the entitlement code. If you're activating the client on a user's personal computer, you can enter an entitlement code or an activation code. |
AUTO_START=no | By default, ZTC starts immediately after successful installation. Using this parameter with a no value prevents the GUI from launching automatically after the installation is complete. Note that if the user manually starts the client, it will automatically start from then on at OS boot, unless START_ON_BOOT=”no” is specified.This parameter isn't usually needed. Use it only if you have a strong reason to do so. |
START_ON_BOOT=no | By default, the ZTC GUI loads automatically at OS startup. Use this parameter with a no value to disable this functionality. This parameter suppresses the auto start functionality, even if the user has manually started the client in the past.With Threat Protection enabled in Enterprise Center, ZTC onboards traffic to SIA even if the GUI is not running. With Access enabled in Enterprise Center, ZTC doesn’t onboard traffic to EAA if the GUI is not running or the user is not authenticated. |
MINIMIZED=yes | By default, ZTC displays the GUI window after successful installation. Use this parameter with a yes value to start the GUI minimized. Note that this parameter applies only if autostart isn’t disabled with the AUTO_START="no" parameter. |
AZTC_LANG=language | Use this parameter to change the language. English is the default display language. Available values are the following: Japanese, Brasil. |
FORWARD_PROXY=enable | Proxy is disabled by default. Specifying this parameter starts the client with Remote Proxy enabled after the installation is complete. This lets ZTC use your manually configured OS proxy settings. To learn more about using proxies with Zero Trust Client, refer to the proxy documentation. |
FORWARD_PROXY_URL=<protocol>://<host>:<port> | With FORWARD_PROXY enabled, this parameter lets you use a PAC file and specify your forward proxy’s protocol, hostname, and port.Accepted protocols: httpsAccepted hosts: IPv4, IPv6, and domain name If you’d like to use an IPv6 address in a URL, encase it in a bracket. For example: https://[2001:db8::1]:80If your organization uses a PAC file, you need to modify it for it to work with Zero Trust Client. Contact your Akamai account representative for assistance. To learn more about using proxies with Zero Trust Client, refer to the proxy documentation. |
GC_OFFLINE_INSTALL=true|false | When set to true, Segmentation is installed using the Agent version provided within the installer (network connectivity to the Aggregator is not required). |
GC_SERVER_ADDRESSES=<aggregator_address>:<aggregator_port>,<aggregator_address>:<aggregator_port>" | Comma-separated Aggregator IP addresses or hostnames. Addresses are to be provided by the Centra Technical platform owner. |
GC_PASSWORD=<password> | Agent installation passphrase. Retrieve from the Centra UI: Administration → System → Configuration → Agents installation → Agents installation password |
GC_DATA_PATH=<dir> | Set custom installation path for the Segmentation data files (certificates, log files, configuration, and storage). |
GC_LOGGING_PROFILE=<profile> | Set the logging rotation profile for the Agent ('min', 'max' or 'medium'). |
GC_PROFILE=<profile> | Install agent modules from a specific profile. |
GC_LABELS=<key1:value1,..,keyN:valueN > | List of labels in the form of key1:value1,key2:value2 for labeling the agent instance. |
WITH_ETP=falseAvailable in version 6.1.0 and later | Use this parameter to disable Threat Protection. When set to false, this parameter permanently disables the Threat Protection service on the workstation even if it’s available in your contract and configured in Enterprise Center.To enable Threat Protection again, reinstall the client without this flag. |
ALLOW_DOWNGRADE=yesAvailable in version 6.1.0 and later | By default, Zero Trust Client prevents end-users from manually downgrading to an older version of the client. If the end-user attempts to install a version of the client that is older than the version they are currently running, the installation fails and client operation remains uninterrupted. By specifying this parameter, you allow your end-users to downgrade the client using an older version of the Zero Trust Client installer. Note that this parameter applies only to manual downgrade attempts. You can deploy a client downgrade from Enterprise Center regardless of the status of this parameter. |
- In the macOS Terminal, enter the following command to start the silent installation. Replace
<version>with the version number of the client you are installing.
sudo installer -pkg <AZTClient-<version>-macos.pkg> -target /
- The installation starts and runs in the background. After the installation is complete, the ZTC window opens. If you encounter issues during the installation, refer to the troubleshooting section.
Example
The following commands silently install ZTC with a pre-configured IdP hostname and ETP code:
cat > ./aztc-install.cfg << EOF
IDP=youridphostname.com
TOKEN=9ffc01d7-0000-0000-0000-40c3ffbf70fa
EOF
sudo installer -pkg ./<AZTClient-<version>-macos.pkg> -target /
rm ./aztc-install.cfg || true
Next, you can configure your Akamai Zero Trust Client.
(Zero Trust Client 6.1.0) Set up Access hook scripts
This optional feature lets you set up and execute custom scripts based on the authentication state of the Access service. It provides flexibility for administrators to automate tasks depending on the current Access status of users. The scripts are executed with the end-user’s privileges.
Supported script types
macOS
Supported script types: .sh
Default script paths:
/Library/Application Support/AZTClient/hooks/on_login.sh
/Library/Application Support/AZTClient/hooks/on_logout.sh
Windows
Supported script types: .bat, .cmd, .ps1, .exe
Default script paths:
C:\Program Files\AZTClient\hooks\on_login.bat
C:\Program Files\AZTClient\hooks\on_logout.bat
Set up your Access hook scripts
Follow these instructions to create script hooks and set up the necessary read-only access for non-admin users.
macOS
- Write your script and save it with a
.shextension as follows:on_login.shruns when Access status becomes authenticated.on_logout.shruns when Access status becomes unauthenticated.
- Move the script(s) to the default scripts directory:
/Library/Application Support/AZTClient/hooks/ - Ensure the script files are read-only for non-admin users. You can set the necessary permissions by running the following commands from your admin account:
chmod 755 /Library/Application Support/AZTClient/hooks/on_login.sh
chmod 755 /Library/Application Support/AZTClient/hooks/on_logout.sh
You’ve just set up your Access hook scripts on macOS. The scripts will be executed automatically when the Access authentication state changes.
Windows
- Write your script and save it with a
.bat,.cmd,.ps1, or.exeextension as follows:on_login.bat/cmd/ps1/exeruns when Access status becomes authenticated.on_logout.bat/cmd/ps1/exeruns when Access status becomes unauthenticated.
- Move the script(s) to the default scripts directory:
C:\Program Files\AZTClient\hooks - Ensure the script files are read-only for non-admin users. You can set the necessary permissions by right-clicking the script file, selecting
Properties, navigating to theSecuritytab, and modifying the permissions accordingly.
You’ve just set up your Access hook scripts on Windows. The scripts will be executed automatically when the Access authentication state changes.
Updated about 2 months ago