Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
En esta sección, encontrarás cómo crear una cuenta de servicio para autenticarte en la plataforma Unico IDCloud
Para utilizar interacciones server-to-server, es necesario solicitar la creación de la cuenta de servicio al gerente de proyectos responsable de tu empresa enviando los siguientes datos: nombre de la empresa, nombre de la aplicación, nombre, correo electrónico y teléfono móvil del responsable de la aplicación en la empresa. Es necesario crear cuentas diferentes para los entornos de Homologación y Producción.
Tras recibir estos datos, se creará una cuenta de servicio responsable de autenticar tu aplicación y te enviaremos un correo electrónico para que se genere el par de claves para la cuenta.
Una credencial de cuenta de servicio incluye un nombre único de cuenta, un identificador de la empresa (Tenant ID) y al menos un par de claves (pública y privada). Al final de la generación de las claves, solo recibirás la clave privada (archivo .key.pem), así como el payload que debe utilizarse para generar el JWT. Este payload tendrá el siguiente formato:
Si necesitas la clave pública para configurar en tu sistema, contacta al gerente de proyectos responsable de tu cuenta. También es posible generar una clave pública mediante el siguiente comando openssl:
¿No encontraste algo o aún necesitas ayuda? Si ya eres cliente o socio, puedes ponerte en contacto a través del Centro de Ayuda.
En esta sección, encontrarás cómo realizar el proceso de autenticación en la plataforma Unico IDCloud
Después de crear y configurar una cuenta de servicio, tu aplicación debe completar las siguientes etapas:
Crear un JSON Web Token (JWT), que incluye el encabezado, el payload y la firma.
Solicitar un token de acceso (AccessToken) a la plataforma de autenticación OAuth2.
Procesar la respuesta JSON que la plataforma de autenticación devolverá.
Si en la respuesta está incluido un token de acceso, podrás utilizarlo para hacer solicitudes a las APIs de los productos de Unico a los que la cuenta de servicio tenga permisos de acceso. (Si en la respuesta no se incluye un token de acceso, tu JWT y la solicitud para obtener el token pueden estar incorrectos o la cuenta de servicio puede no tener los permisos necesarios para acceder a los recursos solicitados).
El token de acceso generado en la solicitud mencionada anteriormente tiene una validez predeterminada de 3600 segundos, aunque puede variar según la configuración de seguridad establecida para tu empresa. Cuando el token de acceso expire, tu aplicación deberá generar un nuevo JWT, firmarlo y solicitar un nuevo token de acceso a la plataforma de autenticación.
Un JWT está compuesto por tres partes: un encabezado, un payload y una firma. El encabezado y el payload son objetos JSON. Estos objetos JSON se serializan en UTF-8 y luego se codifican utilizando codificación Base64url¹. Esta codificación proporciona resistencia contra alteraciones de codificación en casos de operaciones repetidas de codificación. El encabezado, el payload y la firma se concatenan con un carácter de punto final (".").
Un JWT se compone de la siguiente forma:
El texto base para la firma se compone de la siguiente manera:
El encabezado consiste en dos campos que indican el algoritmo de firma y el formato del token. Ambos campos son obligatorios y cada campo tiene solo un valor. Las cuentas de servicio dependen del algoritmo RSA SHA-256 y del formato de token JWT. Como resultado, la representación JSON del encabezado es la siguiente:
La representación en Base64url es la siguiente:
El payload JWT contiene información sobre el JWT, incluyendo los permisos solicitados (alcances), la cuenta que solicita el acceso, el emisor, el momento en que se emitió el token y el tiempo de vida del token. La mayoría de los campos son obligatorios. Al igual que el encabezado JWT, el payload es un objeto JSON y se utiliza en la composición de la firma.
Los campos obligatorios en el JWT se muestran en la siguiente tabla. Pueden aparecer en cualquier orden dentro del payload.
Entienda cómo funciona la conversión de los campos de emisión (iat) y expiración (exp) del JWT, y vea también ejemplos de uso de los valores de los campos aquí. Además, el campo "iat" debe ser la hora actual en el formato requerido y el "exp" debe seguir la fórmula a continuación:
La representación de los campos JSON obligatorios en el payload del JWT se muestra de la siguiente manera:
La especificación JSON Web Signature (JWS)² es la mecánica que guía el cálculo de la firma para un JWT. El contenido de entrada para el cálculo de la firma es el array de bytes del siguiente contenido:
El mismo algoritmo indicado en el encabezado del JWT debe ser utilizado para el cálculo de la firma. El único algoritmo de firma soportado por la plataforma de autenticación OAuth2 es RSA utilizando SHA-256. Este se expresa como RS256 en el campo alg del encabezado del JWT.
Firme la representación UTF-8 del contenido de entrada utilizando SHA256withRSA (también conocido como RSASSA-PKCS1-V1_5-SIGN con el hash SHA-256) con la clave privada que fue creada y asociada con la cuenta de servicio (archivo .key.pem generado por la solicitud recibida por correo electrónico). El contenido de salida será un array de bytes.
La firma debe ser luego codificada en Base64url. El encabezado, el payload y la firma deben ser concatenados con el carácter de punto final. El resultado es el JWT. Debe ser de la siguiente forma:
A continuación se muestra un ejemplo del token JWT antes de la codificación en Base64url:
A continuación se muestra un ejemplo del JWT que ha sido firmado y está listo para la transmisión:
Después de la generación del JWT firmado, una aplicación puede utilizarlo para solicitar un token de acceso (Access Token). La solicitud del token de acceso es una solicitud POST HTTPS y el cuerpo debe ser URL encoded. La URL es la mostrada a continuación:
Los parámetros a continuación son obligatorios en la solicitud POST HTTPS:
Si el JWT y la solicitud del token de acceso fueron formados adecuadamente y la cuenta de servicio tiene los permisos necesarios, la respuesta de la plataforma de autenticación devuelve un objeto JSON que contiene un token de acceso. A continuación se muestra un ejemplo de respuesta de la plataforma:
El token de acceso devuelto en el campo “access_token” del objeto JSON también es un token JWT que debe ser utilizado en las APIs de los productos de unico. Si se devuelve un error en la solicitud, es posible consultar el tipo de error en la tabla de errores haciendo clic aquí.
La duración del token de acceso es variable. Su duración es especificada en el campo “expires_in”, devuelto junto con el token de acceso. Se debe utilizar el mismo token de acceso durante su validez para todas las llamadas a las APIs de los productos.
No solicite un nuevo token de acceso hasta que la validez del token actual esté llegando a su fin. Sugerimos un margen de 600 segundos (10 minutos). Para ello, ejecute el cálculo: token decodificado:
Siendo que token.exp es el timestamp de expiración del token.
Por defecto, el token enviado a la empresa tiene una duración de 1h, pero puede ser alterado. La sugerencia es siempre usar el expires_in como base y restar 600s de él para solicitar un nuevo token.
Ejemplos:
Un nuevo token de acceso puede ser solicitado cuando queden 10 minutos para su expiración.
No utilice un tiempo fijo para la obtención de un nuevo token, ya que el tiempo de duración del token recibido puede ser menor que el tiempo establecido, lo que ocasionará fallos en el uso de los servicios.
¹ De acuerdo con la RFC 4648 de codificación BaseN, el formato Base64url es similar al formato Base64, con la excepción de que el carácter = debe ser omitido, y los caracteres + y / deben ser reemplazados por - y _, respectivamente.
También es posible utilizar bibliotecas previamente establecidas para realizar la creación del JWT. Como referencia, es posible encontrar una lista de bibliotecas en el sitio .
² JSON Web Signature: .
¿No encontraste algo o aún necesitas ayuda? Si ya eres cliente o socio, puedes ponerte en contacto a través del .
¿No encontraste algo o aún necesitas ayuda? Si ya eres cliente o socio, puedes ponerte en contacto a través del .
iss
El identificador de la cuenta de servicio en la empresa.
scope
Una lista delimitada por espacios o por el signo de más + de los permisos que la aplicación está solicitando. Si todos los permisos de la cuenta son necesarios, utilizar el signo de asterisco * para ello.
aud
Dirección de la plataforma de autenticación que emite los tokens de acceso. Este valor debe ser siempre exactamente https://identityhomolog.acesso.io.
Casos recurrentes que NO funcionan:
Inclusión de una barra al final de la dirección: https://identityhomolog.acesso.io/;
Uso del protocolo HTTP en lugar de HTTPS: http://identityhomolog.acesso.io.
exp
El tiempo de expiración del token, especificado en segundos desde 00:00:00 UTC, 1 de enero de 1970. Este valor tiene un tiempo máximo de 1 hora después del momento de emisión del JWT. Este valor debe ser numérico. Casos recurrentes que NO funcionan:
Uso de comillas para delimitar el valor. Ej.: “1524161193” es una cadena de texto y no funcionará. Mientras que 1524161193 es un número y funcionará.
iat
El momento de emisión del JWT, especificado en segundos desde 00:00:00 UTC, 1 de enero de 1970. Este valor debe ser numérico.
Uso de comillas para delimitar el valor. Ej.: “1524161193” es una cadena de texto y no funcionará. Mientras que 1524161193 es un número y funcionará.
grant_type
Utilice el siguiente texto, codificado en URL si es necesario: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion
El JWT, incluida la firma.
En esta sección, encontrará los posibles errores que pueden ocurrir al intentar autenticar en la plataforma Unico IDCloud
Los errores devueltos en la solicitud pueden ser identificados a través de los códigos a continuación y tienen la siguiente estructura:
1.0.1
Verifique si el ID informado en la formación del "iss" es el ID del tenant correcto, proporcionado en la generación de la clave privada¹.
1.0.14
Verifique con la persona responsable del proyecto si la aplicación utilizada está activa.
1.1.1
El parámetro "scope" no fue informado en el payload del token JWT utilizado en la solicitud.
1.2.4
El token JWT utilizado en la solicitud ha expirado. Verifique el valor informado en el campo "exp" del payload.
1.2.5
El token JWT utilizado en la solicitud no puede ser validado. Verifique los parámetros informados y asegúrese de haberlo firmado correctamente.
1.2.6
La clave privada utilizada en la firma del token JWT utilizado en la solicitud ya no es aceptable. Solicite nuevas credenciales para la cuenta utilizada.
1.2.7
El token JWT utilizado en la solicitud ya no es aceptable, ya que ya ha sido utilizado anteriormente. Genere un nuevo token para realizar una nueva solicitud.
1.2.11
La cuenta utilizada no está activa.
1.2.14
La cuenta utilizada no tiene los permisos necesarios.
1.2.18
La cuenta utilizada ha sido temporalmente bloqueada por exceder la cantidad de intentos fallidos de autenticación.
1.2.19
La cuenta utilizada no está autorizada para impersonar otra cuenta de usuario (elimine el parámetro "sub" del payload).
1.2.20 1.2.21
Error en la decodificación del token JWT utilizado en la solicitud. Utilice un nuevo token insertando solo los campos especificados en las secciones "Campos obligatorios" y "Campos adicionales", respetando la nomenclatura, semántica y tipo de cada campo.
1.2.22
El token JWT utilizado en la solicitud tiene campos adicionales en el payload que no están permitidos. Utilice un nuevo token insertando solo los campos especificados en las secciones "Campos obligatorios" y "Campos adicionales", respetando la nomenclatura, semántica y tipo de cada campo.
1.3.1
La cuenta utilizada tiene restricciones de IP de origen.
1.3.2
La cuenta utilizada tiene restricciones de fecha/hora de acceso.
¿No encontraste algo o aún necesitas ayuda? Si ya eres cliente o socio, puedes ponerte en contacto a través del Centro de Ayuda.
En esta sección, encontrará recursos adicionales relacionados con la autenticación
En esta sección, encontrará la colección de Postman con la REST API para realizar la autenticación en la plataforma Unico IDCloud
Descargue el archivo a continuación, impórtelo en Postman y sustituya los valores de los parámetros "service_account", "tenant_id" y "secret_key" para probar la llamada.
¿No encontraste algo o aún necesitas ayuda? Si ya eres cliente o socio, puedes ponerte en contacto a través del Centro de Ayuda.
En esta sección, encontrará toda la especificación técnica sobre la forma de autenticación para utilizar las APIs REST de la plataforma IDCloud
Para utilizar la plataforma IDCloud es necesario autenticarte mediante un token de acceso, utilizando el sistema de autenticación conocido como OAuth2.
El sistema de autenticación OAuth2 de Unico soporta la interacción server-to-server entre una aplicación web y los servicios de Unico.
Para este escenario, necesitarás una cuenta de servicio, que es una cuenta impersonal que pertenece a tu aplicación y no a un usuario individual. Tu aplicación llama las APIs de Unico en nombre de la cuenta de servicio, por lo que los usuarios no están directamente involucrados. Este escenario se denomina "two-legged OAuth", o "2LO". Típicamente, una aplicación utiliza una cuenta de servicio cuando llama a las APIs de Unico para trabajar con sus propios datos en lugar de los datos del usuario.
Este es el paso cero para iniciar tu implementación, así que no saltes esta etapa.
¿No encontraste algo o aún necesitas ayuda? Si ya eres cliente o socio, puedes ponerte en contacto a través del .
