OAuth 2.0 es un estándar diseñado para permitir que un sitio web o una aplicación accedan a recursos alojados por otras aplicaciones web en nombre de un usuario. OAuth 2.0 es ampliamente reconocido en el ámbito de la autenticación y autorización en aplicaciones web y móviles, y ofrece una forma segura de obtener autorización para acceder a recursos protegidos en nombre de un usuario.
FRACTTAL API usa OAuth 2.0 como protocolo de autenticación para garantizar la seguridad en todas las peticiones HTTP. Este tipo de autenticación ofrece dos tipos de autorización: Credenciales de Cliente y Código de autorización. Ambos tipos permiten a los clientes obtener tokens de acceso para autenticar sus solicitudes.
Configuración en Fracttal One
Para utilizar la autenticación mediante OAuth 2.0 en FRACTTAL API, es necesario configurar los Consumidores OAuth dentro de Fracttal One. Esto se puede realizar accediendo a la sección Configuración, y luego seleccionando Conexiones API en el menú lateral, y finalmente la pestaña Consumidores OAuth. Encuentre un ejemplo aquí
Es importante destacar que cada consumidor de OAuth que se configure debe estar asociado a un grupo de permisos, independientemente del tipo de autorización seleccionado. Estos grupos de permisos brindan un control granular sobre qué recursos se pueden acceder y qué acciones se pueden realizar.
Además, cada consumidor debe llevar un nombre, y de forma optativa una descripción, que permitan identificarlo para su mejor administración.
De forma adicional, existen campos configurables que variarán de acuerdo al tipo de autorización que se seleccione.
Credenciales de Cliente
Para configurar un consumidor que utilice Credenciales de Cliente como tipo de autorización, los únicos campos requeridos son el Nombre y el Grupo de permisos. Adicionalmente se puede entregar una Descripción del consumidor.
Una vez completados estos campos, al guardar la configuración se generará una Clave y un Secreto que servirán para poder obtener el token de autenticación.
Código de Autorización
Para configurar un consumidor que utilice Código de autorización como tipo de autorización, además del Nombre y el Grupo de permisos será necesario indicar una URL de redireccionamiento en el campo URL de remarcación. De forma optativa se puede entregar una Descripción del consumidor, además de indicar la URL, la URL de política de privacidad y la URL de Acuerdo de licencia de usuario final.
Una vez completados estos campos, al guardar la configuración se generará una Clave y un Secreto que servirán para poder obtener el token de autenticación.
Obtención de Token
La URL para la obtención de token es https://one.fracttal.com/oauth/token
Credenciales de Cliente
Cuando se utiliza este tipo de autorización, el token se obtiene de la siguiente forma:
curl -X POST -u "clave:secreto" https://one.fracttal.com/oauth/token -d grant_type=client_credentials
{
"access_token":"******",
"token_type":"Bearer",
"expires_in":7200,
"refresh_token":"***",
"state":"client_credentials"
}
Al ejecutar el comando, se debe reemplazar clave y secreto por los valores que se obtuvieron el configurar el consumidor de OAuth.
Código de Autorización
Cuando se utiliza este tipo de autorización, primero se sebe solicitar autorización al usuario final enviando su navegador a https://one.fracttal.com/oauth/authorize.
El redireccionamiento de retorno (o callback) incluirá el parámetro de consulta ?code={código_de_autorización}, que será necesario para obtener el token, de la siguiente forma:
curl -X POST -u "clave:secreto" https://one.fracttal.com/oauth/token -d grant_type=authorization_code -d code=código_de_autorización
{
"access_token":"*****",
"token_type":"Bearer",
"expires_in":7200,
"refresh_token":"***",
"state":"authorization_code"
}
Al ejecutar el comando, se debe reemplazar clave y secreto por los valores que se obtuvieron el configurar el consumidor de OAuth en Fracttal One, y código_de_autorización por el código obtenido en el callback del paso anterior.
Envío de solicitudes
Una vez obtenido un token de acceso, la forma recomendada y conveniente de incluirlo en tus solicitudes es enviarlo en el encabezado de la solicitud, agregando lo siguiente:
| Campo | Valor | Descripción |
|---|---|---|
Authorization | Bearer {access_token} | Token de autorización cuando se utiliza OAuth2 |
Se debe reemplazar {access_token} por el valor real del token de acceso.
Al incluir el token en la cabecera de la solicitud, es importante asegurarse de utilizar el esquema de autenticación "Bearer" para indicar que se está enviando un token de acceso. Esto permitirá que el servidor identifique y autentique correctamente la solicitud.
Actualización de token
Al utilizar FRACTTAL API, es importante tener en cuenta que los tokens de acceso tienen una duración de dos horas y caducarán después de ese período. Cuando un token de acceso caduca, se recibirá una respuesta con el código de estado 401 (No autorizado).
Para facilitar la renovación de tokens de acceso sin requerir la intervención del usuario final, las respuestas de concesión de tokens de acceso incluyen un token de actualización, en el campo "refresh_token". Este token de actualización puede utilizarse para solicitar un nuevo token de acceso, de la siguiente forma:
curl -X POST -u "clave:secreto" https://one.fracttal.com/oauth/token -d grant_type=refresh_token -d refresh_token=token_de_actualización
Se debe reemplazar token_de_actualización por el valor real del token de actualización.
Es importante utilizar el token de actualización de manera segura y asegurarse de protegerlo de accesos no autorizados, ya que su compromiso podría permitir a un tercero obtener acceso a los recursos protegidos.