Aplicaciones externas (OAuth)

Como desarrollador que trabaja en la integración de productos UiPath con aplicaciones externas, eres responsable de tareas como la gestión de cambios de ámbito, la gestión de tokens de acceso y tokens de actualización y el mantenimiento de la integración entre la aplicación externa y los recursos de UiPath. La siguiente guía te orienta a través de estas operaciones.

OAuth ofrece una selección de bibliotecas que puedes aprovechar para simplificar la autenticación, la autorización, la delegación y la seguridad de las llamadas a la API. Puedes acceder a estos recursos directamente desde el sitio web oficial de OAuth.

Requisitos previos

Como desarrollador, una vez que el administrador de la organización haya registrado tu aplicación externa en UiPath, deberás obtener los detalles de registro para autenticar tu aplicación externa con recursos de UiPath.

• El tipo de aplicación y el ID de aplicación. Si trabajas con una aplicación confidencial, también necesitarás el Secreto de la aplicación. Estos se utilizan para autenticar tu aplicación con Identity Server de UiPath, el servidor de autorización para acceder a los recursos de UiPath, que admite el marco OAuth 2.0.

• Además, debes conocer los ámbitos de la aplicación externa, que definen a qué recursos puede acceder tu aplicación externa en UiPath. Esto incluye tanto la especificación del recurso (como activos, procesos, etc.) como el nivel de permiso (lectura, escritura, edición, etc.).

Autenticar y autorizar aplicaciones externas

Una vez registrada la aplicación externa, debes implementar el mecanismo de autorización adecuado para la aplicación externa con el tipo de concesión adecuado para que la aplicación externa pueda recuperar un token de acceso.

Durante este proceso, solicita un token de acceso proporcionando el ámbito de la aplicación externa y las credenciales de la aplicación registrada (el ID de la aplicación (y el Secreto de la aplicación en el caso de las aplicaciones confidenciales)) a Identity Server. Si las credenciales son válidas, Identity Server responde emitiendo un código de autorización, que se utilizará para generar el token de acceso.

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

Tipo de aplicación	Ámbito	Tipo de concesión requerida
Confidencial	Aplicación	Credenciales de Cliente
Confidencial	Usuario	Código de autorización
Confidencial	aplicación y usuario	Credenciales de cliente y código de autorización
no confidenciales	Usuario	Código de autorización con PKCE

Nota:

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.

Declarar ámbitos

El ámbito definido por el administrador para una aplicación determina el nivel máximo de acceso que la aplicación puede alcanzar. Como desarrollador, si solicitas acceso más allá de este ámbito predefinido, tu solicitud falla. Por lo tanto, es importante asegurarse de que tus solicitudes estén dentro del ámbito definido por el administrador.

En el nivel de administrador, los permisos de la aplicación pueden ser:

• Permisos de ámbito de la organización: de forma predeterminada, cuando se registra una aplicación externa, tiene acceso de toda la organización a los recursos según los ámbitos establecidos.

• Permisos detallados: para una configuración de permisos más granular, el administrador de la organización puede asignar un rol a nivel de tenant o carpeta dentro de Orchestrator a la aplicación externa, aunque esto solo es aplicable a aplicaciones confidenciales.

En el nivel de desarrollador, la declaración de ámbitos se realiza de la siguiente manera:

• Permisos de ámbito de la organización: al declarar un ámbito especificado explícitamente como OR.Machines.View en la solicitud de token, implica que la aplicación solicita un permiso de acceso para toda la organización.
• Permisos detallados: para proporcionar a tu aplicación un acceso detallado, debes declarar OR.Default en la solicitud del token. OR.Default actúa como un ámbito de comodín, proporcionando a tu aplicación un acceso detallado que depende de su rol asignado en tenants o carpetas específicas.

Por ejemplo, supongamos que quieres que tu aplicación tenga acceso a toda la organización para ver todas las máquinas, así como permisos exclusivos a un nivel más granular dentro de tenants y carpetas definidos. En ese caso, puedes declarar los ámbitos como OR.Machines.View y OR.Default. Esta declaración combinada permite que tu aplicación externa funcione tanto en el nivel de organización como en tenants o carpetas específicas de Orchestrator.

