Install Aembit Desktop and sign in

Install on your Windows 11 machine, trust your Aembit Tenant’s certificate authority, sign in through your Identity Provider, and point a tool at the local proxy. Everything here happens on your own machine. An Aembit Tenant administrator does the other half in the Aembit Tenant UI, following Set up user access for Aembit Desktop.

Before you begin

Get these from your Aembit Tenant administrator before you start:

The Aembit Client ID. Everyone who signs in through the same Identity Provider uses the same value, and you pass it to adt login. It identifies your Identity Provider for Aembit Desktop sign-in; a ‘s Aembit Client ID is a different value.
Your tenant ID. It’s the first part of your Aembit Tenant UI address: the tenant ID in https://abc123.aembit.io is abc123.
The address of a service you can reach, which the administrator configured as a .

You also need a Windows 11 machine and permission to install software on it. The installer writes to C:\Program Files\ and changes the system PATH, so it prompts for administrator approval.

Install Aembit Desktop

Download the Windows installer from the Aembit Desktop releases page.

The filename is aembit_desktop_windows_amd64_<version>.msi. The releases page lists the checksum beside the download and shows how to verify it.
Run the installer and accept the administrator prompt.

The installer puts adt.exe in C:\Program Files\Aembit\Desktop\ for every account on the machine and adds that directory to the system PATH. Installing a newer version over an existing one stops Aembit Desktop first, so run adt start again after an upgrade.
Open a new terminal and confirm that adt is on your PATH:
Terminal window
```
adt --version
```
The terminal must be one you opened after the install finished, because an existing terminal holds the PATH it started with.

Trust the Aembit Tenant CA certificate

Aembit Desktop terminates TLS on its way through the local proxy, using a certificate issued under your Aembit Tenant’s certificate authority. When the Client Workload has a standalone certificate authority, Aembit Cloud issues the certificate under that one instead. Your machine rejects those connections until it trusts that certificate authority.

Write the certificate to a file, substituting your own tenant ID:
Terminal window
```
adt get-tenant-ca-cert --tenant-id abc123 --file aembit-tenant-ca.crt
```
adt saves the certificate and installs nothing. It also prints a certutil command that trusts the certificate for your Windows user only, which the next step replaces with a machine-wide import.
Add the certificate to the machine’s trusted root store from an elevated PowerShell prompt:
Terminal window
```
Import-Certificate -FilePath .\aembit-tenant-ca.crt -CertStoreLocation Cert:\LocalMachine\Root
```
Tools that keep their own trust store, such as some language runtimes and container images, need the certificate added there as well.
Close the elevated prompt, and run the rest of the adt commands from a regular PowerShell window. Background services started from an elevated prompt run with administrator privileges.

Start Aembit Desktop

adt start

adt start launches two background services: one that holds your session credentials and one that runs the proxy on 127.0.0.1, port 8000 unless your administrator changed it. It prints the address the proxy listens on. Both keep running after you close the terminal. Nothing starts them again after the machine restarts, so run adt start after each restart.

Start Aembit Desktop before you set HTTP_PROXY or HTTPS_PROXY for your tools. The proxy service refuses to start when either variable already points at its own address, because that would send its own outbound traffic back to itself. For a traffic type whose variable is unset or empty, it checks the Windows manual proxy setting the same way.

Run adt login with the Aembit Client ID your administrator gave you:
Terminal window
```
adt login --client-id <aembit-client-id>
```
When your administrator delivered the Aembit Client ID in a settings file, run adt login without --client-id. adt prints the authorization URL and opens it in your default browser. Pass --no-browser to have it print the URL without opening anything, then open the URL yourself.
Sign in at your Identity Provider in the browser, under whatever rules your organization already enforces.

adt prints Login successful. once it stores the session.

