Aplicativos externos (OAuth)

Estas instruções destinam-se a desenvolvedores que mantêm a integração entre produtos UiPath e aplicativos externos usando a funcionalidade UiPath com base na estrutura do OAuth.

Dica:

Antes de você começar:

• O aplicativo externo já deve ter sido registrado por um Administratorsda organização.
• Obtenha os detalhes do registro do administrador da organização.

Visão geral

Os aplicativos externos ao UiPath Platform podem conceder acesso aos recursos da UiPath sem ter que compartilhar credenciais de usuários. Usando a estrutura do OAuth, os administradores da organização podem delegar autorização para aplicativos externos. Após serem registrados, esses aplicativos poderão fazer chamadas de API para aplicativos da UiPath ou para os recursos que você incluir no escopo do registro.

Como administrador, para definir escopos de aplicativos externos em:

• nível da organização (Admin > Apps externos > OAuth) - você atribui permissões a ela, como OR.Machines.Read - isso concede acesso de leitura às máquinas dentro de todos os tenants da organização.

• tenant (Orchestrator > Tenant > Gerenciar acesso) ou nível de pasta (Orchestrator > Pasta > Configurações > Gerenciar acesso) - você adiciona o aplicativo ao tenant ou pasta desejado, atribuindo-lhe uma função. Essa ação configura escopos mais granulares.

  Por exemplo, se um aplicativo for adicionado ao tenant EMEA e à pasta Finanças com a permissão Assets.View, ele ganha permissões de visualização para ativos dentro do tenant EMEA e pasta Finanças.

Observação:

Para que os desenvolvedores usem esses aplicativos externos, eles devem declarar certos escopos na solicitação.

Acesso fino

Dependendo das permissões com as quais um aplicativo externo foi registrado, os desenvolvedores devem declarar certos escopos para usá-los. Há três opções possíveis:

1. Uma permissão específica, como OR.Machines.View, para visualizar todas as máquinas na organização.
2. Uma combinação de uma permissão específica e OR.Default, por exemplo OR.Machines.View + OR.Default - para solicitar máquinas de visualização em toda a organização e para pesquisar permissões granulares dentro de tenants e pastas específicos.
3. Apenas OR.Default - para solicitar exclusivamente permissões granulares dentro de tenants e pastas específicos.

Usando os diferentes tipos de concessões

Após o aplicativo externo ser registrado, você deve implementar o mecanismo de autorização adequado para o aplicativo externo, com um tipo adequado de concessão para o escopo registrado, para que o aplicativo externo possa recuperar um token de acesso.

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

Tipo de Aplicativo	Escopo	Tipo de concessão necessário
Confidencial	Usuário	Authorization Code
Confidencial	Aplicativo	Client Credentials
não confidencial	Usuário	Código de autorização com o PKCE

Observação:

Se um aplicativo confidential foi concedido tanto para usuários quanto para aplicativos, você deve implementar ambos os tipos de concessã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.

O servidor de autorização para acesso dos recursos da UiPath é o UiPath Identity Server, o qual é compatível com a framework do OAuth 2.0.

Acesso fino

Para aplicativos confidenciais com acesso fino configurados por meio do Orchestrator, você precisa solicitar o escopo OR.Default, que permite que o aplicativo verifique as atribuições feitas no Orchestrator, nos níveis da pasta e do tenant. Então, o aplicativo poderá acessar os recursos aos quais recebeu acesso nesses tenants e pastas.

Por exemplo, você quer que um aplicativo externo visualize trabalhos e máquinas em todos os tenants na organização. Ao aproveitar a funcionalidade de acesso granular, você também pode configurar o aplicativo para visualizar filas em uma pasta.

Para obter o token de acesso para seu app externo nesse cenário, você deve solicitar os seguintes escopos: OR.Jobs.Read, OR.Machines.Read, OR.Default. Isso concede a seu app permissões para Visualizar trabalhos e máquinas em todos os tenants na organização, e também para Visualizar filas na pasta, desde que o app externo tenha sido atribuído a ela e tenha concedido as permissões necessárias por meio de uma função.

