Uso de OAuth de GitHub con el SDK de Copilot

Permitir que los usuarios se autentiquen con sus GitHub cuentas para usar GitHub Copilot a través de tu aplicación.

¿Quién puede utilizar esta característica?

SDK de GitHub Copilot está disponible con todos los Copilot planes.

En este artículo

Nota:

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Conecte a los usuarios a GitHub Copilot proporcionando la autenticación de cuentas GitHub directamente en su aplicación.

          **Lo mejor para:** Aplicaciones multiusuario, herramientas internas con control de acceso de la organización, productos SaaS y aplicaciones en las que los usuarios ya tienen GitHub cuentas.

Cómo funciona

Cree una GitHub aplicación de OAuth (o GitHub App), los usuarios lo autoricen y pase su token de acceso al SDK. Copilot Las solicitudes se realizan en nombre de cada usuario autenticado, mediante su suscripción Copilot . Para obtener diagramas de secuencia detallados de este flujo y arquitectura, consulte el github/copilot-sdkrepositorio.

          **Características clave:**
  • Cada usuario se autentica con su propia GitHub cuenta.
  •         Copilot el uso se factura a la suscripción de cada usuario.
  • Admite GitHub organizaciones y cuentas empresariales.
  • La aplicación nunca controla las claves de API del modelo:GitHub administra todo.

Paso 1: Creación de una aplicación de OAuth de GitHub

  1. Vaya a GitHub Configuración > Configuración del desarrollador > Aplicaciones de OAuth > Nueva aplicación de OAuth. Para las organizaciones, vaya a Configuración de la organización > Configuración del desarrollador.
  2. Rellene los campos siguientes: * Nombre de la aplicación: nombre de la aplicación. * Dirección URL de la página principal: dirección URL de la aplicación. * Dirección URL de devolución de llamada de autorización: tu endpoint de devolución de llamada de OAuth (por ejemplo, https://YOUR-APP.com/auth/callback). Reemplaza YOUR-APP.com por tu dominio.
  3. Anote el identificador de cliente y genere un secreto de cliente.

Nota:

Tanto GitHub Apps como las aplicaciones OAuth funcionan con el SDK. GitHub Apps ofrecen permisos más específicos y se recomiendan para los nuevos proyectos. Las aplicaciones de OAuth son más sencillas de configurar. El flujo de tokens es el mismo desde la perspectiva del SDK.

Paso 2: Implementar el flujo de OAuth

La aplicación controla el flujo de OAuth estándar GitHub . A continuación se muestra el intercambio de tokens del lado servidor:

// Server-side: exchange authorization code for user token
async function handleOAuthCallback(code: string): Promise<string> {
    const response = await fetch("https://github.com/login/oauth/access_token", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            Accept: "application/json",
        },
        body: JSON.stringify({
            client_id: process.env.GITHUB_CLIENT_ID,
            client_secret: process.env.GITHUB_CLIENT_SECRET,
            code,
        }),
    });

    const data = await response.json();
    return data.access_token; // gho_xxxx or ghu_xxxx
}

Paso 3: Pasar el token al SDK

Cree un cliente del SDK para cada usuario autenticado y pase su token.

Node.js/TypeScript

import { CopilotClient } from "@github/copilot-sdk";

// Create a client for an authenticated user
function createClientForUser(userToken: string): CopilotClient {
    return new CopilotClient({
        githubToken: userToken,
        useLoggedInUser: false,  // Don't fall back to CLI sign-in
    });
}

// Usage
const client = createClientForUser("USER-ACCESS-TOKEN");
const session = await client.createSession({
    sessionId: `user-${userId}-session`,
    model: "gpt-4.1",
});

const response = await session.sendAndWait({ prompt: "Hello!" });

Reemplace por USER-ACCESS-TOKEN el token de acceso de OAuth del usuario (por ejemplo, gho_xxxx).

Python

from copilot import CopilotClient, PermissionHandler

def create_client_for_user(user_token: str) -> CopilotClient:
    return CopilotClient({
        "github_token": user_token,
        "use_logged_in_user": False,
    })

# Usage
client = create_client_for_user("USER-ACCESS-TOKEN")
await client.start()

session = await client.create_session(
    on_permission_request=PermissionHandler.approve_all,
    model="gpt-4.1",
    session_id=f"user-{user_id}-session",
)

