Acceder a recursos de UiPath mediante aplicaciones externas

Estas instrucciones están destinadas a desarrolladores que mantienen la integración entre los productos de UiPath y las aplicaciones externas en un entorno con una instalación local de Orchestrator o una instalación autohospedada de Orchestrator.

Consejo:

Antes de comenzar:

• El administrador de la organización debe haber registrado ya la aplicación externa en Aplicaciones externas.
• Obtén los datos de registro del administrador de la organización.

Cómo utilizar los diferentes tipos de concesión

Después de registrar la aplicación externa, debes implementar el mecanismo de autorización adecuado para la aplicación externa, con el tipo de concesión apropiado para el ámbito permitido, de modo que la aplicación externa pueda recuperar un token de acceso.

Qué tipo de concesión de autorización utilizar:

Tipo de aplicación	Ámbito	Tipo de concesión requerida
Confidencial	Usuario	Código de autorización (instrucciones)
Confidencial	Aplicación	Credenciales de cliente (instrucciones)
no confidenciales	Usuario	Código de autorización con PKCE (instrucciones)

Nota:

Si a una aplicación confidencial se le concedió tanto el ámbito de usuario como el de aplicación, debes implementar ambos tipos de concesión.

Cuando el nombre del ámbito es el mismo tanto en el ámbito de usuario como en el de aplicación, como en el caso de Orchestrator, el tipo de concesión que se utiliza determina si el recurso se llama en el ámbito de usuario o en el de aplicación.

El servidor de autorización para acceder a los recursos de UiPath es UiPath Identity Server, que soporta el marco OAuth 2.0.

Código de autorización

Utiliza este tipo de concesión cuando la aplicación registrada es del tipo confidencial y la solicitud es de ámbito de usuario.

Con este tipo de concesión, el flujo es el siguiente:

1. La aplicación externa envía una solicitud de autorización al punto final de autorización de UiPath Identity Server para obtener el código de autorización.

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

   • {BaseURL}/identity/connect/authorize es el punto de conexión de la autorización de Identity Server.
   • response_type=code especifica que la aplicación solicita un código de autorización.
   • client_id debe contener el ID de la aplicación (mostrado en la página de Aplicaciones externas).
   • scope: contiene los ámbitos solicitados por la aplicación, delimitados por un espacio; por ejemplo OR.Machines OR.Robots.
     Nota: consulta el punto final en Swagger para obtener los valores de ámbito que necesitas. Por ejemplo:

     

   • redirect_uri contiene la URL a la que el UiPath Identity Server redirige la solicitud de autorización después de que se conceda el código de autorización.
2. Debe iniciar sesión en Orchestrator un usuario para autenticar la solicitud de autorización. La solicitud falla si:
   • el usuario no está en el tenant donde se registró la aplicación externa

   • para algunos recursos, el usuario conectado no tiene los permisos necesarios para el ámbito de la solicitud

3. La aplicación externa recibe el código de autorización. Ejemplo de redirección de solicitud de autorización: {redirect_url}?code={authorization_code}&scope={scopes}.
   Solo puedes utilizar el código de autorización una vez.
4. La aplicación externa solicita un token de acceso a UiPath Identity Server utilizando el código de autorización y los detalles de autenticación (client_id y client_secret). Se incluyen en el cuerpo de una solicitud POST al punto de conexión del token {BaseURL}/identity/connect/token.

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

   Si utilizas Postman o alguna herramienta similar, utiliza el tipo de contenido application/x-www-form-urlencoded.

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

   Nota:

   Se devuelve client_secret después de registrar una aplicación confidencial en Aplicaciones externas.

   Para una aplicación no confidencial, utiliza code_challenge y code_challenge_method en lugar de la etiqueta client_secret.
5. La aplicación externa recibe una respuesta que contiene el token de acceso, por ejemplo:

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

Ahora la aplicación puede utilizar el token de acceso para acceder a los recursos del usuario hasta que el token expire (una hora). Para más información, consulta la sección Uso del token de acceso y Obtención de un token de actualización.

Código de autorización con PCKE

Utiliza este tipo de concesión cuando la aplicación registrada es del tipo confidencial y la solicitud es de ámbito de usuario.