Comprueba el punto final en la documentación de API del recurso para obtener los valores de ámbito que necesitas. Por ejemplo:

Aplicaciones confidenciales con ámbitos de aplicación (flujo de credenciales de cliente)

Las aplicaciones confidenciales con ámbitos de aplicación realizan el flujo de credenciales de cliente contra el UiPath Identity Server.

El diagrama muestra el flujo de credenciales de cliente OAuth. El cliente envía la credencial a Identity Server y recibe el token de acceso. Con el token verificado, se proporciona acceso a los recursos API.

Para obtener una comprensión detallada del flujo OAuth que utiliza las credenciales de cliente, consulta el documento RFC 6749.

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

1. La aplicación externa solicita un token de acceso enviando una solicitud POST que incluye client_id y client_secret al punto final del token de Identity Server: https://{yourDomain}/identity/connect/token:

   grant_type=client_credentials&client_id={app_id}&client_secret={app_secret}&scope={scopes}

   Campo	Descripción
   client_id	Especifica el identificador único asignado a la aplicación durante su registro. Debe contener el ID de la aplicación (proporcionado por el administrador).
   client_secret	Especifica información confidencial, como una contraseña, que se proporciona a las aplicaciones confidenciales en el momento de su registro. Este campo se utiliza junto con el client_id para autenticar la aplicación cuando emite solicitudes al Identity Server. Debe contener el secreto de la aplicación (proporcionado por el administrador).
   scope	Especifica los ámbitos solicitados por la aplicación, delimitados por un espacio; por ejemplo: OR.Machines.View OR.Default. Usa OR.Default para conceder acceso controlado y personalizado dentro de tenants o carpetas específicas. Los permisos reales que obtiene la aplicación se determinan en función de dónde se asigna la aplicación dentro de los tenants o carpetas por el administrador. Utiliza ámbitos explícitos como OR.Machines.View para conceder acceso amplio en toda la organización a ciertos recursos.

2. La aplicación externa recibe una respuesta que contiene el token de acceso:

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

   La aplicación puede utilizar el token de acceso para acceder a los recursos del usuario hasta que el token caduque (una hora).

Aplicaciones confidenciales con ámbitos de usuario (flujo de código de autorización)

Para aplicaciones externas confidenciales con ámbitos de usuario, realizas el flujo de código de autorización contra Identity Server.

El diagrama muestra el flujo de código de autorización OAuth. El cliente solicita autorización de Identity Server. A continuación, se solicita al usuario que inicie sesión. Si se realiza correctamente, Identity Server proporciona el código de autorización. El cliente utiliza este código y secreto de cliente para recuperar un token de acceso. Con el token verificado, se proporciona acceso a los recursos API.

Para obtener una comprensión detallada del flujo OAuth que utiliza códigos de autorización, consulta el documento RFC 6749.

Nota: si utilizas Postman o una herramienta similar, utiliza el tipo de contenido application/x-www-form-urlencoded

1. La aplicación externa envía una solicitud de autorización para obtener el código de autorización al punto final de autorización de Identity Server https://{yourDomain}/identity/connect/authorize?:

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

   Opción	Descripción
   acr_values	Permite a Identity Server aplicar una política de autenticación en función de la organización a la que pertenece el usuario. Puede adoptar diferentes valores: acr_values=tenant:{target organization GlobalId}: el ID de la organización sirve como valor ACR. acr_values=tenantName:{target organization name}: el nombre de la organización actúa como valor ACR.
   client_id	Especifica el identificador único asignado a la aplicación durante su registro. Debe contener el ID de la aplicación (como lo proporciona el administrador).
   client_secret	Especifica información confidencial, como una contraseña, que se proporciona a las aplicaciones confidenciales en el momento de su registro. Este campo se utiliza junto con el client_id para autenticar la aplicación cuando emite solicitudes al Identity Server. Debe contener el Secreto de la aplicación (como lo proporciona el administrador).
   scope	Especifica los ámbitos solicitados por la aplicación, delimitados por un espacio; por ejemplo: OR.Machines.View OR.Default. Utiliza OR.Default para conceder acceso controlado y personalizado dentro de tenants o carpetas específicas. Los permisos que obtiene la aplicación se determinan en función de los tenants o carpetas en las que el administrador asigna la aplicación. Utiliza ámbitos explícitos como OR.Machines.View para conceder acceso amplio a ciertos recursos.
   redirect_uri	Especifica la URL donde Identity Server redirecciona la solicitud de autorización después de que se conceda el código de autorización

