Aplicaciones externas (OAuth)

These instructions are intended for developers who maintain the integration between UiPath® products and external applications using the UiPath® functionality based on the OAuth framework.

Consejo:

Antes de comenzar:

• La aplicación externa ya debe estar registrada por los Administratorsde la organización.
• 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
Confidencial	Aplicación	Credenciales de Cliente
no confidenciales	Usuario	Código de autorización con PKCE

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.

The authorization server for accessing UiPath® resources is the UiPath® Identity Server, which supports the OAuth 2.0 framework.

Acceso detallado

Para aplicaciones confidenciales con acceso detallado configurado a través de Orchestrator debes solicitar el ámbito OR.Default , lo que permite a la aplicación comprobar en busca de asignaciones realizadas en Orchestrator, a nivel de tenant y carpeta. La aplicación puede entonces acceder a los recursos a los que se les haya concedido acceso en esos tenants y carpetas.

Por ejemplo, si desea que una aplicación externa vea trabajos y máquinas en todos los tenants de la organización. Al aprovechar la funcionalidad de acceso detallado, también puede configurar la aplicación para ver las colas en una carpeta.

Para obtener el token de acceso para tu aplicación externa en este escenario, deberías solicitar los ámbitos siguientes: OR.Jobs.Read, OR.Machines.Read, OR.Default. Esto le otorga permisos de Ver sobre trabajos y máquinas en todos los tenants en la organización, y también Ver en Colas en la carpeta, siempre que la aplicación externa haya sido asignada a ella y se le hayan otorgado los permisos necesarios mediante un rol.

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. The external application sends an authorize request to the UiPath® Identity Server authorize endpoint to get the authorization code.

   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
   https://{yourDomain}/identity_/connect/authorize	El punto final de autorización de Identity Server.
   response_type=code	Especifica que la aplicación solicita un código de autorizació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	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 la documentación de la API del recurso para obtener los valores de ámbito que necesitas. Por ejemplo:
   redirect_uri	Contains the URL where UiPath® Identity Server redirects the authorize request after the authorization code is granted.

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.
   Ejemplo de redirección de solicitud de autorización: {redirect_url}?code={authorization_code}&scope={scopes}el código de autorización solo se puede utilizar una vez.
4. The external application requests an access token from UiPath® Identity Server using the authorization code and authentication details (client_id and client_secret). These are included in the body of a POST request to the token endpoint https://{yourDomain}/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).

Código de autorización con PKCE

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 usa el código de autorización, excepto que en la solicitud de autorización debe incluir los siguientes parámetros de consulta de 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 el estándar rfc7636 .

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

En la solicitud de token POST a https://{yourDomain}/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: https://{yourDomain}/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 "https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/odata/Machines"
  -H "Authorization: Bearer {access_token}" -H  "accept: application/json"

Nota: Consulta la API Swagger de Orchestrator en https://{yourDomain}/{organizationName}/{tenantName}/orchestrator_/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. Tanto las aplicaciones externas confidenciales como las no confidenciales pueden solicitar un token de actualización.

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.

UiPath® Identity Server Endpoints

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.