Preparando para hacer una solicitud autenticada a la API
En esta sección, encontrarás cómo realizar el proceso de autenticación en la plataforma Unico IDCloud
Atualizado
Isto foi útil?
En esta sección, encontrarás cómo realizar el proceso de autenticación en la plataforma Unico IDCloud
Atualizado
Isto foi útil?
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.
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
Casos recurrentes que NO funcionan:
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á.
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:
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 jwt.io.
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:
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.
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.
² JSON Web Signature: https://tools.ietf.org/html/rfc7515.
¿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.
Dirección de la plataforma de autenticación que emite los tokens de acceso. Este valor debe ser siempre exactamente .
Inclusión de una barra al final de la dirección: ;
Uso del protocolo HTTP en lugar de HTTPS: .
