Autenticação

Autentique a UiPath CLI usando OAuth2 interativo, credenciais de aplicativos externos ou fluxos de tokens de variáveis de ambiente.

A UiPath CLI é compatível com cinco fluxos de autenticação: um desenvolvedor em um laptop, um pipeline de CI/CD chamando o Orchestrator com um aplicativo externo, uma plataforma de CI/CD que pode emitir seus próprios tokens OIDC em vez de manter um segredo de longa duração, um contêiner ou efêmero runtime que já contém um token de acesso e um processo em execução ao lado de um UiPath Robot local. Os três primeiros terminam no mesmo lugar — uma sessão autenticada persistida em uma pasta de credenciais que cada comando uip subsequente reutiliza — mas eles diferem na forma como obtém o token e como a CLI o atualiza. O quarto acesso ignora totalmente o estado no disco. O anexo adia a própria identidade do Robô sobre um canal IPC local.

Escolha um fluxo

Você está…	Use isto	Como
Um desenvolvedor em um laptop ou estação de trabalho	OAuth2 interativo	uip login abre um navegador, você faz login uma vez, os tokens são armazenados e atualizados automaticamente.
Um pipeline ou servidor de CI/CD	Aplicativo externo (credenciais do cliente)	Crie um aplicativo externo no UiPath, passe seu ID e segredo para uip login --client-id … --client-secret …. Os tokens são armazenados e atualizados.
Uma plataforma de CI/CD que pode gerar seus próprios tokens OIDC (identidade da carga de trabalho)	Credenciais federadas	uip login --client-id <app-id> --client-assertion env.OIDC_TOKEN — um OIDC JWT representa o segredo do cliente, portanto, não há segredo de longa duração para armazenar ou girar. Requer --client-id; mutuamente exclusivo com --client-secret.
Um contêiner, executor efêmero ou qualquer processo que já tenha um token	Autenticação da variável de ambiente	Defina UIPATH_CLI_ENABLE_ENV_AUTH=true e forneça o token + organização/tenant por meio de env vars. Nenhum arquivo é escrito; sem atualização.
Um processo em execução em uma máquina com um UiPath Robot local	Credenciais do Robô	Defina UIPATH_CLI_ENFORCE_ROBOT_AUTH=true. uip autentica-se por meio do canal IPC local do robô, em vez de qualquer um dos procedimentos acima.

uip logout limpa todas as credenciais no disco dos três primeiros fluxos. O fluxo env-var não tem nada para limpar — desmarque as variáveis env. As credenciais do robô também não têm nada para limpar — o Robô é o proprietário da identidade.

Dica:

--profile <name> um sinalizador global (consulte Opções globais) que nomeia uma sessão para que vários logins — em qualquer um dos três primeiros fluxos — possam existir lado a lado. Passe o mesmo --profile em cada comando que deve reutilizar uma determinada sessão nomeada; é mutuamente exclusivo com --file/-f em uip login e uip logout.

Fluxo 1 — OAuth2 interativo

Execute uip login sem argumentos:

uip login

uip seu navegador padrão na página de logon do UiPath. Depois de autenticar, a UiPath redireciona de volta para um retorno de chamada local que uip está ouvindo, e a CLI solicita que você escolha um tenant. Quando o tenant é selecionado, a sessão é salva, e pronto.

Sinalizadores úteis:

uip login --tenant DefaultTenant                 # skip the tenant picker
uip login --organization my-org                  # skip the org picker for users in multiple orgs
uip login --interactive                          # explicitly show the tenant picker even if --tenant was set
uip login --authority https://example.com        # point at a non-default identity authority (Automation Suite, staging)
uip login --scope "OR.Folders OR.Jobs"           # restrict the session to specific scopes
uip login --file /path/to/creds                  # store credentials in a non-default folder

Onde as credenciais são armazenadas

Por padrão, a sessão é armazenada dentro de uma pasta .uipath/ . uip procura essa pasta em três lugares, em ordem:

1. Pasta explícita — se você passou --file <folder>, a CLI usa essa pasta. Passe a pasta, não um caminho de arquivo.
2. Caminho acima do diretório de trabalho atual procurando .uipath/ — para que uma pasta do projeto possa carregar sua própria sessão sem afetar a página inicial do usuário.
3. ~/.uipath/ o fallback padrão.