2. Debe iniciar sesión un usuario para autenticar la solicitud de autorización.

   La solicitud falla si:

   • el usuario no está en la organización 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. Solo puedes utilizar el código de autorización una vez.
   Ejemplo de redirección de solicitud de autorización: {redirect_url}?code={authorization_code}&scope={scopes}
4. La aplicación externa solicita un token de acceso de 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 https://{yourDomain}/identity/connect/token.

   grant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_url}&client_id={app_id}&client_secret={app_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}"
   }

La aplicación puede utilizar el token de acceso para acceder a los recursos del usuario hasta que el token caduque (una hora).

Aplicaciones no confidenciales con ámbitos de usuario (código de autorización con flujo PKCE)

Para una aplicación no confidencial con ámbitos de usuario, realizas el código de autorización con el flujo PKCE. Para obtener una comprensión detallada del flujo OAuth que utiliza código de autorización con PKCE, consulta el documento RFC 7636.

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

1. La aplicación externa envía una solicitud de autorización para obtener el código de autorización al punto final 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

   Opción	Descripción
   client_id	Especifica el identificador único asignado a la aplicación durante su registro. Debe contener el ID de la aplicación (como lo proporciona el administrador).
   scope	Especifica los ámbitos solicitados por la aplicación, delimitados por un espacio; por ejemplo: OR.Machines.View.
   redirect_uri	Especifica la URL donde UiPath Identity Server redirecciona la solicitud de autorización después de que se haya concedido el código de autorización.
   code_challenge_method	Especifica el método utilizado para codificar code_verifier para el code_challenge. El valor para este campo debe ser S256, lo que significa que code_verifier debe ser hash utilizando SHA256 y codificado en base64url para crear el code_challenge.
   code_challenge	Una cadena criptográficamente aleatoria derivada de code_verifier, utilizada para conectar la solicitud de autorización a 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.

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

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

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

Aquí hay una solicitud de muestra a la API odata/Machines que utiliza un token de acceso en el encabezado de Autorización, donde el token de acceso contiene ámbito OR.Machines en la reclamación de ámbito.

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

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. Tanto las aplicaciones externas confidenciales como las no confidenciales pueden solicitar un token de actualización. Sin embargo, el flujo de credenciales de cliente no admite tokens de actualización. En el flujo de credenciales de cliente, los tokens de acceso se conceden directamente sin tokens de actualización. Cuando los clientes necesitan un nuevo token, deben volver a autenticarse utilizando sus credenciales.

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

Para solicitar un token de actualización, debes incluir offline_access en el parámetro scope de la solicitud de autorización para que el código de autorización pueda usarse en una solicitud de token para obtener un token de actualización.

Obtener un token de actualización

Envía una petición POST con el código de autorización al punto de conexión del token

https://{yourDomain}/identity/connect/token.

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

Obtener un nuevo token de actualización y un nuevo token de acceso

Envía una solicitud POST al punto de conexión del token https://{yourDomain}/identity/connect/token utilizando el tipo de concesión refresh_token.

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

Nota: Si la aplicación externa no es confidencial y utiliza el código de autorización con el tipo de concesión PKCE, elimina el parámetro client_secret del cuerpo de la solicitud.

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

Capa de servidor de identidad	PuntoFinal	Descripción
Discovery	https://{yourDomain}/identity/.well-known/openid-configuration	Usa este punto final para recuperar metadatos sobre tu instancia de Identity Server.
Autorización	https://{yourDomain}/identity/connect/authorize	Utilice este punto final para solicitar tokens o códigos de autorización a través del navegador. Este proceso incluye la autenticación del usuario final y, de forma opcional, el consentimiento.
Token	https://{yourDomain}/identity/connect/token	Usa este extremo para solicitar tokens mediante programación. Ten en cuenta que para este punto final, el tipo de contenido debe ser application/x-www-form-urlencoded.