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..70e309023 --- /dev/null +++ b/docs/admin/access_control/service_accounts.mdx @@ -0,0 +1,51 @@ +# 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, 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 + +Service accounts are created like regular user accounts, but with a few key differences. + +- Go to **Site admin** → **Users & auth** → **Users** +- Click **Create User** +- Enter a descriptive **Username** (e.g., `ci-bot-scip-uploads`, `api-search-jobs`) +- Check the **Service account** checkbox +- Click **Create service account** + +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. + +- 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 + +Service accounts authenticate using access tokens rather than passwords. For detailed information about creating, managing, and using access tokens, see: + +- [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) + +Use service account access tokens to access Sourcegraph's [GraphQL API](/api/graphql). + +## Role-Based Access Control (RBAC) + +Service accounts integrate with Sourcegraph's [role-based access control](/admin/access_control) to provide fine-grained permission control. + +### System Roles + +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. + +### Managing Roles + +Administrators can assign additional roles to service accounts through the user management interface. For detailed information on managing roles and permissions, see: + +- [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) + +## Repository Permissions + +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). 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 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