Quando não existir nenhum .uipath/ em qualquer lugar na cadeia principal, uip login criará um em ~/.uipath/. Trate o conteúdo da pasta como opaco — eles são gerenciados por uip login, uip login tenant set e uip logout.

Gerenciar tenants no meio da sessão

A sessão armazena um único tenant ativo de cada vez. Alterne sem executar novamente o fluxo de login completo:

uip login tenant list           # show all tenants available to your account
uip login tenant set MyTenant   # switch the active tenant

uip login status a organização atual, o tenant e a expiração do token.

A atualização é automática

uip os tokens de acesso em segundo plano quando estão próximos da expiração. Você não precisa executar novamente uip login a menos que o próprio token de atualização expire ou seja revogado, ou você altere tenants/organizações.

Login interativo sem periféricos (--no-browser)

uip login normalmente abre o navegador do seu sistema. Em um ambiente sem periféricos — um driver de CI que precisa de uma identidade de usuário real (com um token de atualização) em vez de um Aplicativo externo, mas não possui exibição — passe --no-browser (ou defina UIPATH_CLI_NO_BROWSER=true):

uip login --no-browser --tenant DefaultTenant

Isso mantém todo o fluxo interativo (PKCE, estado, retorno de chamada local, salvamento do token), mas não inicia um navegador. Em vez disso, ele imprime o URL de autorização para o stderr como uma linha de marcador estável:

UIPATH_AUTH_URL https://cloud.uipath.com/identity_/connect/authorize?...

Uma automação externa (por exemplo, um script do Playwight) lê essa linha, abre o URL em um navegador que controla, conclui o login e o provedor de identidade redireciona para o retorno de chamada local de uip como de costume. Completando o login da mesma forma como se um humano tivesse clicado.

O URL impresso é seguro para aparecer em logs de CI: ele carrega apenas valores públicos do OAuth (PKCE code_challenge, state, client_id, redirect_uri, scope) — sem segredo e sem token. --no-browser não tem efeito no Fluxo 2 ou Fluxo 3 (as credenciais do cliente e o login federado nunca abrem um navegador independentemente) — um aviso será registrado se você passá-lo ao lado de --client-secret ou --client-assertion.

Fluxo 2 — Aplicativo externo (credenciais do cliente)

Crie um aplicativo externo no UiPath (Automation Cloud: Admin → Aplicativos externos) com:

• Tipo de aplicativo: confidencial
• Tipo de concessão: credenciais do cliente
• Escopos: os escopos de que seu pipeline precisa (por exemplo, OR.Folders, OR.Jobs, OR.Execution, OR.Assets, OR.Users)

Copie o ID do aplicativo e o Segredo do aplicativo gerados e armazene-os no armazenamento de segredo do pipeline (segredos do GitHub Actions, grupos de variáveis do Azure DevOps, credenciais do Jenkins, Vault etc.).

Faça login a partir do pipeline:

uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT"

O prefixo env.var_NAME

--client-id e --client-secret aceitam um valor literal ou o prefixo especial env. que é resolvido em uma variável de ambiente no runtime. env.UIPATH_CLIENT_ID significa "leia o valor da variável de ambiente UIPATH_CLIENT_ID ". Isso mantém os valores secretos fora do histórico do shell e das listagens de processos — ao contrário de --client-secret "$UIPATH_CLIENT_SECRET", que se expande na linha de comando.

Os valores literais ainda funcionam:

uip login --client-id 3c7af0…-… --client-secret s3cr3t…   # works, but the secret is visible in history

AVISO:

Não defina UIPATH_CLIENT_ID / UIPATH_CLIENT_SECRET como variáveis de ambiente e espere que uip login os colete automaticamente. Antes do UiPath CLI 1.0, uip login --env e a leitura de env-var implícita eram compatíveis; eles foram removidos. Você deve passar o sinalizador explicitamente, com um valor literal ou com o prefixo env. .

Substituições de escopo

Se o Aplicativo externo tiver vários escopos e você quiser uma sessão mais restrita para um script específico, passe --scope:

