Usando o GitHub OAuth com o SDK do Copilot

Conecte usuários ao GitHub Copilot fornecendo autenticação de conta GitHub diretamente em seu aplicativo.

          **Melhor para:** Aplicativos multiusuário, ferramentas internas com controle de acesso da organização, produtos SaaS e aplicativos em que os usuários já têm GitHub contas.

Como funciona

Você cria um GitHub aplicativo OAuth (ou GitHub App), os usuários o autorizam e transmitem o token de acesso para o SDK. Copilot as solicitações são feitas em nome de cada usuário autenticado, usando sua Copilot assinatura. Para obter diagramas de sequência detalhados desse fluxo e arquitetura, consulte o github/copilot-sdkrepositório.

          **Principais características:**

• Cada usuário se autentica com sua própria GitHub conta.

•         Copilot o uso é cobrado na assinatura de cada usuário.
  

•         GitHub Dá suporte a organizações e contas empresariais.
  

• Seu aplicativo nunca lida com chaves de API de modelo—GitHub gerencia tudo.

Etapa 1: Criar um aplicativo OAuth do GitHub

1. Vá para GitHub Configurações > Configurações do Desenvolvedor > Aplicativos OAuth > Novo Aplicativo OAuth. Para organizações, acesse Configurações da Organização > Configurações do Desenvolvedor.
2. Preencha os seguintes campos: * Nome do aplicativo: o nome do aplicativo. * URL da home page: URL do seu aplicativo. * URL de retorno de chamada de autorização: seu ponto de extremidade de retorno de chamada OAuth (por exemplo, https://YOUR-APP.com/auth/callback). Substitua YOUR-APP.com pelo seu domínio.
3. Observe a ID do cliente e gere um segredo do cliente.

Etapa 2: Implementar o fluxo OAuth

Seu aplicativo manipula o fluxo OAuth padrão GitHub . O seguinte mostra a troca de tokens do lado do 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
}

Etapa 3: passar o token para o SDK

Crie um cliente SDK para cada usuário autenticado, passando seu 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!" });

Substitua USER-ACCESS-TOKEN pelo token de acesso OAuth do usuário (por exemplo, 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!" });

Acesso empresarial e organizacional

          GitHub O OAuth naturalmente dá suporte a cenários empresariais. Quando os usuários se autenticam com GitHub, suas associações de organização e associações empresariais são incluídas.

Verificar a associação à organização

Após o OAuth, você pode verificar se o usuário pertence à sua organização:

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

Substitua YOUR-ORG pelo nome da sua organização GitHub.

EMU (Usuários Gerenciados da Empresa)

Para contas de usuário gerenciadas, o fluxo é idêntico. Os usuários da EMU se autenticam por meio GitHub do OAuth, como qualquer outro usuário, e as políticas empresariais (restrições de IP, SSO do SAML) são impostas GitHub automaticamente.

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

Tipos de token com suporte

Prefixo de token	Fonte	Supported
gho_	Token de acesso do usuário OAuth	Sim
ghu_

          GitHub App token de acesso do usuário | Sim |

| github_pat_ | Fine-grained personal access token | Sim | | ghp_ | Personal access token (classic) | Não (encerrando) |

Gerenciamento do ciclo de vida do token

Seu aplicativo é responsável pelo armazenamento de tokens, atualização e tratamento de expiração. O SDK usa qualquer token fornecido, ele não gerencia o ciclo de vida do OAuth.

Padrão de atualização de token

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

Padrões de vários usuários

Um cliente por usuário (recomendado)

Cada usuário obtém seu próprio cliente SDK com seu próprio token. Isso fornece o isolamento mais forte.

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

Limitações

Limitation	Detalhes

          **
          Copilot assinatura necessária** | Cada usuário precisa de uma assinatura ativa GitHub Copilot . |

| O gerenciamento de tokens é sua responsabilidade | Você deve armazenar, atualizar e manipular a expiração do token. | | ** GitHub conta obrigatória** | Os usuários devem ter GitHub contas. | | Limites de taxa por usuário | O uso está sujeito aos limites de taxa de Copilot cada usuário. |

Próximas Etapas 

• Para executar o SDK em servidores, consulte Configurando o SDK do Copilot para serviços de back-end.
• Para lidar com muitos usuários simultâneos, consulte Dimensionamento de implantações do SDK do Copilot.
• Para instalação e sua primeira mensagem, consulte Introdução ao SDK do Copilot.