Skip to content

website/docs: improve service account docs #22145

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dominic-r wants to merge 2 commits into
base: main
Choose a base branch
from
+96 −67
Draft

website/docs: improve service account docs #22145

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5ec3a10
website/docs: improve service account docs
dominic-r May 8, 2026
940ee34
website/docs: title service account warning
dominic-r May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 96 additions & 67 deletions website/docs/sys-mgmt/service-accounts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,107 +3,136 @@ title: Service Accounts
sidebar_label: Service Accounts
---

Service accounts are specialized user accounts designed for machine-to-machine authentication and automation purposes rather than interactive human use. They're ideal for integrating authentik with external systems, APIs, and services.
Service accounts are specialized user accounts for machine-to-machine authentication and automation. Use them when an external service, script, integration, or protocol client needs to authenticate to authentik without representing a human user.

## Types of Service Accounts
Common examples include LDAP bind users, automation that calls the authentik API, SCIM or outpost-related integrations, and third-party applications that need a stable credential.

authentik distinguishes between two types of service accounts:
## Types of service accounts

1. **User-created Service Accounts**: Created by administrators for integrating with external systems or for automation purposes.
2. **Internal Service Accounts**: Created and managed automatically by authentik for internal purposes, such as outpost communications. These cannot be created manually.
authentik has two service account types:

- **User-created service accounts**: accounts created by administrators for external systems or automation. These accounts appear under **Directory** > **Users** with the `Service account` user type.
- **Internal service accounts**: accounts created and managed by authentik for internal components, such as outpost communication. These accounts cannot be created manually, converted to another user type, or edited like regular users.

## How service accounts work

A user-created service account is an authentik user with the `Service account` type and an unusable password. Instead of a normal password, it authenticates with tokens:

- **App passwords** authenticate to flows and protocol clients that accept a username and password, such as LDAP bind clients. When you create a service account from **Directory** > **Users**, authentik creates an app password for the account and shows it once in the confirmation screen.
- **API tokens** authenticate to the authentik API with HTTP Bearer authentication. Use API tokens for scripts, CI/CD jobs, and other automation that calls `/api/v3/` endpoints.

A service account is still a user object for authorization purposes. You can add it to groups, add it to roles, assign object permissions, and include or exclude it from application access through bindings and policies.

## Limitations

Service accounts have certain limitations compared to regular user accounts:
Service accounts differ from regular users in the following ways:

1. Cannot log in through the UI.
2. Cannot have a password (they use tokens exclusively).
3. Cannot participate in multi-factor authentication flows.
4. Cannot be used for interactive sessions that require human interaction.
5. Cannot have permissions assigned directly if they are internal service accounts.
6. Cannot change their own password or manage their own account settings.
7. Are subject to token expiration policies that differ from regular user accounts.
- They are intended for non-interactive use and cannot access the authentik user or Admin interfaces. If a service account authenticates in a browser, authentik redirects it to the brand's default application when one is configured; otherwise access to the interface is denied.
- They do not have a usable account password. Use an app password or API token instead.
- They cannot complete interactive MFA setup or other human-driven account settings flows.
- They should not be used to represent a person. Create a regular internal or external user for human access.
- Internal service accounts are managed by authentik and cannot be modified directly.

## Creating a Service Account
## Create a service account

To create a service account:

1. In the authentik **Admin interface**, navigate to **Directory** > **Users**.
2. Click the **Create Service Account** button.
3. Configure the following settings:
- **Username**: The user's primary identifier (150 characters or fewer).
- **Create Group**: Enabling this toggle will create a group named after the user, with the user as a member.
- **Expiring**: If selected, the token will expire and be automatically rotated upon expiration.
- **Expires on**: Sets the expiration date (defaults to 1 year from the creation date).
4. Click **Create Service Account**.
1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Directory** > **Users**.
3. Click **Create a service account**.
4. Configure the following settings:
- **Username**: the primary identifier for the service account. This value is used as the username for app-password authentication.
- **Create group**: creates a group with the same name as the service account and adds the service account to it. This can be useful when you want to grant access through group membership.
- **Expiring**: controls whether the generated app password expires.
- **Expires on**: sets the expiration date for the generated app password. If no date is provided, the default is 360 days.
5. Click **Create**.
6. Copy the generated username and password from the confirmation screen and store the password in a secure secret store.

After creating the service account, you'll see a confirmation screen that shows the username and generated password (token). Make sure to copy this information somewhere secure as you'll need it for authentication.
:::warning Store the generated password securely
The generated password is the service account's initial app password. Treat it like any other secret. Anyone with this value can authenticate as the service account anywhere that app passwords are accepted.
:::

## Token Properties
## Manage service account tokens

Service account tokens have the following properties:
Service account tokens are managed from **Directory** > **Tokens and App passwords**.

- **Expiration**: By default, tokens expire after 360 days but can be configured to be non-expiring.
- **Custom Expiration Date**: You can set a specific expiration date when creating the service account.
- **Revocation**: Tokens can be revoked at any time by deleting them or generating new ones.
- **Automatic Rotation**: When a token expires, it's automatically rotated to maintain security.
### Create another app password

## Managing Service Account Tokens
Create an app password when an integration needs username/password-style authentication, for example an LDAP bind password.

