Service Accounts

Last modified on September 22, 2023

Service accounts allow for programmatic access to StrongDM resources, which is useful for continuous-integration pipelines, extract-transform-load jobs, or any automated function that would need resource access.

This page describes how to create and 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.
Paste the service account token into the email field; StrongDM automatically detects the format as a service account token. Click continue.

Environment variables

The StrongDM client checks the local environment for the variable SDM_ADMIN_TOKEN. You can add the variable to the environment by exporting it, by specifying the command in your shell profile, or by 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 variables can also be 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.

Click the sdm icon in the menu bar of your screen to open the desktop app and see all of the resources available to you are shown.

In the CLI, enter the command sdm status, as in the following example, to see the resources available to you.

$ 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.
Paste the service account token into the email field; StrongDM automatically detects the format as a service account token. Click continue.

Automated installation

To bypass the desktop app and use only the CLI, or to automate the installation process, you can download the StrongDM CLI directly from the Admin UI.

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.

The information in this section can also be used to install the StrongDM CLI as a Windows service that runs in the background and that automatically connects to certain resources on startup.

Note that this package works on Windows Server 2008 R2 and later. The Windows service installer is only supported on machines with C:/ as their boot drive.

Download the CLI package

Start by following steps 1 through 5 in the Download the StrongDM CLI section of the Windows installation guide.

Alternatively, you can click to directly download the CLI installer. (Clicking the link starts the download.)

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

If you are installing Windows as a service, continue with step 7 to the end of this section. If you are not, proceed to test the setup.
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, 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

When a user utilizes sdm connect to connect to a StrongDM resource from their profile, credentials are added to the state.db file in the /Users/<USERNAME>/.sdm directory. This allows multiple Windows users to take advantage of a single installation of StrongDM.

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

Some older versions of Windows do not update the PATH until the system is rebooted. If you get an error, use the existing sdm32.exe rather than sdm (for example, .\sdm32 status). In this situation, the path is set properly after a Windows reboot.

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.

Service Accounts

Service Accounts on macOS and Linux #

Use the CLI #

Use StrongDM Desktop (macOS only) #

Environment variables #

Export #

Shell profile #

In line #

Check that it is working #

General usage #

Service Accounts on Windows #

Standard Windows installation #

Automated installation #

Download the CLI package #

Run the installer #

Test the setup #

Uninstall the Windows service #