El flujo es el mismo que cuando se utiliza el código de autorización, excepto que en la solicitud de autorización hay que incluir los siguientes parámetros de consulta de la solicitud:

• code_challenge_method, que debe ser S256
• code_challenge una cadena criptográficamente aleatoria derivada del verificador de código, utilizada para conectar la solicitud de autorización con la solicitud de token.

Debe utilizar un algoritmo verificador de código para generar el desafío de código. También puedes crear el tuyo propio, siempre que cumpla con el estándar rfc7636.

{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

En la solicitud de token POST a {BaseURL}/identity/connect/token, es necesario incluir code_verifier (la cadena original utilizada para generar code_challenge) en el cuerpo de la solicitud.

Si utilizas Postman o una herramienta similar, utiliza el tipo de contenido application/x-www-form-urlencoded.

{ 
    grant_type: "authorization_code" 
    code: "{authorization_code}" 
    redirect_uri: "{redirect_url}" 
    client_id: "{app_id}" 
    code_verifier: "{code_verifier}" 
}

La respuesta incluye un token de acceso que la aplicación puede utilizar para acceder a los recursos del usuario hasta que el token caduque (una hora). Para más información, consulta la sección Uso del token de acceso y Obtención de un token de actualización.

Credenciales de Cliente

Para que las aplicaciones confidenciales accedan al ámbito de aplicación, la aplicación externa solicita un token de acceso enviando una solicitud POST que incluye el client_id y client_secret al punto de conexión del Identity Server: {BaseURL}/identity/connect/token.

Si utilizas Postman o una herramienta similar, utiliza el tipo de contenido application/x-www-form-urlencoded.

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

Uso del token de acceso

Cuando la aplicación tiene un token de acceso, puede utilizarse para acceder a los recursos permitidos, limitados a los ámbitos seleccionados, hasta que el token caduque (una hora).

A continuación se muestra un ejemplo de solicitud a la API odata/Machines que utiliza un token de acceso en la cabecera Authorization, donde el token de acceso contiene el ámbito OR.Machines en la solicitud de ámbito.

curl -X GET "{OrchestratorURL}/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"l

Nota: Consulta la API Swagger de Orchestrator en {OrchestratorURL}/swagger/index.html para obtener información sobre las API disponibles.

Obtener un token de actualización

Los tokens de acceso caducan en una hora. La aplicación externa puede obtener un nuevo token de acceso sin la interacción del usuario intercambiando un token de actualización por él.

Los tokens de actualización también son válidos para un solo uso y caducan a los 60 días.

Tanto las aplicaciones externas confidenciales como las no confidenciales pueden solicitar un token de actualización. Para ello, deben incluir offline_access en el parámetro scope de la solicitud de autorización para que el código de autorización pueda ser utilizado en una solicitud de token para obtener un token de actualización.

Para obtener un token de actualización, envía una solicitud POST con el código de autorización al punto de conexión del token.

{BaseURL}/identity/connect/token.

Si utilizas Postman o una herramienta similar, utiliza el tipo de contenido application/x-www-form-urlencoded.

La solicitud devuelve un nuevo token de acceso y un token de actualización:

{ 
    "access_token": "{access_token}", 
    "expires_in": 3600, 
    "token_type": "Bearer", 
    "refresh_token": "{refresh_token}", 
    "scope": "OR.Machines OR.Robots offline_access" 
}

Para obtener un nuevo token de actualización y un nuevo token de acceso, envía una solicitud POST al punto de conexión {BaseURL}/identity/connect/token del token utilizando el tipo de concesión refresh_token.

Si utilizas Postman o una herramienta similar, utiliza el tipo de contenido application/x-www-form-urlencoded.

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

La respuesta devuelve un nuevo token de acceso y un nuevo token de actualización.

El token de actualización existente ya no es válido después de su uso, así que asegúrate de utilizar el nuevo token de actualización que has recibido.

Puntos de conexión de UiPath Identity Server

Si utilizas Postman o una herramienta similar, utiliza el tipo de contenido application/x-www-form-urlencoded para cualquier petición a los puntos de conexión del Identity Server. Esto no es necesario si las solicitudes se realizan de forma programada.

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

Autorización: {BaseURL}/identity/connect/authorize

Token: {BaseURL}/identity/connect/token