From 59d510b6b6066ec984640ede67aea153862ad524 Mon Sep 17 00:00:00 2001 From: Enrique Gonzalez Date: Fri, 10 Apr 2026 08:06:24 -0700 Subject: [PATCH] docs: add clarification between oauth apps and M2M credentials --- docs/admin/oauth-apps.mdx | 26 ++++++++++++++++++++++++-- docs/admin/service-accounts.mdx | 16 ++++++++++++++-- 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/docs/admin/oauth-apps.mdx b/docs/admin/oauth-apps.mdx index b5cc061da..0b5e3998f 100644 --- a/docs/admin/oauth-apps.mdx +++ b/docs/admin/oauth-apps.mdx @@ -11,6 +11,23 @@ This makes OAuth the preferred choice for any multi-user integration like browse OAuth Apps are in compliance with standards including [RFC 6749](https://tools.ietf.org/html/rfc6749), [RFC 7636 (PKCE)](https://tools.ietf.org/html/rfc7636), and [RFC 8628 (Device Authorization Grant)](https://tools.ietf.org/html/rfc8628). + + OAuth Apps and service-account M2M credentials both use Sourcegraph's OAuth + server, but they are different client types for different jobs: + + - OAuth Apps created in **Site admin > OAuth clients** are for apps acting on + behalf of a user. They support `authorization_code` and + `refresh_token`, and public clients also support the device authorization + flow. + - Service-account M2M credentials are separate OAuth clients that are bound to + a service account. They are the only clients that support + `grant_type=client_credentials`. + + If your OpenID Connect discovery document lists `client_credentials`, that + means the Sourcegraph OAuth server supports that grant overall. It does not + mean every OAuth client created in the UI can use it. + + Consider using **M2M (client-credentials) service-account tokens** or traditional [access tokens](/cli/how-tos/creating-an-access-token) for server-to-server communication, automated scripts, CI/CD pipelines, or single-user applications that do not require per-user permission checks. See [service accounts](/admin/service-accounts#m2m-oauth-credentials-client-credentials-flow) for details. ## Creating an OAuth App @@ -61,7 +78,7 @@ Public clients: Private clients can securely store client secrets: - **Server-side web applications** -- **Backend services** +- **Backend services that act on behalf of signed-in users** - **Secure server environments** Private clients: @@ -69,6 +86,7 @@ Private clients: - Receive both client ID and client secret - Can use the standard authorization code flow (PKCE strongly recommended) - Allow client authentication with a secret and server-side code exchange +- Still act on behalf of a user, not as a standalone machine identity ## Available Scopes @@ -103,6 +121,10 @@ When creating an OAuth app, select the minimum scopes necessary for your applica ## OAuth Flow Examples +The first three flows below are for OAuth Apps created in **Site admin > OAuth +clients**. The `client_credentials` example is included for completeness, but +it only works with M2M credentials created for a service account. + 1. **Authorization Request**: Redirect users to Sourcegraph's authorization endpoint: @@ -260,7 +282,7 @@ curl -X POST https://sourcegraph.example.com/.auth/idp/oauth/token \ -The client credentials flow is designed for server-to-server authentication without user interaction. Service accounts can create M2M (machine-to-machine) credentials that use this flow. You can create M2M credentials in the service account settings under **Access tokens > M2M credentials**. +The client credentials flow is designed for server-to-server authentication without user interaction. It is not available for OAuth Apps created in **Site admin > OAuth clients**. Instead, service accounts create separate M2M (machine-to-machine) credentials that use this flow. You can create M2M credentials in the service account settings under **Access tokens > M2M credentials**. 1. **Token Request** (no user interaction required): diff --git a/docs/admin/service-accounts.mdx b/docs/admin/service-accounts.mdx index 022a2188f..c5625b599 100644 --- a/docs/admin/service-accounts.mdx +++ b/docs/admin/service-accounts.mdx @@ -26,6 +26,14 @@ You'll be presented with some next steps you might want to take, like creating a Service accounts can authenticate using either traditional access tokens or M2M (machine-to-machine) OAuth credentials. + + M2M credentials are not the same thing as OAuth Apps created in + **Site admin > OAuth clients**. OAuth Apps are for flows where an application + acts on behalf of a user. M2M credentials are separate OAuth clients that are + bound to a service account and are the only way to use + `grant_type=client_credentials`. + + ### Traditional Access Tokens For detailed information about creating, managing, and using traditional access tokens, see: @@ -36,7 +44,11 @@ For detailed information about creating, managing, and using traditional access ### M2M OAuth Credentials (Client Credentials Flow) -M2M credentials provide short-lived tokens via the OAuth client credentials flow expiring after 1 hour. +M2M credentials provide short-lived tokens via the OAuth client credentials flow expiring after 1 hour. Tokens issued by this flow represent the service account itself, not an end-user session. + +If your instance's OpenID Connect discovery document lists `client_credentials` +in `grant_types_supported`, that means the Sourcegraph OAuth server supports +that grant globally. It does not mean a regular OAuth App can use it. **Creating M2M credentials:** @@ -65,7 +77,7 @@ curl -H "Authorization: Bearer ACCESS_TOKEN" \ https://sourcegraph.example.com/.api/graphql ``` -See [OAuth Apps → Client Credentials Flow](/admin/oauth-apps#oauth-flow-examples) for more details on the client credentials flow. +See [OAuth Apps](/admin/oauth-apps#oauth-flow-examples) for a side-by-side explanation of user-delegated OAuth flows versus service-account M2M credentials. Both authentication methods can be used to access Sourcegraph's [GraphQL API](/api/graphql) and [Stream API](/api/stream-api).