Your session lasts as long as your administrator configured. The credential service renews your tokens on a schedule while it runs. The session ends early when the credential service goes a full Token Lifetime without renewing, for example because your machine was off or you ran adt stop. It ends at the Absolute Token Lifetime however often it renewed. Either way, you run adt login again.

The credential service also stops renewing after a renewal fails, for example because your machine had no network connection at that moment. Run adt stop and then adt start to retry the renewal, or run adt login if that doesn’t restore access.

Route a tool through the proxy

Aembit Desktop intercepts nothing on its own. After adt start has run, point each tool at the local proxy in one of these ways:

adt beta shell opens a new shell with HTTP_PROXY and HTTPS_PROXY set to the local proxy. When the SHELL environment variable names a program other than PowerShell, as Git Bash and Cygwin set it, it opens that program; otherwise it opens PowerShell 7 or Windows PowerShell. Windows PowerShell 5.1 doesn’t send Invoke-WebRequest or Invoke-RestMethod requests through the proxy those variables name, because those commands read proxy environment variables only from PowerShell 7.0 on. Started from Command Prompt, adt beta shell opens Windows PowerShell 5.1, so start it from PowerShell 7 to use those commands.
adt beta env prints the commands that set the same variables, choosing the syntax the same way. Pass --pwsh or --sh to choose PowerShell or Portable Operating System Interface (POSIX) shell syntax instead, for example --pwsh in a PowerShell session that inherited SHELL from Git Bash. It has no Command Prompt syntax, so run it from PowerShell, Git Bash, or Cygwin. To apply them to the current PowerShell session:
Terminal window
```
adt beta env --pwsh | Invoke-Expression
```
The tool’s own proxy setting, or the variables set by hand, with the port adt start printed in place of 8000 when your administrator changed it:
Terminal window
```
$env:HTTP_PROXY = "http://127.0.0.1:8000"
$env:HTTPS_PROXY = "http://127.0.0.1:8000"
```

Both adt beta commands read the port from the running proxy and fail when adt start hasn’t run. They read it once, so after the port changes, open a new adt beta shell or run adt beta env again. Neither sets NO_PROXY, so set it yourself for any host that must bypass the proxy. Tools that pin TLS certificates reject the proxy’s certificate whatever you configure, so route those around the proxy with NO_PROXY.

Don’t run adt start from a shell that already points at the local proxy, such as one adt beta shell opened. The proxy service refuses to start there, because its own outbound traffic would come back to itself.

Verify access

Replace 8000 with the port adt start printed if your administrator changed it.

curl.exe --proxy "http://127.0.0.1:8000" "https://<server-workload-address>"

Type curl.exe, with the extension. In Windows PowerShell, curl is an alias for Invoke-WebRequest, which takes different options and ignores the --proxy flag.

Test against a service that rejects requests without a valid credential. A successful response from such a service means the request reached it with an Aembit-brokered credential attached, because you never supplied one. A service that accepts requests without a credential can respond even when no Client Workload matches you, because the proxy then passes the HTTPS connection through without injecting anything. A rejection can instead come from the service, the target URL, the network, or TLS certificate validation. Ask your administrator to use to determine whether Aembit denied the request. They can then confirm that an active and its components match the request.

Run adt status at any time to see whether the services are running and whether you hold a current session. Add --verbose for process IDs and credential storage detail.

Stop and sign out

adt logout

adt logout discards the stored session, and the next adt login sends you back to your Identity Provider. Run it before adt stop, because it reaches the credential service to clear what that service holds.

adt stop

adt stop stops both background services. It leaves your session in place, so adt start after a plain adt stop picks up where you left off.

Troubleshooting

When a command fails or a tool can’t reach a service, see Troubleshoot Aembit Desktop.

Next steps

Aembit Desktop reference - Every adt command and option, the settings, the environment variables, and the defaults and limits
Aembit Desktop concepts - What the two background services do and how a credential reaches a request
What Aembit Desktop supports - The platforms, protocols, and sign-in methods Aembit Desktop supports