From c4dcb421d933a9389bead52eab288c3993a4294f Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Thu, 12 Jun 2025 14:25:15 +0200 Subject: [PATCH 1/5] Initial service account docs --- docs/admin/access_control/index.mdx | 1 + .../admin/access_control/service_accounts.mdx | 158 ++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 docs/admin/access_control/service_accounts.mdx diff --git a/docs/admin/access_control/index.mdx b/docs/admin/access_control/index.mdx index 87ffa9d59..7dd683af3 100644 --- a/docs/admin/access_control/index.mdx +++ b/docs/admin/access_control/index.mdx @@ -42,6 +42,7 @@ You can read about the specific permission types available for each RBAC-enabled - [Batch Changes](/admin/access_control/batch_changes) - [Ownership](/admin/access_control/ownership) +- [Service accounts](/admin/access_control/service_accounts) ### Deleting a role diff --git a/docs/admin/access_control/service_accounts.mdx b/docs/admin/access_control/service_accounts.mdx new file mode 100644 index 000000000..6c69cab55 --- /dev/null +++ b/docs/admin/access_control/service_accounts.mdx @@ -0,0 +1,158 @@ +# Service accounts + + + Supported on [Enterprise](/pricing/enterprise) plans. + + Available via the Web app. + + + +Service accounts in Sourcegraph are special types of accounts designed for automated tasks and integrations. Unlike regular user accounts, service accounts cannot sign into Sourcegraph directly and can only be used through their associated access tokens. + +## What are service accounts? + +Service accounts are non-human accounts that enable: + +- **Automated operations**: Run scripts, CI/CD pipelines, or other automated processes that interact with Sourcegraph +- **API integrations**: Build applications that need to access Sourcegraph programmatically +- **Secure token management**: Create dedicated tokens for specific purposes without using personal user accounts + +Key characteristics of service accounts: + +- **Cannot sign in**: Service accounts cannot access the Sourcegraph web interface directly +- **Token-based access only**: All operations must be performed using access tokens +- **No user seat usage**: Service accounts don't count toward your user seat limit and won't affect billing +- **RBAC compatible**: Can be assigned custom roles and permissions like regular users + +## Why use service accounts? + +Service accounts provide several advantages over using personal user accounts for automated tasks: + +### Security benefits +- **Isolated permissions**: Scope access to only what's needed for specific automation tasks +- **No human login**: Eliminates risk of compromised human credentials affecting automation +- **Audit trail**: Clearly identify automated vs. human actions in logs and audit trails + +### Management benefits +- **Independent lifecycle**: Service accounts persist even if team members leave or change roles +- **Dedicated purpose**: Each service account can be tailored for specific use cases +- **No billing impact**: Unlimited service accounts without affecting user seat counts + +### Common use cases +- **CI/CD pipelines**: Automate code analysis, search operations, or batch changes +- **Monitoring and alerting**: Create dashboards or alerts based on Sourcegraph data +- **Data integration**: Sync repository data with external systems +- **Batch operations**: Perform bulk operations across multiple repositories + +## Creating service accounts + +To create a service account: + +1. Navigate to **Site admin > Users & auth > Service accounts** +2. Click **+ Create service account** +3. Provide a descriptive name for the service account +4. Optionally add a description explaining its purpose +5. Click **Create** + +> NOTE: Only site administrators can create and manage service accounts. + +## Managing access tokens + +Once you've created a service account, you'll need to create access tokens for it to perform operations: + +### Creating access tokens + +1. From the service accounts list, click on the service account you want to create a token for +2. In the **Access tokens** section, click **+ Generate new token** +3. Provide a descriptive name for the token +4. Set an expiration date (recommended for security) +5. Click **Generate token** +6. **Important**: Copy the token immediately - it will not be shown again + +### Token security best practices + +- **Use descriptive names**: Clearly identify what each token is used for +- **Set expiration dates**: Regularly rotate tokens by setting reasonable expiration periods +- **Limit scope**: Assign minimal necessary permissions to the service account +- **Secure storage**: Store tokens securely in your automation systems (environment variables, secret managers) +- **Monitor usage**: Review access logs to ensure tokens are being used appropriately + +## Permissions and role-based access control + +Service accounts can be assigned custom roles just like regular users, enabling fine-grained permission control. + +### Assigning roles + +1. Navigate to **Site admin > Users & auth > Users** +2. Find the service account in the user list +3. Click the triple dots to open the context menu +4. Select **Manage roles** +5. Assign or remove roles as needed +6. Click **Update** to save changes + +### Permission scoping + +Use RBAC to limit service account permissions: + +- **Batch Changes**: Control whether the service account can create, modify, or execute batch changes +- **Repository access**: Combine with [repository permissions](/admin/permissions/) to limit which repositories the service account can access +- **Custom roles**: Create specific roles tailored to your automation needs + +Example role configurations: +- **CI/CD Service**: Read-only access to repositories, can trigger searches +- **Batch Change Automation**: Can create and execute batch changes on specific repositories +- **Monitoring Service**: Read-only access for generating reports and dashboards + +## API usage with service accounts + +Service accounts work with all Sourcegraph APIs using their access tokens: + +### GraphQL API +```bash +curl -H "Authorization: Bearer " \ + -H "Content-Type: application/json" \ + -d '{"query": "{ currentUser { username } }"}' \ + https://your-sourcegraph-instance.com/.api/graphql +``` + +### REST APIs +```bash +curl -H "Authorization: Bearer " \ + https://your-sourcegraph-instance.com/.api/search/stream?q=test +``` + +## Monitoring service account activity + +Track service account usage through: + +- **Audit logs**: All service account actions are logged with clear identification +- **Security event logs**: Monitor for unusual access patterns or failures +- **Access token usage**: Review when tokens were last used and from where + +## Troubleshooting + +### Common issues + +**Service account token not working** +- Verify the token hasn't expired +- Check that the service account has the necessary permissions +- Ensure the token is being passed correctly in API requests + +**Permission denied errors** +- Review the service account's assigned roles +- Check repository-level permissions if accessing specific repositories +- Verify the required permissions are included in the service account's roles + +**Token generation fails** +- Ensure you have site administrator privileges +- Check that the service account exists and is active +- Verify there are no conflicting token names + +## Best practices + +1. **Use meaningful names**: Name service accounts and tokens descriptively (e.g., `ci-batch-changes`, `monitoring-dashboard`) +2. **Regular token rotation**: Set expiration dates and rotate tokens periodically +3. **Minimal permissions**: Grant only the permissions necessary for each use case +4. **Monitor and audit**: Regularly review service account activity and permissions +5. **Document usage**: Keep records of what each service account is used for and by which systems +6. **Secure token storage**: Never commit tokens to code repositories; use secure secret management From 09175ac2d1ad8b9e8ac7518cf41d3ef6cc4676f9 Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Mon, 23 Jun 2025 16:26:15 +0200 Subject: [PATCH 2/5] Update service account docs --- .../admin/access_control/service_accounts.mdx | 168 ++++-------------- 1 file changed, 30 insertions(+), 138 deletions(-) diff --git a/docs/admin/access_control/service_accounts.mdx b/docs/admin/access_control/service_accounts.mdx index 6c69cab55..546a0639e 100644 --- a/docs/admin/access_control/service_accounts.mdx +++ b/docs/admin/access_control/service_accounts.mdx @@ -1,158 +1,50 @@ -# Service accounts +# Service Accounts - - Supported on [Enterprise](/pricing/enterprise) plans. - - Available via the Web app. - - +Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password and cannot access the Sourcegraph UI. They are specifically intended for automated workflows, CI/CD pipelines, scripts, and other non-human access patterns. Service accounts also don't count towards the user limit and won't be part of any billing cycles. -Service accounts in Sourcegraph are special types of accounts designed for automated tasks and integrations. Unlike regular user accounts, service accounts cannot sign into Sourcegraph directly and can only be used through their associated access tokens. +## Creating Service Accounts -## What are service accounts? +Service accounts are created like regular user accounts, but with a few key differences. -Service accounts are non-human accounts that enable: +- Go to **Site admin** → **Users & auth** → **Users** +- Click **Create User** +- Enter a descriptive **Username** (e.g., `ci-automation`, `api-integration`) +- Check the **Service account** checkbox +- Click **Create service account** -- **Automated operations**: Run scripts, CI/CD pipelines, or other automated processes that interact with Sourcegraph -- **API integrations**: Build applications that need to access Sourcegraph programmatically -- **Secure token management**: Create dedicated tokens for specific purposes without using personal user accounts +You'll be presented with some next steps you might want to take, like creating an access token, managing and assigning roles, and managing repository permissions. -Key characteristics of service accounts: +- Service accounts are automatically assigned the "Service Account" system role +- They appear in the user list with "Service account" type designation -- **Cannot sign in**: Service accounts cannot access the Sourcegraph web interface directly -- **Token-based access only**: All operations must be performed using access tokens -- **No user seat usage**: Service accounts don't count toward your user seat limit and won't affect billing -- **RBAC compatible**: Can be assigned custom roles and permissions like regular users +## Managing Access Tokens -## Why use service accounts? +Service accounts authenticate using access tokens rather than passwords. For detailed information about creating, managing, and using access tokens, see: -Service accounts provide several advantages over using personal user accounts for automated tasks: +- [Creating an access token](/cli/how-tos/creating_an_access_token) +- [Managing access tokens](/cli/how-tos/managing_access_tokens) +- [Revoking an access token](/cli/how-tos/revoking_an_access_token) -### Security benefits -- **Isolated permissions**: Scope access to only what's needed for specific automation tasks -- **No human login**: Eliminates risk of compromised human credentials affecting automation -- **Audit trail**: Clearly identify automated vs. human actions in logs and audit trails +Use service account access tokens to access Sourcegraph's [GraphQL API](/api/graphql). -### Management benefits -- **Independent lifecycle**: Service accounts persist even if team members leave or change roles -- **Dedicated purpose**: Each service account can be tailored for specific use cases -- **No billing impact**: Unlimited service accounts without affecting user seat counts +## Role-Based Access Control (RBAC) -### Common use cases -- **CI/CD pipelines**: Automate code analysis, search operations, or batch changes -- **Monitoring and alerting**: Create dashboards or alerts based on Sourcegraph data -- **Data integration**: Sync repository data with external systems -- **Batch operations**: Perform bulk operations across multiple repositories +Service accounts integrate with Sourcegraph's [role-based access control](/admin/access_control) to provide fine-grained permission control. -## Creating service accounts +### System Roles -To create a service account: +Service accounts are automatically assigned the **Service Account** system role, which provides basic API access permissions and standard search capabilities. The **Service Account** system role is applied to all service accounts and can be used to provide service accounts with a default set of permissions. For more specialized service accounts, it is recommended to create custom roles and assign them to service accounts as needed. -1. Navigate to **Site admin > Users & auth > Service accounts** -2. Click **+ Create service account** -3. Provide a descriptive name for the service account -4. Optionally add a description explaining its purpose -5. Click **Create** +### Managing Roles -> NOTE: Only site administrators can create and manage service accounts. +Administrators can assign additional roles to service accounts through the user management interface. For detailed information on managing roles and permissions, see: -## Managing access tokens +- [Managing roles and permissions](/admin/access_control#managing-roles-and-permissions) +- [Managing user roles](/admin/access_control#managing-user-roles) +- [Creating custom roles](/admin/access_control#creating-a-new-role-and-assigning-it-permissions) -Once you've created a service account, you'll need to create access tokens for it to perform operations: +## Repository Permissions -### Creating access tokens +Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation. -1. From the service accounts list, click on the service account you want to create a token for -2. In the **Access tokens** section, click **+ Generate new token** -3. Provide a descriptive name for the token -4. Set an expiration date (recommended for security) -5. Click **Generate token** -6. **Important**: Copy the token immediately - it will not be shown again - -### Token security best practices - -- **Use descriptive names**: Clearly identify what each token is used for -- **Set expiration dates**: Regularly rotate tokens by setting reasonable expiration periods -- **Limit scope**: Assign minimal necessary permissions to the service account -- **Secure storage**: Store tokens securely in your automation systems (environment variables, secret managers) -- **Monitor usage**: Review access logs to ensure tokens are being used appropriately - -## Permissions and role-based access control - -Service accounts can be assigned custom roles just like regular users, enabling fine-grained permission control. - -### Assigning roles - -1. Navigate to **Site admin > Users & auth > Users** -2. Find the service account in the user list -3. Click the triple dots to open the context menu -4. Select **Manage roles** -5. Assign or remove roles as needed -6. Click **Update** to save changes - -### Permission scoping - -Use RBAC to limit service account permissions: - -- **Batch Changes**: Control whether the service account can create, modify, or execute batch changes -- **Repository access**: Combine with [repository permissions](/admin/permissions/) to limit which repositories the service account can access -- **Custom roles**: Create specific roles tailored to your automation needs - -Example role configurations: -- **CI/CD Service**: Read-only access to repositories, can trigger searches -- **Batch Change Automation**: Can create and execute batch changes on specific repositories -- **Monitoring Service**: Read-only access for generating reports and dashboards - -## API usage with service accounts - -Service accounts work with all Sourcegraph APIs using their access tokens: - -### GraphQL API -```bash -curl -H "Authorization: Bearer " \ - -H "Content-Type: application/json" \ - -d '{"query": "{ currentUser { username } }"}' \ - https://your-sourcegraph-instance.com/.api/graphql -``` - -### REST APIs -```bash -curl -H "Authorization: Bearer " \ - https://your-sourcegraph-instance.com/.api/search/stream?q=test -``` - -## Monitoring service account activity - -Track service account usage through: - -- **Audit logs**: All service account actions are logged with clear identification -- **Security event logs**: Monitor for unusual access patterns or failures -- **Access token usage**: Review when tokens were last used and from where - -## Troubleshooting - -### Common issues - -**Service account token not working** -- Verify the token hasn't expired -- Check that the service account has the necessary permissions -- Ensure the token is being passed correctly in API requests - -**Permission denied errors** -- Review the service account's assigned roles -- Check repository-level permissions if accessing specific repositories -- Verify the required permissions are included in the service account's roles - -**Token generation fails** -- Ensure you have site administrator privileges -- Check that the service account exists and is active -- Verify there are no conflicting token names - -## Best practices - -1. **Use meaningful names**: Name service accounts and tokens descriptively (e.g., `ci-batch-changes`, `monitoring-dashboard`) -2. **Regular token rotation**: Set expiration dates and rotate tokens periodically -3. **Minimal permissions**: Grant only the permissions necessary for each use case -4. **Monitor and audit**: Regularly review service account activity and permissions -5. **Document usage**: Keep records of what each service account is used for and by which systems -6. **Secure token storage**: Never commit tokens to code repositories; use secure secret management +Service accounts cannot have external service accounts. If service accounts need access to private repositories, they must explicitly be granted access to those repositories. This can be done from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). From 3dbe3f55b425b9817aaf10e54a1eb7f37d0b4aee Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Mon, 23 Jun 2025 16:39:34 +0200 Subject: [PATCH 3/5] Link to service accounts from a few more places --- docs/admin/auth/index.mdx | 4 ++++ docs/api/graphql/index.mdx | 2 ++ 2 files changed, 6 insertions(+) diff --git a/docs/admin/auth/index.mdx b/docs/admin/auth/index.mdx index 7acb7390a..d7abfa0c8 100644 --- a/docs/admin/auth/index.mdx +++ b/docs/admin/auth/index.mdx @@ -29,6 +29,10 @@ The following methods are supported for sign up and sign in: The authentication providers are configured in the [`auth.providers`](/admin/config/site_config#authentication-providers) site configuration option. +## Programmatic authentication + +For automated systems, CI/CD pipelines, and API integrations that need to authenticate without human interaction, use [service accounts](/admin/access_control/service_accounts). Service accounts are specialized user accounts designed for automation that authenticate using access tokens rather than passwords. + ## Login form configuration To configure the presentation of the login form, see the [login form configuration page](/admin/auth/login_form). diff --git a/docs/api/graphql/index.mdx b/docs/api/graphql/index.mdx index 89da31f8d..1b8e88e0b 100644 --- a/docs/api/graphql/index.mdx +++ b/docs/api/graphql/index.mdx @@ -32,6 +32,8 @@ You should see a response like this: { "data": { "currentUser": { "username": "YOUR_USERNAME" } } } ``` +For automated scripts, CI/CD pipelines, and production integrations, use [service accounts](/admin/access_control/service_accounts) instead of personal access tokens. Service accounts are designed specifically for programmatic API access and provide better security and audit capabilities. + ## Documentation & tooling ### API Console From 28aef6a645ba877bf74e4e52ba098e583d70f2e6 Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Mon, 23 Jun 2025 17:08:14 +0200 Subject: [PATCH 4/5] PR comments --- docs/admin/access_control/service_accounts.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/admin/access_control/service_accounts.mdx b/docs/admin/access_control/service_accounts.mdx index 546a0639e..1bef83b56 100644 --- a/docs/admin/access_control/service_accounts.mdx +++ b/docs/admin/access_control/service_accounts.mdx @@ -1,6 +1,6 @@ # Service Accounts -Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password and cannot access the Sourcegraph UI. They are specifically intended for automated workflows, CI/CD pipelines, scripts, and other non-human access patterns. Service accounts also don't count towards the user limit and won't be part of any billing cycles. +Service accounts are specialized user accounts designed for automation, API integrations, and programmatic access to Sourcegraph, as opposed to using access tokens from regular users. Unlike regular user accounts, service accounts don't require an email address or password, cannot access the Sourcegraph UI, don't count towards a license's user limit and won't be part of any billing cycles. ## Creating Service Accounts @@ -8,7 +8,7 @@ Service accounts are created like regular user accounts, but with a few key diff - Go to **Site admin** → **Users & auth** → **Users** - Click **Create User** -- Enter a descriptive **Username** (e.g., `ci-automation`, `api-integration`) +- Enter a descriptive **Username** (e.g., `ci-bot-scip-uploads`, `api-search-jobs`) - Check the **Service account** checkbox - Click **Create service account** @@ -16,6 +16,7 @@ You'll be presented with some next steps you might want to take, like creating a - Service accounts are automatically assigned the "Service Account" system role - They appear in the user list with "Service account" type designation +- By default, service accounts can only access public and unrestricted repositories ## Managing Access Tokens @@ -47,4 +48,4 @@ Administrators can assign additional roles to service accounts through the user Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation. -Service accounts cannot have external service accounts. If service accounts need access to private repositories, they must explicitly be granted access to those repositories. This can be done from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). +Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). From 9b447ad56cdb50ba1e254c3ca38e4114e0fe6b60 Mon Sep 17 00:00:00 2001 From: Petri-Johan Last Date: Mon, 23 Jun 2025 17:12:13 +0200 Subject: [PATCH 5/5] Add a note about unrestricted access --- docs/admin/access_control/service_accounts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/access_control/service_accounts.mdx b/docs/admin/access_control/service_accounts.mdx index 1bef83b56..70e309023 100644 --- a/docs/admin/access_control/service_accounts.mdx +++ b/docs/admin/access_control/service_accounts.mdx @@ -48,4 +48,4 @@ Administrators can assign additional roles to service accounts through the user Service accounts respect repository permissions and access controls. For comprehensive information about repository permissions, see the [Repository permissions](/admin/permissions) documentation. -Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). +Service accounts by default can only access public and unrestricted repositories in Sourcegraph. You may explicitly grant fine-grained access to private repositories from the service account's user settings page, under the **Repo permissions** tab, or via [the GraphQL API](/admin/permissions/api#explicit-permissions-api). In the **Repo permissions** tab, you can also grant service accounts access to all current and future repositories on Sourcegraph, regardless of their visibility, which is useful for service accounts that need to do things like perform search jobs, but admins should take care to ensure that the access tokens for these accounts are not shared with unauthorized users. \ No newline at end of file