response = await session.send_and_wait({"prompt": "Hello!"})

Go

func createClientForUser(userToken string) *copilot.Client {
    return copilot.NewClient(&copilot.ClientOptions{
        GithubToken:     userToken,
        UseLoggedInUser: copilot.Bool(false),
    })
}

// Usage
client := createClientForUser("USER-ACCESS-TOKEN")
client.Start(ctx)
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{
    SessionID: fmt.Sprintf("user-%s-session", userID),
    Model:     "gpt-4.1",
})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})

.NET

CopilotClient CreateClientForUser(string userToken) =>
    new CopilotClient(new CopilotClientOptions
    {
        GithubToken = userToken,
        UseLoggedInUser = false,
    });

// Usage
await using var client = CreateClientForUser("USER-ACCESS-TOKEN");
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    SessionId = $"user-{userId}-session",
    Model = "gpt-4.1",
});

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello!" });

Acceso empresarial y organizacional

          GitHub OAuth admite naturalmente escenarios empresariales. Cuando los usuarios se autentican con GitHub, se incluyen sus pertenencias a la organización y asociaciones empresariales.

Comprobación de la pertenencia a la organización

Después de OAuth, puede comprobar que el usuario pertenece a su organización:

async function verifyOrgMembership(
    token: string,
    requiredOrg: string
): Promise<boolean> {
    const response = await fetch("https://api.github.com/user/orgs", {
        headers: { Authorization: `Bearer ${token}` },
    });
    const orgs = await response.json();
    return orgs.some((org: any) => org.login === requiredOrg);
}

// In your auth flow
const token = await handleOAuthCallback(code);
if (!await verifyOrgMembership(token, "YOUR-ORG")) {
    throw new Error("User is not a member of the required organization");
}
const client = createClientForUser(token);

Reemplace por YOUR-ORG el nombre de la GitHub organización.

Usuarios administrados por empresas (EMU)

Para cuentas de usuario administradas, el flujo es idéntico. Los usuarios de EMU se autentican a través de GitHub OAuth como cualquier otro usuario, y las directivas empresariales (restricciones de IP, inicio de sesión único de SAML) son aplicadas GitHub automáticamente.

// No special SDK configuration needed for EMU
const client = new CopilotClient({
    githubToken: emuUserToken,
    useLoggedInUser: false,
});

Tipos de token admitidos

Prefijo de tokenFuenteSoportado
gho_Token de acceso de usuario de OAuthSí
ghu_
          GitHub App token de acceso de usuario | Sí |

| github_pat_ | Fine-grained personal access token | Sí | | ghp_ | Personal access token (classic) | No (cerrar) |

Administración del ciclo de vida de tokens

La aplicación es responsable del almacenamiento de tokens, la actualización y el control de expiración. El SDK usa el token que proporcione: no administra el ciclo de vida de OAuth.

Patrón de actualización de tokens

async function getOrRefreshToken(userId: string): Promise<string> {
    const stored = await tokenStore.get(userId);

    if (stored && !isExpired(stored)) {
        return stored.accessToken;
    }

    if (stored?.refreshToken) {
        const refreshed = await refreshGitHubToken(stored.refreshToken);
        await tokenStore.set(userId, refreshed);
        return refreshed.accessToken;
    }

    throw new Error("User must re-authenticate");
}

Patrones multiusuario

Cada usuario obtiene su propio cliente del SDK con su propio token. Esto proporciona el aislamiento más fuerte.

const clients = new Map<string, CopilotClient>();

function getClientForUser(userId: string, token: string): CopilotClient {
    if (!clients.has(userId)) {
        clients.set(userId, new CopilotClient({
            githubToken: token,
            useLoggedInUser: false,
        }));
    }
    return clients.get(userId)!;
}

Limitaciones

LimitaciónDetalles
          **
          Copilot suscripción necesaria** | Cada usuario necesita una suscripción activa GitHub Copilot . |

| La administración de tokens es su responsabilidad | Debe almacenar, actualizar y controlar la expiración del token. | | ** GitHub se requiere cuenta** | Los usuarios deben tener GitHub cuentas. | | Límites de velocidad por usuario | El uso está sujeto a los límites de tarifa de Copilot cada usuario. |

Pasos siguientes