Contas de serviço

As contas de serviço permitem executar e dimensionar fluxos de trabalho do Codex sem interface gráfica em toda a sua organização sem depender da conta de um funcionário. Cada executor de integração contínua (CI), tarefa agendada ou integração partilhada recebe a sua própria identidade do espaço de trabalho do ChatGPT, com os mesmos grupos, funções, controlos de acesso e capacidade de auditoria esperados para as pessoas.

Apenas os proprietários e administradores do espaço de trabalho podem criar contas de serviço. Podem permitir que outras pessoas ou grupos façam a gestão de uma conta, configurem plugins ou criem tokens de acesso.

Uma conta de serviço representa uma identidade não humana do espaço de trabalho. Um token de acesso pessoal representa o membro do espaço de trabalho que o cria. As contas de serviço de projetos da API Platform e as API keys utilizam acessos e faturação de projeto distintos.

Criar e configurar uma conta de serviço

Este guia interativo utiliza o GitHub como exemplo: crie uma conta, configure um plugin, crie um token e atribua grupos e funções.

1. Abra Contas de serviço nas definições do espaço de trabalho.
2. Selecione o botão de adição (+) e introduza um nome descritivo, como release-automation.
3. Selecione Criar.

Ligar um plugin

Configure os plugins na própria conta de serviço. Esta não herda os plugins nem as aplicações ligadas do respetivo criador.

1. Abra a secção Plugins da conta e selecione Adicionar plugin.
2. Escolha um plugin e confirme que aparece como configurado ou ativado.

As funções Configurador e Gestor podem configurar plugins. A função Utilizador não pode.

Criar um token de acesso

Crie um token na página de detalhes da conta de serviço. O token representa a conta de serviço e não a pessoa que o cria.

1. Abra a conta e selecione Criar token em Tokens de acesso.
2. Atribua um nome ao token, confirme o âmbito Codex e escolha uma validade.
3. Selecione Criar e guarde o token no seu gestor de segredos.

O token completo só é apresentado uma vez. As políticas do espaço de trabalho controlam as validades disponíveis.

Atribuir funções e grupos

Uma conta de serviço pode receber funções do espaço de trabalho e aderir a grupos como um membro humano do espaço de trabalho. Atribua-lhe o acesso diretamente; a conta não herda as permissões do respetivo criador.

Para permitir que pessoas ou grupos façam a gestão da conta, selecione Partilhar, depois Adicionar pessoas ou grupos e atribua uma função:

Estas funções aplicam-se às pessoas que gerem a conta. São distintas das funções e dos grupos do espaço de trabalho atribuídos à conta de serviço.

Configurador e Gestor podem ativar ou desativar a conta. Apenas os proprietários e administradores do espaço de trabalho podem criar, eliminar ou partilhar contas. Os operadores gerem contas partilhadas com sessão iniciada nas suas próprias contas do ChatGPT.

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

Executar o Codex sem iniciar sessão

Os tokens de acesso de contas de serviço requerem o Codex CLI versão 0.142.0 ou posterior. 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 CI, forneça o token através de um gestor de segredos ou de um segredo do executor.

Para guardar um início de sessão numa máquina fidedigna, passe o token através da entrada padrão:

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

Esta ação guarda a credencial localmente. Em executores partilhados ou temporários, utilize CODEX_ACCESS_TOKEN sem guardar um início de sessão.

Aprovisionar contas de serviço com SCIM

Se o seu espaço de trabalho suportar o aprovisionamento de contas de serviço através do protocolo System for Cross-domain Identity Management (SCIM), defina userType como ServiceAccount no seu fornecedor 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"
}

Atribua a identidade ao espaço de trabalho e aos grupos necessários e, em seguida, sincronize-a. O fornecedor de identidade gere o nome, a associação a grupos e o ciclo de vida da conta. As contas geridas por SCIM não podem ser renomeadas nem eliminadas no ChatGPT. Consulte Grupos e aprovisionamento.

Gerir contas de serviço com a Admin API

Se o seu espaço de trabalho tiver acesso, utilize uma ChatGPT Admin API key para gerir contas, tokens e partilhas. As operações de leitura requerem chatgpt.enterprise.service_account.read; as alterações requerem chatgpt.enterprise.service_account.write. Um token de conta de serviço não pode autenticar pedidos à Admin API.

Consulte a referência da Admin API para conhecer as operações disponíveis e os caminhos de pedidos atuais.

Contas

Crie contas com POST /v1/manage/workspaces/{workspace_id}/service-accounts. As atualizações da conta alteram apenas enabled.

Tokens

Por exemplo, crie um token do Codex que expire após 30 dias:

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

ttl é o tempo de vida do token em segundos. Um tempo de vida finito tem de ser inferior a um ano e respeitar a política de validade do seu espaço de trabalho. O access_token completo só é devolvido quando o token é criado.

A Admin API também pode listar, adicionar, atualizar e remover o acesso à conta partilhada. Os respetivos valores de função são manager, configurer e user; configurer aparece como Configurador no ChatGPT.

Proteger e gerir contas de serviço

• Conceda apenas as funções, os grupos, os plugins e as ligações de que o fluxo de trabalho necessita.
• Armazene os tokens num gestor de segredos e utilize executores fidedignos.
• Mantenha as credenciais fora de registos, mensagens de conversa e do controlo de código-fonte.
• Defina validades finitas e reveja regularmente o acesso e a atividade da conta.
• Efetue a rotação de um token criando um substituto, atualizando o fluxo de trabalho, verificando o acesso e revogando o token antigo no espaço de trabalho ou na Admin API.
• Revogue imediatamente os tokens expostos e investigue a atividade recente da conta.
• Desative ou elimine contas não utilizadas no espaço de trabalho ou na Admin API. Ambas as ações revogam todos os tokens ativos. As contas desativadas podem voltar a ser ativadas com novos tokens; uma eliminação não pode ser anulada.

As execuções são atribuídas à conta de serviço. As análises do espaço de trabalho e os registos de auditoria disponíveis também podem identificar quem criou tokens ou alterou as definições da conta. Confirme a cobertura dos eventos na referência da Admin API.

Documentação relacionada

• Autenticação
• Tokens de acesso pessoais
• Funções e permissões do espaço de trabalho
• Grupos e aprovisionamento
• Governação
• Compliance API e eventos de auditoria
• Modo não interativo