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.

Pré-requisitos

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

Autenticação e autorização de aplicativos externos

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.

Qual tipo de concessão de autorização usar

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

Observação:

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.

Declaração de escopos

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.

Por exemplo, suponha que você queira que seu aplicativo tenha acesso em toda a organização para visualizar todas as máquinas, bem como permissões exclusivas em um nível mais granular dentro de tenants e pastas definidos. Nesse caso, você pode declarar os escopos como 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:

Aplicativos confidenciais com escopos de usuário (fluxo de código de autorização)

Para aplicativos externos confidenciais com escopos de usuário, você realiza o fluxo de código de autorização no Identity Server.

O diagrama mostra o fluxo de Código de Autorização do OAuth. Cliente solicita autorização do Identity Server. O usuário é solicitado a fazer logon. Após o sucesso, o Identity Server fornece o código de autorização. O cliente usa esse código e segredo do cliente para recuperar um token de acesso. Com o token verificado, o acesso aos recursos de API é fornecido.

Para obter uma compreensão detalhada do fluxo do OAuth que utiliza códigos de autorização, consulte o documento RFC 6749.

Observação: se você estiver usando o Postman ou uma ferramenta semelhante, use o tipo de conteúdo application/x-www-form-urlencoded

1. O aplicativo externo envia uma solicitação de autorização para obter o código de autorização para o ponto de extremidade de autorização do Identity Server https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/authorize?:

   response_type=code&acr_values={value}&client_id={app_id}&scope={scopes}&redirect_uri={redirect_url}

   Opção	Description
   acr_values	Permite que o Identity Server aplique uma política de autenticação com base na organização à qual o usuário pertence. Pode adotar diferentes valores: acr_values=tenant:{target organization GlobalId} - o ID da organização serve como um valor de ACR. acr_values=tenantName:{target organization name} - o nome da organização atua como um valor de ACR.
   client_id	Especifica o identificador exclusivo atribuído ao aplicativo durante seu registro. Deve conter o ID do aplicativo (conforme fornecido pelo administrador).
   client_secret	Especifica uma informação confidencial, como uma senha, que é fornecida a aplicativos confidenciais após o registro. Esse campo é usado junto com o client_id para autenticar o aplicativo quando emite solicitações para o Identity Server. Deve conter o Segredo do aplicativo (conforme 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 que o aplicativo obtém são determinadas com base nos tenants ou pastas em que o aplicativo é atribuído pelo administrador. Use escopos explícitos, como OR.Machines.View, para conceder acesso amplo e em toda a organização a certos recursos.
   redirect_uri	Especifica a URL para onde o Identity Server redireciona a solicitação de autorização após o código de autorização ser concedido

2. Um usuário deve fazer login para autenticar a solicitação de autorização.

   A solicitação falha se:

   • o usuário não estiver na organização onde o aplicativo externo foi registrado
   • para alguns recursos, o usuário logado não tem as permissões necessárias para o escopo da solicitação.
3. O aplicativo externo recebe o código de autorização. Você só pode usar o código de autorização uma vez.
   Exemplo de redirecionamento de solicitação de autorização: {redirect_url}?code={authorization_code}&scope={scopes}
4. O aplicativo externo solicita um token de acesso do UiPath® Identity Server usando o código de autorização e os detalhes de autenticação (client_id e client_secret). Esses estão incluídos no corpo de uma solicitação POST para o endpoint do token https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token.

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_secret}

5. O aplicativo externo recebe uma resposta contendo o token de acesso, por exemplo:

   {
       "access_token":"{access_token}",
       "expires_in":3600,
       "token_type":"Bearer",
       "scope":"{scopes}"
   }

O aplicativo pode usar o token de acesso para acessar recursos de usuários até que o token expire (uma hora).

Aplicativos não confidenciais com escopos de usuário (código de autorização com fluxo PKCE)

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:

1. O aplicativo externo envia uma solicitação de autorização para obter o código de autorização para o ponto de extremidade https://govcloud.uipath.us/{organizationName}/{tenantName}/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

   Opçã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 o code_verifier para o code_challenge. O valor para esse campo deve ser S256, o que significa que o code_verifier deve ter hash usando SHA256 e codificado com base64url para criar o code_challenge.
   code_challenge	Uma string criptograficamente aleatória derivada do code_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.

2. Na solicitação POST de token para https://{identity_baseURL}/connect/token, você precisa incluir code_verifier (uma cadeia original usada para gerar code_challenge) no corpo da solicitação.

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&code_verifier={code_verifier}

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

Aplicativos confidenciais com escopos de aplicativos (fluxo de credenciais do cliente)

Os aplicativos confidenciais com escopos de aplicativos executam o fluxo de credenciais do cliente no UiPath Identity Server.

O diagrama mostra o fluxo de credenciais do cliente do OAuth. O cliente envia a credencial para o Identity Server e recebe o token de acesso. Com o token verificado, o acesso é fornecido aos recursos de API.

Para obter uma compreensão detalhada do fluxo do OAuth que utiliza Credenciais do Cliente, consulte o documento RFC 6749.

Com esse tipo de concessão, o fluxo é o seguinte:

1. O aplicativo externo solicita um token de acesso enviando uma solicitação POST, que inclui o client_id e client_secret para o ponto de extremidade do token do Identity Server: https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token:

   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 o client_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.

2. O aplicativo externo recebe uma resposta contendo o token de acesso:

   {
       "access_token":"{access_token}",
       "expires_in":3600,
       "token_type":"Bearer",
       "scope":"{scopes}"
   }

   O aplicativo pode usar o token de acesso para acessar recursos de usuários até que o token expire (uma hora).

Usando o Token de Acesso

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

Aqui está um exemplo de solicitação para a API 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://govcloud.uipath.us/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

Obtendo um token de atualização

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.

Para solicitar um token de atualização, você deve incluir 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.

Obtendo um token de atualização

Envie uma solicitação POST com o código de autorização para o endpoint do token

https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token.

Nota: Se você estiver usando o Postman ou uma ferramenta semelhante, use o tipo de conteúdo 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" 
}

Obtendo um novo token de atualização e um novo token de acesso

Envie uma solicitação POST para o endpoint do token https://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/connect/token usando o tipo de concessão refresh_token .

Nota: Se você estiver usando o Postman ou uma ferramenta semelhante, use o tipo de conteúdo application/x-www-form-urlencoded.

{
    "grant_type": "refresh_token",
    "client_id": "{app_id}",
    "client_secret": "{app_secret}",
    "refresh_token": "{existing_refresh_token}"
}

Nota: Se o aplicativo externo não for confidencial e estiver usando o código de autorização com o tipo de concessão PKCE, remova o parâmetro 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.

Endpoints do UiPath® Identity Server

Se você estiver usando o Postman ou uma ferramenta semelhante, use o tipo de conteúdo 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://govcloud.uipath.us/{organizationName}/{tenantName}/identity_/.well-known/openid-configuration	Use este endpoint para recuperar metadados sobre sua instância do Identity Server.
Autorização	https://govcloud.uipath.us/{organizationName}/{tenantName}/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://govcloud.uipath.us/{organizationName}/{tenantName}/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.