在 Copilot SDK 中使用 GitHub OAuth

"通过在您的应用程序内直接提供 GitHub 账户认证，将用户连接到 GitHub Copilot。

最佳适用场景： 多用户应用、具有组织访问控制的内部工具、SaaS 产品以及用户已有 GitHub 账户的应用。

它是如何工作的

您创建一个 GitHub OAuth 应用（或 GitHub App），用户授权后，您将他们的访问令牌传递给 SDK。Copilot 请求将代表每个已认证用户发起，使用其 Copilot 订阅。有关此流程和架构的详细时序图，请参阅 github/copilot-sdk 仓库。

关键特性

• 每位用户使用其自己的 GitHub 账户进行身份验证。
• Copilot 使用费用计入每位用户的订阅。
• 支持 GitHub 组织和企业账户。
• 您的应用程序从不处理模型 API 密钥——所有操作均由 GitHub 管理。

步骤 1：创建 GitHub OAuth 应用

1. 前往 GitHub 设置 > 开发者设置 > OAuth 应用 > 新建 OAuth 应用。对于组织，请前往 组织设置 > 开发者设置。
2. 填写以下字段
   • 应用名称：您的应用名称。
   • 主页 URL：您的应用 URL。
   • 授权回调 URL：您的 OAuth 回调端点（例如 https://YOUR-APP.com/auth/callback）。将 YOUR-APP.com 替换为您的域名。
3. 记录您的 客户端 ID 并生成 客户端密钥。

步骤 2：实现 OAuth 流程

您的应用程序处理标准的 GitHub OAuth 流程。下面展示服务器端的令牌交换。

// 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
}

步骤 3：将令牌传递给 SDK

为每个已认证用户创建一个 SDK 客户端，并传入其令牌。

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!" });

将 USER-ACCESS-TOKEN 替换为用户的 OAuth 访问令牌（例如 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!" });

企业和组织访问

GitHub OAuth 天然支持企业场景。当用户使用 GitHub 进行身份验证时，其组织成员资格和企业关联信息会被包含在内。

验证组织成员资格

OAuth 完成后，您可以检查用户是否属于您的组织

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);

将 YOUR-ORG 替换为您的 GitHub 组织名称。

企业托管用户（EMU）

对于托管用户账户，流程完全相同。EMU 用户通过 GitHub OAuth 进行身份验证，与其他用户无异，企业策略（IP 限制、SAML 单点登录）由 GitHub 自动强制执行。

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

支持的令牌类型

令牌前缀	来源	Supported
gho_	OAuth 用户访问令牌	是
ghu_	GitHub App 用户访问令牌	是
github_pat_	细粒度个人访问令牌	是
ghp_	个人访问令牌（classic）	否（已停用）

令牌生命周期管理

您的应用程序负责令牌的存储、刷新和过期处理。SDK 使用您提供的令牌——它不管理 OAuth 生命周期。

令牌刷新模式

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");
}

多用户模式

每用户一个客户端（推荐）

每位用户拥有自己的 SDK 客户端和令牌。这提供了最强的隔离性。

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)!;
}

限制

限制	详细信息
需要 Copilot 订阅	每位用户都需要有效的 GitHub Copilot 订阅。
令牌管理由您负责	您必须存储、刷新并处理令牌的过期。
需要 GitHub 账户	用户必须拥有 GitHub 账户。
每用户速率限制	使用受每位用户的 Copilot 速率限制约束。

后续步骤

• 要在服务器上运行 SDK，请参阅 后端服务的 Copilot SDK 设置。
• 要处理大量并发用户，请参阅 Copilot SDK 部署的扩展。
• 有关安装和首条消息的内容，请参阅 Copilot SDK 入门指南。