# Service Accounts A service account is a type of user account that provides programmatic access to resources via StrongDM. Unlike a [user account](/admin/principals.md), a service account requires only a display name—not a full name and email address—because service accounts are for machines, programs, and applications, not people. Service accounts authenticate to StrongDM with admin tokens in order to conduct automated administrative processes or perform any automated function that needs resource access. They are used for automation or for allowing programs and applications to use StrongDM, when there is no live human to authenticate. For example, a service account is ideal for the following: * Continuous-integration pipelines * Periodic extract-transform-load (ETL) jobs * Business intelligence (BI) tools * Jupyter Notebooks and similar self-contained analysis environments * Containerized environments (often in conjunction with the StrongDM client container) that need access to StrongDM-protected resources This article describes how to create service accounts in the Admin UI and gain a token to use for authentication. ### Create a Service Account To create service accounts, make sure you have admin access to the Admin UI. Then follow these steps: 1. In the Admin UI, select **Principals** > **Users** from the navigation menu. 2. Click the **Add service** button. 3. Enter a name for the service account. Notice that a first/last name and email address are not needed because service accounts are for programs/machines, not people. 4. Click **Create service account**. 5. Copy the generated service account token and keep it somewhere safe, as you won't be able to see it again. ### Grant Access to Resources StrongDM uses role-based privileges to control access to [resources](/admin/resources.md). Like user accounts, service accounts gain access to resources through role membership, via the static and dynamic access rules that have been defined for that role. For information on how to assign a role to an account, see [Roles](/admin/access/roles.md). ### Authenticate After creating a service account, generating a service account token, and granting the account access to resources via role membership, you need to authenticate the account in your environment in order to use it. Once authenticated, the [CLI Reference](/references/cli.md) and [StrongDM Client](/users/client.md) behave the same as they would for a normal user. In this section, you learn the various ways to authenticate with a service account on macOS, Linux, and Windows. #### Service accounts on Linux On Linux, use the CLI for authentication. Pass the service account token to the CLI login command. ```sh sdm login --admin-token='' ``` #### Service accounts on macOS On macOS, you can authenticate via the CLI or the StrongDM Desktop application. To use the CLI to authenticate, pass the service account token to the CLI login command. ```sh sdm login --admin-token='' ``` To use the desktop app to authenticate, follow these steps: 1. Select the desktop app's **sdm** icon from the menu bar on your screen. 2. Paste the service account token into the email field; StrongDM automatically detects the format as a service account token. Click `continue`. #### Use environment variables to pass the token 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, by specifying the command in your shell profile, or by adding it before a command. **Export** ```sh export SDM_ADMIN_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. ```sh echo 'export SDM_ADMIN_TOKEN=' >> ~/.bash_profile ``` **In line** Environment variables also can be read when specified before a command. ```sh SDM_ADMIN_TOKEN= sdm login ``` #### Test that it's 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. ```bash $ sdm status DATASOURCE STATUS PORT TYPE pgsql_1_31 not connected 5432 postgres SSH SERVER STATUS PORT TYPE server-245a not connected 61334 ssh ``` #### Service accounts on Windows **Standard Windows installation** Most users following the standard [Windows Installation Guide](/users/client/windows.md) can authenticate StrongDM with a service account token and these steps: 1. Start the StrongDM Desktop application. 2. 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 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](#windows-as-a-service-installation). 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](/users/client/windows.md#download-the-strongdm-cli-only) section. Additionally, you can directly download the CLI installer in the Admin UI from the **Downloads** page. **Run the installer** Use the following steps to run the installer after it is downloaded and unzipped. 1. Open a PowerShell terminal as an administrator. 2. Navigate to the directory containing the **sdm32.exe** binary we unzipped when downloading the StrongDM CLI. 3. 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. ```powershell Installing StrongDM listener - paste the token and press ENTER: ``` 4. Paste the service account token assigned to this resource and hit enter. 5. 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. ```powershell 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: ```powershell 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 ``` {% hint style="info" %} 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. {% endhint %} **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](#download-the-cli-package) and [run the installer](#run-the-installer). {% hint style="info" %} The Windows service installer is only supported on machines with `C:/` as their boot drive. {% endhint %} 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. 1. Open the Command Prompt. 2. Confirm the port is in use: ```powershell netstat -ano | find "LISTEN" | find "65220" ``` The process ID (PID) is listed in the last column. 3. Confirm which process is using the port: ```powershell tasklist /fi "PID eq ``` The output shows the image name, PID, session name, session number, and memory usage information, as in the following example. ```powershell Image Name PID Session Name Session# Mem Usage ========================= ======== ================ =========== ============ sdm.exe 26740 Services 0 48,760 K ``` {% hint style="info" %} 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/[User]/.sdm` directory. This allows multiple Windows users to take advantage of a single installation of StrongDM. {% endhint %} **Uninstall the Windows service** To uninstall the Windows service, run: ```powershell 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: ```powershell sdm32.exe uninstall preparing to uninstall ... uninstalling StrongDM listener uninstall failed, see sdm-uninstall-1594851455.log for details press enter to close... ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.strongdm.com/admin/principals/service-accounts.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.