From f0e58a6f49631da7c0f4dc3c8fd33e0ccf671990 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Tue, 1 Apr 2025 17:37:11 -0400 Subject: [PATCH] website/docs: sys-mgmt: service accounts (#13722) * website/docs: ops: service accounts * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Update website/docs/sys-mgmt/service-accounts.md Co-authored-by: Tana M Berry Signed-off-by: Dominic R * Dewi's suggestions --------- Signed-off-by: Dominic R Co-authored-by: Tana M Berry --- website/docs/sys-mgmt/service-accounts.md | 110 ++++++++++++++++++++++ website/sidebars.js | 1 + 2 files changed, 111 insertions(+) create mode 100644 website/docs/sys-mgmt/service-accounts.md diff --git a/website/docs/sys-mgmt/service-accounts.md b/website/docs/sys-mgmt/service-accounts.md new file mode 100644 index 0000000000..0e64ceb3cd --- /dev/null +++ b/website/docs/sys-mgmt/service-accounts.md @@ -0,0 +1,110 @@ +--- +title: Service Accounts +sidebar_label: Service Accounts +--- + +# 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. + +## Types of Service Accounts + +authentik distinguishes between two 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. + +## Limitations + +Service accounts have certain limitations compared to regular user accounts: + +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. + +## Creating 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**. + +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. + +## Token Properties + +Service account tokens have the following properties: + +- **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. + +## Managing Service Account Tokens + +Tokens for service accounts are managed through the authentik Admin interface: + +1. Log in to the Admin interface and navigate to **Directory** > **Tokens and App passwords**. +2. Here you can view, create, copy, delete, and manage tokens. + +### Creating New Tokens + +To create a new token for a service account: + +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. + +### Managing and Regenerating Tokens + +- 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. + +## Authentication with Service Accounts + +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. + +## Permissions and Access Control + +Like regular user accounts, with service accounts you can assign [permissions and use RBAC](../users-sources/access-control/manage_permissions). + +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. + +We recommend following the principle of least privilege and only grant service accounts the permissions they absolutely need. + +## Common Use Cases + +### Integration with External Systems + +Service accounts are commonly used for: + +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. + +## 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. diff --git a/website/sidebars.js b/website/sidebars.js index 2b29412d86..08f4132321 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -608,6 +608,7 @@ export default { }, "sys-mgmt/certificates", "sys-mgmt/settings", + "sys-mgmt/service-accounts", ], }, {