Skip to content

docs: improve auth methods docs and make clear different types of auth available #1754

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

Open
enriquegh wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: improve auth methods docs and make clear different types of auth available #1754

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 12 additions & 0 deletions docs/admin/service-accounts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

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.

## Choosing an authentication method

Use this quick guide if you're deciding between a service account, an OAuth App, and an access token:

| Option | Best for | Identity used for requests | Notes |
| ------ | -------- | -------------------------- | ----- |
| Service account | Automation, CI/CD, server-to-server integrations | A dedicated machine identity | Supports traditional access tokens and M2M credentials for `grant_type=client_credentials` |
| OAuth App | Applications acting on behalf of signed-in users | Each end user | Best when repository access should follow the permissions of the person using the app |
| Access token | Quick tests, CLI usage, or one-off scripts tied to a single user | The user or service account that created the token | Simpler to set up, but not ideal for multi-user integrations |

If your integration should act as one non-human identity, use a service account. If it should act on behalf of each signed-in user, use an [OAuth App](/admin/oauth-apps). If you just need a simple token for a single user or service account, use an [access token](/cli/how-tos/creating-an-access-token).

## Creating Service Accounts

Service accounts are created like regular user accounts, but with a few key differences.
Expand Down
19 changes: 16 additions & 3 deletions docs/api/mcp/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,11 +173,24 @@ To restrict MCP to a subset of users:
See [Access control](/admin/access-control) for more about managing roles and permissions.

<Callout type="info">
MCP access control is separate from [repository permissions](/admin/permissions/).
Users can only read data from repositories they are already allowed to access
in Sourcegraph.
MCP access control is separate from [repository
permissions](/admin/permissions/). Users can only read data from
repositories they are already allowed to access in Sourcegraph.
</Callout>

## Troubleshooting

Most MCP connection issues come from OAuth or access-control configuration rather than the MCP endpoint itself.

| If you see | Likely cause | What to check |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `invalid_scope` during OAuth sign-in | The client requested the wrong scope for MCP | MCP-only connections should use the `mcp` scope. If the integration also needs GraphQL or other APIs, create a separate [OAuth App](/admin/oauth-apps) with the broader scopes you need instead of reusing an MCP-only registration. |
| `redirect_uri_mismatch` or a token exchange failure after browser auth | The OAuth client is missing the callback URL expected by the MCP client | Register the exact redirect URI your client uses. For the `mcp-remote` fallback shown above, add `http://localhost:3334/oauth/callback` to the OAuth app. |
| `/.auth/idp/oauth/register` returns `404 not found` | Dynamic Client Registration is disabled | Confirm `mcp.enabled` is `true` and `auth.idpDynamicClientRegistrationEnabled` is `true`. If you want MCP available without DCR, use the manual OAuth setup instead. |
| The browser opens for sign-in, but the connection never completes or loops back to login | Your Sourcegraph browser session expired before the OAuth flow completed | Sign in to Sourcegraph in the same browser profile first, then retry the MCP connection. This is especially common when the OAuth window opens in a browser profile that is not already signed in. |
| Users must sign in again frequently even though the integration previously worked | The client is not refreshing tokens correctly | OAuth access tokens are short-lived. Make sure the client stores the newest `refresh_token` returned on each refresh, because refresh tokens are one-time use. For service-account M2M flows, request a new access token when the current one expires because no refresh token is returned. |
| `403 forbidden` from `/.api/mcp` | The user authenticated successfully but does not have MCP access | Check that MCP is enabled, the user has the `MCP#ACCESS` permission, and the user already has access to the repositories they are trying to read. |

## Available Tools

<Callout type="info">
Expand Down
6 changes: 6 additions & 0 deletions docs/cli/how-tos/managing-access-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@ The `auth.accessTokens` setting in Sourcegraph's site configuration allows admin
}
```

<Callout type="note">
`auth.accessTokens` only controls Sourcegraph access tokens. It does not disable
[OAuth Apps](/admin/oauth-apps), service-account M2M credentials, or MCP
Dynamic Client Registration.
</Callout>

## Access token creation

The `allow` property permits or restricts the use of access tokens. It can be assigned one of three values:
Expand Down