Authorization Code

Use esse tipo de concessão quando o aplicativo registrado for do tipo confidencial e a solicitação for para o escopo do usuário.

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

1. O aplicativo externo envia uma solicitação de autorização para o endpoint de autorização do UiPath Identity Server, para obter o código da autorização.

   https://cloud.uipath.com/identity_/connect/authorize?
   response_type=code&
   acr_values={value}&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   Opção	Description
   https://cloud.uipath.com/identity_/connect/authorize	O ponto de extremidade de autorização do Identity Server.
   response_type=code	Especifica que o aplicativo está solicitando um código de autorização.
   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 ACR. acr_values=tenantName:{target organization name} — o nome da organização atua como um valor ACR.
   client_id	Deve conter o ID do aplicativo (exibido na página de Aplicativos externos).
   scope	Contém os escopos solicitados pelo aplicativo, delimitado por um espaço; por exemplo: OR.Machines OR.Robots. Nota: Verifique o endpoint na documentação da API do recurso para obter os valores de escopo que você precisa. Por exemplo:
   redirect_uri	Contém o URL onde o UiPath Identity Server redirecionará 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.
   Exemplo de redirecionamento de solicitação de autorização: {redirect_url}?code={authorization_code}&scope={scopes}Você pode usar o código de autorização apenas uma vez.
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://cloud.uipath.com/identity_/connect/token.

   {
       "grant_type": "authorization_code",
       "code": "{authorization_code}",
       "redirect_uri": "{redirect_url}",
       "client_id": "{app_id}",
       "client_secret": "{app_secret}"
   }

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

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

   Observação:

   O client_secret é retornado após registrar um aplicativo confidencial em Aplicativos Externos.

   Para um aplicativo não confidencial, use code_challenge e code_challenge_method em vez do client_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}"
   }

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

Código de autorização com o PCKE

Use esse tipo de concessão se o aplicativo registrado for do tipo não confidencial e a solicitação for para escopo do usuário.

O fluxo é o mesmo ao usar o código de autorização, exceto que na solicitação de autorização é preciso incluir os seguintes parâmetros de consulta de solicitação:

• code_challenge_method, que deve ser S256
• code_challenge, uma cadeia criptográfica 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 próprio, desde que esteja em conformidade com o padrão rfc7636 .

https://cloud.uipath.com/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

Na solicitação POST de token para https://cloud.uipath.com/identity_/connect/token, você precisa incluir code_verifier (uma cadeia original usada para gerar code_challenge) no corpo da solicitação.

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

{ 
    "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). Consulte Usando o Token de Acesso e Obtenção de um token de atualização para mais informações.

Client Credentials

Para que aplicativos confidenciais acessem o escopo de aplicativos, o aplicativo externo solicita um token de acesso enviando uma solicitação POST que inclui o client_id e o client_secret para o endpoint do token do Identity Server: https://cloud.uipath.com/identity_/connect/token.

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

{
    "grant_type": "client_credentials",
    "client_id": "{app_id}",
    "client_secret": "{app_secret}",
    "scope": "{scopes}"
}

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 de autorização, onde o token de acesso contém o escopo OR.Machines na declaração do escopo.

curl -X GET "https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

Nota: Consulte o Swagger da API do Orchestrator no https://cloud.uipath.com/{organizationName}/{tenantName}/orchestrator_/swagger/index.html para obter informações sobre as API disponíveis.

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 externos confidenciais quanto os não confidenciais podem solicitar um token de atualização.

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://cloud.uipath.com/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://cloud.uipath.com/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://cloud.uipath.com/identity_/.well-known/openid-configuration	Use este endpoint para recuperar metadados sobre sua instância do Identity Server.
Autorização	https://cloud.uipath.com/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://cloud.uipath.com/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.