- Introdução
- Autenticação
- Métodos de autenticação do SQL
- Aplicativos externos (OAuth)
- ROPC (não recomendado)
- Definição do Swagger
- APIs do Orchestrator
- Solicitações de alertas
- Solicitações de ativos
- Solicitações de calendários
- Solicitações de ambientes
- Solicitações de pastas
- Solicitações de Tarefas Genéricas
- Solicitações de trabalhos
- Solicitações de bibliotecas
- Solicitações de licenças
- Solicitações de pacotes
- Solicitações de permissões
- Solicitações de espaços de trabalho pessoais
- Solicitações de processos
- Solicitações de itens de fila
- Solicitações de robôs
- Solicitações de funções
- Solicitações de agendamentos
- Solicitações de configurações
- Solicitações de tarefas
- Solicitações de catálogos de tarefas
- Solicitações de formulários de tarefas
- Solicitações de tenants
- Solicitações de Transações
- Solicitações de usuários
- Solicitações de webhooks
- APIs de gestão de plataforma
Aplicativos externos (OAuth)
Como desenvolvedor que trabalha na integração de produtos UiPath com aplicativos externos, você é responsável por tarefas como gerenciar alterações de escopo, gerenciar tokens de acesso e atualizar tokens e manter a integração entre o aplicativo externo e os recursos da UiPath. O guia a seguir orienta você por essas operações.
O OAuth oferece uma seleção de bibliotecas que você pode aproveitar para simplificar a autenticação, autorização, delegação e segurança de chamadas de API. Você pode acessar esses recursos diretamente do site oficial do OAuth.
Como desenvolvedor, assim que o administrador da organização registrar seu aplicativo externo na UiPath, você precisará obter os detalhes de registro para autenticar seu aplicativo externo com recursos da UiPath.
-
O Tipo de aplicativo e o ID do aplicativo. Se você estiver trabalhando com um aplicativo confidencial, você também precisará do Segredo do aplicativo. Eles são usados para autenticar seu aplicativo com o Identity Server da UiPath, o servidor de autorização para acessar recursos da UiPath, que é compatível com a estrutura do OAuth 2.0.
-
Além disso, você precisa saber os escopos de aplicativos externos, que definem quais recursos seu aplicativo externo pode acessar na UiPath. Isso inclui a especificação do recurso (como Ativos, Processos etc.) e o nível de permissão (ler, gravar, editar etc.).
Depois que o aplicativo externo for registrado, você deve implementar o mecanismo de autorização apropriado para o aplicativo externo, com o tipo de concessão apropriado, para que o aplicativo externo possa recuperar um token de acesso.
Durante esse processo, solicite um token de acesso fornecendo o escopo do aplicativo externo e as credenciais do aplicativo registrado - o ID do aplicativo (e o Segredo do aplicativo no caso de aplicativos confidenciais) - para o Identity Server. Se as credenciais forem válidas, o Identity Server responderá emitindo um código de autorização, que será usado para gerar o token de acesso.
Tipo de Aplicativo |
Escopo |
Tipo de concessão necessário |
---|---|---|
Confidencial |
Aplicativo |
Client Credentials |
Confidencial |
Usuário |
Authorization Code |
Confidencial |
aplicativo e usuário |
Credenciais do cliente e código de autorização |
não confidencial |
Usuário |
Código de autorização com o PKCE |
Quando o nome de escopo é o mesmo tanto sob o escopo do usuário quanto o do aplicativo, como no caso do Orchestrator, o tipo de concessão que você usa determina se o recurso é chamado sob o escopo do usuário ou do aplicativo.
O escopo definido pelo administrador para um aplicativo determina o nível máximo de acesso que o aplicativo pode atingir. Como desenvolvedor, se você solicitar acesso além desse escopo predefinido, sua solicitação falhará. Portanto, é importante garantir que suas solicitações estejam dentro do escopo definido pelo administrador.
No nível de administrador, as permissões do aplicativo podem ser:
-
Permissões com escopo de organização: por padrão, quando um aplicativo externo é registrado, ele tem acesso em toda a organização aos recursos de acordo com os escopos definidos.
-
Permissões refinadas: para configurações de permissões mais granulares, o administrador da organização pode atribuir uma função no nível do tenant ou da pasta dentro do Orchestrator ao aplicativo externo, embora isso seja aplicável apenas a aplicativos confidenciais.
No nível do desenvolvedor, a declaração de escopos é feita da seguinte forma:
-
Permissões com escopo de organização: quando você declara um escopo explicitamente especificado, como
OR.Machines.View
na solicitação de token, implica que o aplicativo está solicitando uma permissão de acesso em toda a organização. -
Permissões refinadas: para fornecer ao seu aplicativo acesso refinado, você deve declarar
OR.Default
na solicitação de token.OR.Default
atua como um escopo de curinga, fornecendo ao seu aplicativo acesso refinado que depende da função atribuída em tenants ou pastas específicos.
OR.Machines.View
e OR.Default
. Essa declaração combinada permite que seu aplicativo externo opere tanto em um nível de toda a organização quanto em tenants ou pastas específicos do Orchestrator.
Verifique o ponto de extremidade na documentação de API do recurso para obter os valores de escopo de que você precisa. Por exemplo:
Com esse tipo de concessão, o fluxo é o seguinte:
-
O aplicativo externo solicita um token de acesso enviando uma solicitação POST, que inclui o
client_id
eclient_secret
para o ponto de extremidade do token do Identity Server:
:https://{yourDomain}/identity
/connect/tokengrant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}
grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}Campo
Description
client_id
Especifica o identificador exclusivo atribuído ao aplicativo durante seu registro.
Deve conter o ID do aplicativo (fornecido pelo administrador).
client_secret
Especifica informações confidenciais, como uma senha, que são fornecidas a aplicativos confidenciais após o registro. Esse campo é usado junto com oclient_id
para autenticar o aplicativo quando emite solicitações para o Identity Server.Deve conter o Segredo do Aplicativo (fornecido pelo administrador).
scope
Especifica os escopos solicitados pelo aplicativo, delimitados por um espaço; por exemplo:OR.Machines.View OR.Default
.-
Use
OR.Default
para conceder acesso controlado e personalizado dentro de tenants ou pastas específicos. As permissões reais que o aplicativo obtém são determinadas com base em onde o aplicativo é atribuído dentro de tenants ou pastas pelo administrador. -
Use escopos explícitos, como
OR.Machines.View
, para conceder acesso amplo e em toda a organização a certos recursos.
-
-
O aplicativo externo recebe uma resposta contendo o token de acesso:O aplicativo pode usar o token de acesso para acessar recursos de usuários até que o token expire (uma hora).
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
{ "access_token":"{access_token}", "expires_in":3600, "token_type":"Bearer", "scope":"{scopes}" }
Para obter uma compreensão detalhada do fluxo do OAuth que utiliza códigos de autorização, consulte o documento RFC 6749.
application/x-www-form-urlencoded
O aplicativo pode usar o token de acesso para acessar recursos de usuários até que o token expire (uma hora).
Para um aplicativo não confidencial com escopos de usuário, você executa o código de autorização com fluxo PKCE. Para obter uma compreensão detalhada do fluxo do OAuth que utiliza o código de autorização com PKCE, consulte o documento RFC 7636.
Com esse tipo de concessão, o fluxo é o seguinte:
-
O aplicativo externo envia uma solicitação de autorização para obter o código de autorização para o ponto de extremidade
https://{yourDomain}/identity/connect/authorize?
:response_type=code&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}&code_challenge={cryptographically-random string from code_verifier}&code_challenge_method=S256
response_type=code&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}&code_challenge={cryptographically-random string from code_verifier}&code_challenge_method=S256Opção
Description
client_id
Especifica o identificador exclusivo atribuído ao aplicativo durante seu registro.
Deve conter o ID do aplicativo (conforme fornecido pelo administrador).
scope
Especifica os escopos solicitados pelo aplicativo, delimitados por um espaço; por exemplo:OR.Machines.View
.redirect_uri
Especifica a URL para onde o UiPath Identity Server redireciona a solicitação de autorização após o código de autorização ser concedido.
code_challenge_method
Especifica o método usado para codificar ocode_verifier
para ocode_challenge
. O valor para esse campo deve ser S256, o que significa que ocode_verifier
deve ter hash usando SHA256 e codificado com base64url para criar ocode_challenge
.code_challenge
Uma string criptograficamente aleatória derivada docode_verifier
, usada para conectar a solicitação de autorização à solicitação de token.Você deve usar um algoritmo verificador de código para gerar o desafio do código. Você também pode criar o seu, desde que ele esteja em conformidade com o padrão rfc763666.
-
Na solicitação POST de token para
https://{identity_baseURL}/connect/token
, você precisa incluircode_verifier
(uma cadeia original usada para gerarcode_challenge
) no corpo da solicitação.A resposta inclui um token de acesso que o aplicativo pode usar para acessar recursos de usuários até que o token expire (uma hora).grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&code_verifier={code_verifier}
grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&code_verifier={code_verifier}
Depois que o aplicativo tiver um token de acesso, ele pode usar o token para acessar recursos permitidos, limitado aos escopos selecionados, até que o token expire (uma hora).
odata/Machines
que usa um token de acesso no cabeçalho Autorização, onde o token de acesso contém o escopo OR.Machines
na declaração de escopo.
curl -X GET "https://{yourDomain}/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
curl -X GET "https://{yourDomain}/odata/Machines"
-H "Authorization: Bearer {access_token}" -H "accept: application/json"
Os tokens de acesso expiram em uma hora. O aplicativo externo pode obter um novo token de acesso sem interação do usuário trocando um token de atualização por ele. Tanto os aplicativos confidenciais e não confidenciais externos podem solicitar um token de atualização. No entanto, o fluxo de credenciais do cliente não é compatível com tokens de atualização. No fluxo de credenciais do cliente, os tokens de acesso são concedidos diretamente sem tokens de atualização. Quando os clientes precisam de um novo token, eles devem se autenticar novamente usando suas credenciais.
Os tokens de atualização também são válidos para um único uso e eles expiram após 60 dias.
offline_access
no parâmetro scope
da solicitação de autorização para que o código de autorização possa ser usado em uma solicitação de token para obter um token de atualização.
Envie uma solicitação POST com o código de autorização para o endpoint do token
https://{yourDomain}/identity/connect/token
.
application/x-www-form-urlencoded
.
A solicitação devolve um novo token de acesso e um token de atualização:
{
"access_token": "{access_token}",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "{refresh_token}",
"scope": "OR.Machines OR.Robots offline_access"
}
{
"access_token": "{access_token}",
"expires_in": 3600,
"token_type": "Bearer",
"refresh_token": "{refresh_token}",
"scope": "OR.Machines OR.Robots offline_access"
}
https://{yourDomain}/identity/connect/token
usando o tipo de concessão refresh_token
.
application/x-www-form-urlencoded
.
{
"grant_type": "refresh_token",
"client_id": "{app_id}",
"client_secret": "{app_secret}",
"refresh_token": "{existing_refresh_token}"
}
{
"grant_type": "refresh_token",
"client_id": "{app_id}",
"client_secret": "{app_secret}",
"refresh_token": "{existing_refresh_token}"
}
client_secret
do corpo da solicitação.
A resposta devolve um novo token de acesso e um novo token de atualização.
O token de atualização existente não é mais válido após o uso, portanto, certifique-se de usar o novo token de atualização que você recebeu.
application/x-www-form-urlencoded
para qualquer solicitação para os endpoints do Identity Server. Se você estiver fazendo solicitações programáticas, isso não será necessário.
Camada do servidor de identidade | Endpoint | Description |
---|---|---|
Discovery | https://{yourDomain}/identity/.well-known/openid-configuration | Use este endpoint para recuperar metadados sobre sua instância do Identity Server. |
Autorização | https://{yourDomain}/identity/connect/authorize | Use este terminal para solicitar tokens ou códigos de autorização por meio do navegador. Este processo inclui autenticação do usuário final e, opcionalmente, consentimento. |
Token | https://{yourDomain}/identity/connect/token | Use esse ponto de extremidade para solicitar tokens de forma programática.
Observe que, para esse endpoint, o tipo de conteúdo deve ser
application/x-www-form-urlencoded .
|
- Pré-requisitos
- Autenticação e autorização de aplicativos externos
- Qual tipo de concessão de autorização usar
- Declaração de escopos
- Aplicativos confidenciais com escopos de aplicativos (fluxo de credenciais do cliente)
- Aplicativos confidenciais com escopos de usuário (fluxo de código de autorização)
- Aplicativos não confidenciais com escopos de usuário (código de autorização com fluxo PKCE)
- Usando o Token de Acesso
- Obtendo um token de atualização
- Obtendo um token de atualização
- Obtendo um novo token de atualização e um novo token de acesso
- Endpoints do UiPath® Identity Server