Acesso a recursos da UiPath usando aplicativos externos

Estas instruções destinam-se a desenvolvedores que mantêm a integração entre produtos UiPath e aplicativos externos em um ambiente com uma instalação local do Orchestrator ou uma instalação auto-hospedada do Orchestrator.

Dica:

Antes de você começar:

• O aplicativo externo já deve estar registrado em Aplicativos externos pelo administrator da organização.
• Obtenha os detalhes do registro do administrador da organização.

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	Código de autorização (instruções)
Confidencial	Aplicativo	Credenciais do cliente (instruções)
não confidencial	Usuário	Código de autorização com PKCE (instruções)

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.

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.

   {BaseURL}/identity/connect/authorize?
   response_type=code&
   client_id={app_id}&
   scope={scopes}&
   redirect_uri={redirect_url}

   • {BaseURL}/identity/connect/authorize é o endpoint de autorização do Identity Server.
   • response_type=code especifica que o aplicativo está solicitando um código de autorização.
   • client_id deve conter o ID do aplicativo (mostrado 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.
     Observação: verifique o ponto de extremidade no Swagger para obter os valores de escopo de que você precisa. Por exemplo:

     

   • redirect_uri contém a 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 no Orchestrator para autenticar a solicitação de autorização. A solicitação falha se:
   • o usuário não está no tenant no qual 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ê só pode usar o código de autorização 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 {BaseURL}/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). Consulte Uso do Token de Acesso e Obtenção de um token de atualização para mais informações.

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, desde que ele esteja em conformidade com o padrão rfc763666.

{BaseURL}/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 {BaseURL}/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 Uso do 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: {BaseURL}/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 "{OrchestratorURL}/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l

Nota: Consulte o Swagger da API do Orchestrator no {OrchestratorURL}/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 atualização por ele.

Os tokens de atualização também são válidos para um único uso e eles expiram após 60 dias.

Tanto os aplicativos confidenciais e não confidenciais externos podem solicitar um token de atualização. Para fazer isso, eles devem 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 do token para obter um token de atualização.

Para obter um token de atualização, envie uma solicitação POST com o código de autorização para o endpoint do token

{BaseURL}/identity/connect/token.

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" 
}

Para obter um novo token de atualização e um novo token de acesso, envie uma solicitação POST para o endpoint do token {BaseURL}/identity/connect/token usando o tipo de concessão refresh_token.

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}"
}

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.

Discovery: {BaseURL}/identity/.well-known/openid-configuration

Autorização: {BaseURL}/identity/connect/authorize

Token: {BaseURL}/identity/connect/token