uip login \
  --client-id env.UIPATH_CLIENT_ID \
  --client-secret env.UIPATH_CLIENT_SECRET \
  --tenant "$UIPATH_TENANT" \
  --scope "OR.Folders OR.Jobs"

Fluxo 3 — Credenciais federadas (identidade da carga de trabalho)

Para plataformas de CI/CD que podem criar seu próprio token OIDC — nenhum segredo do cliente do aplicativo externo para criar, armazenar ou girar:

uip login \
  --client-id "$UIPATH_CLIENT_ID" \
  --client-assertion env.OIDC_TOKEN \
  --tenant "$UIPATH_TENANT"

--client-assertion leva um OIDC JWT no lugar de --client-secret e — como --client-id/--client-secret — aceita o prefixo env. para ler o token de uma variável de ambiente no runtime (recomendado: passar o JWT bruto como um o valor literal imprime um aviso, pois de outra forma seria visível no histórico do shell e nas listagens de processos).

Regras aplicadas por uip login:

• Requer --client-id. O login federado ainda identifica o Aplicativo Externo por seu ID de cliente; apenas o segredo é substituído.
• mutuamente exclusivo com --client-secret. A passagem de ambos falha com --client-secret cannot be combined with --client-assertion.
• é--organization — a organização é fixada pelo ID do cliente, mesmo que o login das credenciais do cliente.
• --no-browser tem efeito — como o login com credenciais do cliente, nenhum navegador é aberto para esse fluxo independentemente.

Uma vez autenticada, a sessão se comporta como uma sessão de um aplicativo externo: ela é persistente, atualizada automaticamente e limpa com uip logout.

Fluxo 4 — Autenticação de variável de ambiente (token de acesso já em mãos)

Alguns ambientes — contêineres criados por outro pipeline, trabalhos agendados, conjuntos de teste — já possuem um token de acesso da UiPath válido e não precisam de login interativo ou troca de credenciais do cliente. Habilite o fluxo de autenticação env-var definindo:

export UIPATH_CLI_ENABLE_ENV_AUTH=true

export UIPATH_CLI_AUTH_TOKEN="$UIPATH_TOKEN"            # JWT access token
export UIPATH_CLI_ORGANIZATION_NAME=my-org
export UIPATH_CLI_ORGANIZATION_ID="$UIPATH_ORG_ID"
export UIPATH_CLI_TENANT_NAME=DefaultTenant
export UIPATH_CLI_TENANT_ID="$UIPATH_TENANT_ID"

Com UIPATH_CLI_ENABLE_ENV_AUTH=true, cada invocação uip autentica-se a partir dessas variáveis e ignora totalmente a pasta .uipath/ . Não há etapa uip login e nada é gravado no disco.

Observações e limitações

• Token opaco. O chamador é responsável pela atualização do token. Não há fluxo de atualização. Quando o token expira, uip login status relata Expired e os comandos falham até que a variável seja rotacionada.
• O URL do servidor é derivados de um JWT. Quando UIPATH_CLI_AUTH_TOKEN contém um token de acesso JWT, sua declaração iss é autorizada — você não define UIPATH_URL. Isso evita erros de roteamento quando um pipeline define UIPATH_URL de forma inconsistente com o token. Isso não se aplica a um token de acesso pessoal — veja abaixo.
• A porta é importante. Se UIPATH_CLI_ENABLE_ENV_AUTH não estiver definido ou for definido como qualquer coisa diferente da string literal true, o fluxo baseado em arquivo será usado. Um erro ortográfico o gateway retorna silenciosamente — verifique com uip login status.
• Os valores ausentes falham explicitamente. Se qualquer variável obrigatória estiver vazia, uip retorna um erro claro nomeando a variável ofensiva, não um genérico "não autenticado".

Exemplo da etapa GitHub Actions usando a autenticação env-var:

- name: Run uip against Orchestrator
  env:
    UIPATH_CLI_ENABLE_ENV_AUTH: "true"
    UIPATH_CLI_AUTH_TOKEN: ${{ secrets.UIPATH_TOKEN }}
    UIPATH_CLI_ORGANIZATION_NAME: contoso
    UIPATH_CLI_ORGANIZATION_ID: ${{ secrets.UIPATH_ORG_ID }}
    UIPATH_CLI_TENANT_NAME: Default
    UIPATH_CLI_TENANT_ID: ${{ secrets.UIPATH_TENANT_ID }}
  run: uip or folders list --output json

Uso de um token de acesso pessoal em vez de um JWT

UIPATH_CLI_AUTH_TOKEN também aceita um Token de Acesso Pessoal da UiPath (PAT — um "token de referência" opaco), criado com uip admin pat create e gerenciado com uip admin pat list/revoke/regenerate. Um PAT não é um JWT, portanto, não carrega nenhuma declaração iss — o que altera uma regra acima:

• UIPATH_URL torna-se necessário. Como a CLI não pode derivar uma URL do servidor de um token opaco, defina UIPATH_URL (por exemplo https://cloud.uipath.com) explicitamente. É ignorado quando o token é um JWT, mas obrigatório quando é um PAT.
• Nenhuma expiração é relatada. uip login status mostra Logged in sem data de expiração e sem campos de identidade — o token é opaco, portanto, a CLI também não tem como saber. Os comandos falham com 401 quando o PAT é revogado ou expira, sem nenhum aviso local prévio — rastreie você mesmo a data de expiração.
• Todas as outras variáveis nesse fluxo (a porta, os nomes e IDs dos tenants/organizações) funcionam da mesma forma que com um JWT.

Fluxo 5 — Credenciais de robô (UiPath Robot local)

Para processos que executam ao lado de um UiPath Robot local — Studio Desktop e outros contextos hospedados no Robô — a autenticação pode adiar inteiramente para a própria identidade do Robô em um canal IPC local, em vez de qualquer token que a CLI gerencie a si mesma:

export UIPATH_CLI_ENFORCE_ROBOT_AUTH=true
uip or folders list

Com a porta definida, uip se comunica com o ponto de extremidade IPC do Robô para o token de acesso e o URL base do recurso, ignorando totalmente a pasta de credenciais .uipath/ e o fluxo env-var. UIPATH_CLI_ENFORCE_ROBOT_AUTH e UIPATH_CLI_ENABLE_ENV_AUTH são mutuamente exclusivos — a configuração de ambos é um erro, não uma substituição silenciosa. Não há etapa uip login, nenhuma atualização para gerenciar e nada para uip logout limpar.

Fazer logout

uip logout                         # clear the default credentials folder
uip logout --file /path/to/creds   # clear a non-default credentials folder

logout limpa a sessão armazenada dentro de .uipath/. No fluxo env-var não há nada para remover — desmarque as variáveis.

Solução de problemas

❌ Não conectado

Nenhuma pasta .uipath/ foi encontrada na cadeia atual ou a sessão armazenada está ilegível. Execute uip login (ou defina o fluxo env-var) e tente novamente.

Token expirado

As sessões de Aplicativo interativo e Externo são atualizadas automaticamente quando estão próximas da expiração. Se você vir Expired, o próprio token de atualização expirou ou foi revogado — execute uip login novamente. Para autenticação do env-var, rotacione UIPATH_CLI_AUTH_TOKEN.

Vários membros da organização, organização errada escolhida

Passe --organization <logical-name> em uip login para ignorar o seletor de organizações ou uip login tenant list após o fato para ver ao que a sessão está realmente associada.

O proxy corporativo bloqueia o retorno de chamada do navegador

O fluxo interativo abre uma porta de retorno de chamada local 127.0.0.1 em. A maioria dos proxies deixa o loopback inalterado, mas algumas configurações robustas o bloqueiam. Trabalhe usando o Fluxo 2 (aplicativo externo), o Fluxo 3 (credenciais federadas) ou o Fluxo 4 (env-var auth) — todos os três evitam totalmente o retorno de chamada do navegador.

Veja também

• Instalação do UiPath CLI — configuração única antes da autenticação.
• Configuração — variáveis de ambiente e precedência de sinalizador.
• Sessões e credenciais — layout em disco da pasta de credenciais.
• referência de login uip, referência de logout uip.