Tokens for service accounts are managed through the authentik Admin interface:
1. Navigate to **Directory** > **Tokens and App passwords**.
2. Click **Create**.
3. Enter a unique **Identifier**.
4. Select the service account in the **User** field.
5. Set **Intent** to **App password**.
6. Configure whether the token expires and, if needed, set **Expires on**.
7. Click **Create** and copy the generated value.

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Directory** > **Tokens and App passwords**.
Here you can view, create, copy, delete, and manage tokens.
### Create an API token

Create an API token when automation needs to call the authentik API.

1. Navigate to **Directory** > **Tokens and App passwords**.
2. Click **Create**.
3. Enter a unique **Identifier**.
4. Select the service account in the **User** field.
5. Set **Intent** to **API Token**.
6. Click **Create** and copy the generated value.

Use the token as a Bearer token in the `Authorization` header when calling the authentik API:

### Creating New Tokens
```http
Authorization: Bearer <token>
```

To create a new token for a service account:
### Rotate or revoke tokens

1. Click **Create**.
2. Set the identifier for your token.
3. In the **User** dropdown list, select your service account.
4. For **Intent**, choose one of the following:
- **API Token**: Used to access the API programmatically (30-minute default lifespan).
- **App password**: Used for logging in using a flow executor (1-year default lifespan).
5. Click **Create** to generate the new token.
- To view a token value, use the copy action in **Directory** > **Tokens and App passwords**. Access to token values is controlled by the `View token's key` permission.
- To revoke a token, delete it.
- To rotate an app password, create a replacement token, update the external system, and then delete the old token.
- Expiring app passwords become invalid when they expire. Expiring API tokens are rotated by authentik.

### Managing and Regenerating Tokens
## Permissions and access control

- To copy a token's value, use the copy button under the **Actions** column.
- To delete a token, select it from the list and click the **Delete** button.
- To regenerate a token, delete the existing token and create a new one with the same settings, ensuring you select the same username under the **User** dropdown list.
Service accounts start with no special access beyond normal authentication. Grant only the permissions required for the integration.

## Authentication with Service Accounts
You can grant access in the same ways as regular users:

Service accounts authenticate using [HTTP Basic Authentication](https://datatracker.ietf.org/doc/html/rfc7617). The username and password (token) generated during account creation are used as credentials.
- Add the service account to a group and grant permissions to that group.
- Add the service account to a role and grant global or object permissions to that role.
- Grant object permissions directly to the service account when access should not be shared with other accounts.
- Use application [bindings](../add-secure-apps/applications/manage_apps.mdx#use-bindings-to-control-access) or policies to restrict which applications the service account can access.

## Permissions and Access Control
For more information about assigning permissions, see [Manage permissions](../users-sources/access-control/manage_permissions.md).

Like regular user accounts, with service accounts you can assign [permissions and use RBAC](../users-sources/access-control/manage_permissions.md).
### Example: LDAP search account

1. Assign the service account to groups to inherit group permissions.
2. Grant specific permissions directly to the service account.
3. Restrict the service account to specific applications or resources.
LDAP clients often need a bind account that can search the LDAP directory. In this case:

We recommend following the principle of least privilege and only grant service accounts the permissions they absolutely need.
1. Create a service account, such as `ldapservice`.
2. Store the generated app password in the LDAP client configuration.
3. Create a role for LDAP search access.
4. Add the service account to that role.
5. On the LDAP provider, assign the role the **Search full LDAP directory** object permission.

## Common Use Cases
For the full LDAP setup, see [Create an LDAP provider](../add-secure-apps/providers/ldap/create-ldap-provider.mdx#create-a-service-account).

### Integration with External Systems
### Example: API automation account

Service accounts are commonly used for:
Automation that manages authentik objects should use an API token for a dedicated service account.

1. **LDAP Authentication**: Systems like SSSD, QNAP NAS, and other LDAP clients often use service accounts to bind to authentik's LDAP provider.
2. **Directory Synchronization**: Tools that sync users and groups between authentik and other systems.
3. **API Automation**: For scripts, CI/CD pipelines, or other systems that need to interact with authentik's API.
1. Create a service account for the automation, such as `ci-authentik-admin`.
2. Create an API token for that service account.
3. Grant the service account only the permissions required by the automation. For example, a script that rotates application certificates should receive certificate-related permissions, not full administrator access.
4. Store the API token in your CI/CD or secret management system and send it as `Authorization: Bearer <token>`.

## Security Best Practices
## Security best practices

When using service accounts, follow these security practices:

1. **Least Privilege**: Grant service accounts only the permissions they need.
2. **Secure Storage**: Store service account tokens securely in encrypted storage, environment variables, or secret management systems.
3. **Token Rotation**: Rotate tokens periodically for sensitive integrations.
4. **Use Expiration**: Set appropriate token expiration dates for your use case.
5. **Audit Usage**: Monitor service account activity for unexpected behavior.
- **Use one service account per integration**. Avoid sharing one account across unrelated systems so audit events and token rotation remain clear.
- **Grant least privilege**. Assign only the global permissions, object permissions, groups, roles, or application access that the integration needs.
- **Prefer expiring tokens** for credentials stored outside authentik, and rotate long-lived secrets on a regular schedule.
- **Store tokens securely** in a secret manager, encrypted environment variable store, or equivalent system.
- **Disable or delete unused accounts**. If an integration is retired, delete its tokens and deactivate or remove the service account.
- **Audit usage** by reviewing events for unexpected logins, API calls, or token access.
Loading