Service Accounts
Last modified on March 24, 2023
Service accounts allow for programmatic access to StrongDM resources. This is useful for continuous-integration pipelines, extract-transform-load jobs, or any automated function that would need resource access. Check the Admin UI Guide to see how to create service accounts. The rest of this guide covers how to authenticate with a service account on macOS, Linux, and Windows.
Service Accounts on macOS and Linux
Use the CLI
Pass the service account token to the CLI login command.
sdm login --admin-token='<SERVICE_ACCOUNT_TOKEN>'
Use StrongDM Desktop (macOS only)
- Select the desktop app’s sdm icon from the menu bar on your screen.
- Press the
esc
key three times. That causes the prompt to change fromemail
toservice account token
. - Paste the service account token and click
continue
.
Environment Variables
The StrongDM client checks the local environment for the variable SDM_ADMIN_TOKEN. There are several ways to add the variable to the environment: via export, specifying the command in your shell profile, or adding it before a command.
Export
export SDM_ADMIN_TOKEN=<TOKEN>
sdm login
Shell profile
You can add the environment variable during a login event by specifying the previous command in your shell profile. This approach is similar among all of the shells.
echo 'export SDM_ADMIN_TOKEN=<TOKEN>' >> ~/.bash_profile
In line
Environment variable can also be read when specified before a command.
SDM_ADMIN_TOKEN=<TOKEN> sdm login
Check That It Is Working
At this point, you should see any assigned resources in your desktop app or the CLI.
To check in the desktop app, click the sdm icon in the menu bar of your screen. All of the resources available to you are shown.
To check in the CLI, enter the command sdm status
, as in the following example.
$ sdm status
DATASOURCE STATUS PORT TYPE
pgsql_1_31 not connected 5432 postgres
SSH SERVER STATUS PORT TYPE
server-245a not connected 61334 ssh
General Usage
Once authenticated, the CLI and desktop app behave the same as they would for a normal user.
Service Accounts on Windows
Standard Windows Installation
Most users following the standard Windows installation can authenticate StrongDM with a service account token and these steps:
- Start the StrongDM Desktop application.
- At the login window, hit the
<esc>
key three times. - This changes the login field to say service account token.
- Paste the token and click continue.
Automated Installation
To bypass the desktop app and use only the CLI, or to automate the installation process, you can directly download just the StrongDM CLI from the Admin UI. The steps in this section can also be used to install the StrongDM CLI as a Windows service. This package works on Windows 2008R2 and later.
To successfully perform the steps in this section, you must be:
- A StrongDM administrator with the ability to create and retrieve a service account token.
- A local administrator on your Windows workstation.
Download the CLI package
Start by following steps 1 through 5 in the Download the StrongDM CLI section. Additionally, you can directly download the CLI installer.
Run the installer
Use the following steps to run the installer after it is downloaded and unzipped.
Open a PowerShell terminal as an administrator.
Navigate to the directory containing the sdm32.exe binary we unzipped when downloading the StrongDM CLI.
Run
.\sdm32.exe install
to receive the following output. If prompted, confirm to continue with administrator access. Newer versions of Windows correctly determine administrator privileges and do not typically show this prompt.Installing StrongDM listener - paste the token and press ENTER:
Paste the service account token assigned to this resource and hit enter.
Customize the installation path and data path, or hit enter twice to accept the defaults. A successful install looks like the following output. If the installation fails, verify you are running PowerShell as an administrator.
Installing StrongDM listener paste the token and press ENTER: eyJhbGciOiJ... installation path [C:\Program Files (x86)\StrongDM]: data path [C:\WINDOWS\system32\config\systemprofile\AppData\Local\StrongDM]: Copying files Installation complete Service installed and started
Test the setup
To confirm the installation and authentication were successful, open a new PowerShell window as an admin and run sdm status
. The output looks similar to this:
C:\Windows\system32> sdm status
CLOUD STATUS PORT OVERRIDE TYPE TAGS URL
AWS example not connected 65111 aws region=us-west-2
CLUSTER STATUS PORT OVERRIDE TYPE TAGS
K8s example not connected 18443 kubernetes team=Example
DATASOURCE STATUS PORT OVERRIDE TYPE TAGS
mysql-db not connected 13306 mysql
oracle-db not connected 11521 oracle
SERVER STATUS PORT OVERRIDE TYPE TAGS
TCP example not connected 59150 rawtcp
sdm32.exe
rather than sdm
(for example, .\sdm32 status
). In this situation, the path is set properly after a Windows reboot.Windows as a service installation
This section contains information about how to install the StrongDM CLI on Windows in order to run it as a background service that automatically connects to certain resources on startup. Before you continue, download the CLI package and run the installer.
C:/
as their boot drive.When running the StrongDM CLI package in this manner, the installer updates the Windows registry, assigning the StrongDM executable to the service and making sure the software boots with the winsvc
process. If you delete these Windows registry entries for winscv
, the StrongDM executable behaves like the typical CLI included with the desktop app.
To ensure proper authentication, the StrongDM executable requires that the StrongDM listener service is running. The port opened when the listener starts is 65220
. To confirm these details, use these steps.
Open the Command Prompt.
Confirm the port is in use:
netstat -ano | find "LISTEN" | find "65220"
The process ID (PID) is listed in the last column.
Confirm which process is using the port:
tasklist /fi "PID eq <PID_VALUE>
The output shows the image name, PID, session name, session number, and memory usage information, as in the following example.
Image Name PID Session Name Session# Mem Usage ========================= ======== ================ =========== ============ sdm.exe 26740 Services 0 48,760 K
sdm connect
to connect to a StrongDM resource from their profile, credentials are added to the state.db
file in the /Users/[User]/.sdm
directory. This allows multiple Windows users to take advantage of a single installation of StrongDM.Uninstall the Windows service
To uninstall the Windows service, run:
sdm32.exe uninstall
This action removes the StrongDM listener and deletes any keys previously added to the Windows registry. The output looks similar to the following:
sdm32.exe uninstall
preparing to uninstall ...
uninstalling StrongDM listener
uninstall failed, see sdm-uninstall-1594851455.log for details
press enter to close...
If you have trouble authenticating with your service account, please contact support@strongdm.com with details.