Contas de serviço

Com as contas de serviço, você pode executar fluxos de trabalho do Codex sem interface gráfica e ampliar seu uso em toda a organização sem depender da conta de um funcionário. Cada executor de integração contínua (CI), tarefa agendada ou integração compartilhada tem uma identidade própria no espaço de trabalho do ChatGPT, com os mesmos grupos, funções, controles de acesso e recursos de auditoria disponíveis para os membros da equipe.

Somente proprietários e administradores do espaço de trabalho podem criar contas de serviço. Eles podem permitir que outras pessoas ou grupos gerenciem uma conta, configurem plugins ou criem tokens de acesso.

Uma conta de serviço representa uma identidade não humana no espaço de trabalho. Um token de acesso pessoal representa o membro do espaço de trabalho que o criou. Na Plataforma de API, as contas de serviço de projeto e as chaves de API usam controles de acesso e cobrança próprios do projeto.

Criar e configurar uma conta de serviço

Este guia interativo usa o GitHub como exemplo e mostra como criar uma conta, configurar um plugin, criar um token e atribuir grupos e funções.

1. Nas configurações do espaço de trabalho, abra Contas de serviço.
2. Selecione o botão de adição (+) e insira um nome descritivo, como release-automation.
3. Selecione Criar.

Conectar um plugin

Configure os plugins diretamente na conta de serviço. Ela não herda os plugins nem os aplicativos conectados de quem a criou.

1. Abra a seção Plug-ins da conta e selecione Adicionar plugin.
2. Escolha um plugin e verifique se ele aparece como configurado ou ativado.

As funções Configurar e Gerente permitem configurar plugins. A função Usuário não permite essa ação.

Criar um token de acesso

Crie um token na página de detalhes da conta de serviço. O token representa a própria conta de serviço, independentemente de quem o criou.

1. Abra a conta e selecione Criar token na seção Tokens de acesso.
2. Dê um nome ao token, confirme o escopo Codex e escolha um prazo de validade.
3. Selecione Criar e salve o token no seu gerenciador de segredos.

O token completo aparece apenas uma vez. As políticas do espaço de trabalho determinam os prazos de validade disponíveis.

Atribuir funções e grupos

Assim como uma pessoa que faz parte do espaço de trabalho, uma conta de serviço pode receber funções e participar de grupos. Conceda acesso diretamente à conta, pois ela não herda as permissões de quem a criou.

Para permitir que pessoas ou grupos gerenciem a conta, selecione Compartilhar, depois Adicionar pessoas ou grupos e atribua uma função.

Essas funções se aplicam às pessoas que gerenciam a conta. Elas são independentes das funções e dos grupos do espaço de trabalho atribuídos à conta de serviço.

As funções Configurar e Gerente permitem ativar ou desativar a conta. Somente proprietários e administradores do espaço de trabalho podem criar, excluir ou compartilhar contas. Para gerenciar contas compartilhadas, os operadores entram no ChatGPT com suas próprias contas.

Para saber mais sobre as permissões do espaço de trabalho, consulte Funções e permissões do espaço de trabalho.

Executar o Codex sem fazer login

Os tokens de acesso de contas de serviço exigem a versão 0.142.0 ou posterior da CLI do Codex. Defina CODEX_ACCESS_TOKEN e execute o Codex sem abrir um navegador.

export CODEX_ACCESS_TOKEN="<service-account-access-token>"
codex exec --json "Inspect this repository and summarize its current state."

Em ambientes de CI, forneça o token por meio de um gerenciador de segredos ou de um segredo configurado no executor.

Para salvar o login em uma máquina confiável, passe o token pela entrada padrão.

printf '%s' "$CODEX_ACCESS_TOKEN" | codex login --with-access-token
codex exec "Summarize the changes in the current branch."

Esse procedimento salva a credencial localmente. Em executores compartilhados ou temporários, use CODEX_ACCESS_TOKEN sem salvar o login.

Provisionar contas de serviço com SCIM

Se o espaço de trabalho oferecer suporte ao provisionamento de contas de serviço pelo protocolo System for Cross-domain Identity Management (SCIM), defina userType como ServiceAccount no seu provedor de identidade.

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "svc-codex-release@company.example",
  "displayName": "Codex release automation",
  "active": true,
  "userType": "ServiceAccount"
}

Adicione a identidade ao espaço de trabalho e aos grupos necessários. Em seguida, sincronize-a. O provedor de identidade gerencia o nome da conta, os grupos dos quais ela faz parte e seu ciclo de vida. O ChatGPT não permite renomear nem excluir contas gerenciadas via SCIM. Consulte Grupos e provisionamento.

Gerenciar contas de serviço com a API de administração

Se o seu espaço de trabalho tiver acesso à API de administração do ChatGPT, use uma chave dessa API para gerenciar contas, tokens e compartilhamento. As operações de leitura exigem chatgpt.enterprise.service_account.read, e as alterações exigem chatgpt.enterprise.service_account.write. Não é possível usar um token de conta de serviço para autenticar requisições à API de administração.

Consulte a referência da API de administração para verificar as operações disponíveis e os caminhos atuais das requisições.

Contas

Para criar contas, use POST /v1/manage/workspaces/{workspace_id}/service-accounts. As atualizações de conta alteram apenas enabled.

Tokens

Para criar um token do Codex com validade de 30 dias, use os valores do exemplo a seguir.

{
  "name": "production-release-runner",
  "ttl": 2592000,
  "scopes": ["chatgpt.workspace.feature.allow-codex-local-access.access"]
}

ttl indica o prazo de validade do token em segundos. Se o prazo for finito, ele deve ser inferior a um ano e respeitar a política de expiração do espaço de trabalho. A API retorna o valor completo de access_token apenas no momento da criação do token.

A API de administração também permite listar, adicionar, atualizar e remover permissões de acesso a contas compartilhadas. Os valores de função aceitos são manager, configurer e user. No ChatGPT, configurer aparece como Configurar.

Proteger e gerenciar contas de serviço

• Conceda à conta apenas as funções, os grupos, os plugins e as conexões de que o fluxo de trabalho precisa.
• Armazene os tokens em um gerenciador de segredos e use executores confiáveis.
• Não inclua credenciais em logs, mensagens de chat ou sistemas de controle de versão.
• Defina prazos de validade finitos e revise regularmente o acesso à conta e suas atividades.
• Para substituir um token, crie outro, atualize o fluxo de trabalho, verifique o acesso e revogue o token antigo no espaço de trabalho ou pela API de administração.
• Revogue imediatamente os tokens expostos e investigue as atividades recentes da conta.
• Use o espaço de trabalho ou a API de administração para desativar ou excluir contas sem uso. Ambas as ações revogam todos os tokens ativos. É possível reativar contas desativadas com novos tokens. A exclusão é irreversível.

As execuções são atribuídas à conta de serviço. Os dados analíticos e os registros de auditoria disponíveis no espaço de trabalho também podem identificar quem criou tokens ou alterou as configurações da conta. Consulte a referência da API de administração para confirmar quais eventos são registrados.

Documentação relacionada

• Autenticação
• Tokens de acesso pessoal
• Funções e permissões do espaço de trabalho
• Grupos e provisionamento
• Governança
• API de Compliance e eventos de auditoria
• Modo não interativo