Autenticación del usuario y autorización de operaciones de consulta

Para que un usuario pueda interactuar con Fortress, es necesario que el mismo se autentique empleando 1 o 2 factores de autenticación (también llamado IdP: proveedor de identidad), según se determine en la configuración del sistema cliente original en Viafirma Fortress. Dependiendo de la configuración del cliente en Viafirma Fortress, fortress solicitará que el usuario se autentique contra uno o dos factores de autenticación de distinta categoría. Las categorías serán:

• Algo que sé → Knowledge
• Algo que tengo → Possession
• Algo que soy → Inherence

Solicitud de autorización

Para consumir los servicios proporcionados por Viafirma Fortress es necesario que el mismo se autentique con 1 o 2 factores de autenticación. Dependiendo de la configuración asociada al cliente de Viafirma Fortress, Viafirma Fortress puede solicitar un factor de autenticación o por el contrario Fortress forzará a que el usuario se autentique contra dos factores de autenticación de distinta categoría.

Para ello, Viafirma Fortress ofrece una interfaz web, disponible en:

{viafirma_fortress_url}/oauth2/v1/auth

Donde:

• viafirma_fortress_url: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortress

Una vez que se accede a esta URL, Viafirma Fortress mostrará la pantalla que permite identificar a los usuarios mediante alguno de los factores de autenticación en los que dicho usuario esté enrolado dentro de Viafirma Fortress.

Esta URL recibe una serie de parámetros, que configuran y preparan la petición de autenticación y autorización:

{viafirma_fortress_url}/oauth2/v1/auth?
scope=profile|certificate|certificates&
state=&
redirect_uri={url_de retorno_definido_en_viafirma_fortress}&
response_type=code&
client_id={codigo_del_cliente_definido_en_viafirma_fortress}&
user_code={codigo_del_usuario_en_viafirma_fortress}

Parámetro	Valor	Descripción
scope	profile / certificate / certificates	profile: Para servicios asociado a la información personal del usuario. En la cabecera de la pantalla aparecerá el siguiente mensaje: certificate: Para servicios asociados al acceso, permite consultar la información de un certificado del usuario seleccionado. En la cabecera de la pantalla aparecerá el siguiente mensaje: certificates: Para servicios asociados al acceso, permite consultar la información de todos los certificados del usuario seleccionado. En la cabecera de la pantalla aparecerá el siguiente mensaje:
state	String	Valor opcional, permite enviar un parámetro que será devuelto a la URL de retorno del cliente sin modificación alguna por parte de Viafirma Fortress
redirect_uri	URL	Debe coincidir con una de las URL de retorno definidas en Viafirma Fortress
response_type	code	El valor debe ser code para las aplicaciones web cliente
client_id	Identificador del cliente	Definido en Viafirma Fortress, identifica a la aplicación cliente que está realizado la petición
user_code	Código de usuario	Indica el usuario que debe autorizar la operación

Factores de autenticación

Viafirma Fortress, mediante los diferentes factores de autenticación en los que el usuario esté enrolado, deberá asegurar la identidad del usuario.

Los factores de autenticación activos se pueden determinar durante la instalación de Viafirma Fortress, modificando los valores de los atributos correspondientes, que siguen un patrón del tipo fortress.idp.{codigo_del_idp}.active (ver manual de instalación).

Independientemente del Proveedor de Identidad seleccionado, en caso de éxito en la autenticación, se entiende que el usuario ha autorizado la operación y se devolverá el control a la aplicación cliente, redireccionando a la URL de retorno especificada en la configuración de la petición.

Para peticiones con scope de tipo certificate, una vez que el usuario se ha autenticado correctamente usando alguno de los factores de autenticación disponibles, se mostrará la lista de certificados del usuario (custodiados por Viafirma Fortress). Una vez que el usuario ha seleccionado uno de sus certificados, se devolverá el control a la aplicación cliente.

Proveedor de Identidad: Email

Se envía al email del usuario un código único, que deberá introducir en la pantalla de autorización una vez que lo reciba.

Proveedor de Identidad: SMS

Se envía al teléfono móvil del usuario un SMS con un código único, que deberá introducir en la pantalla de autorización una vez que lo reciba.

Proveedor de Identidad: OTP

Es necesario disponer de la app (Android/IOS) que generará un código, actualizado cada cierto tiempo. El usuario deberá introducir el código en la pantalla de autorización antes de que el código expire.

Proveedor de Identidad: LDAP

Se solicitará la contraseña LDAP del usuario (la configuración del servicio LDAP se realiza durante la instalación de Viafirma Fortress).

Proveedor de Identidad: PIN

Se solicitará el código PIN que se generó y envió por e-Mail al usuario cuando se le enroló en este sistema de identificación.

Proveedor de Identidad: Password

Se solicitará la password del usuario de Viafirma Fortress.

Proveedor de Identidad: PUSH

Se solicitará un código al usuario enviado a través de una notificación PUSH a la app de su dispositivo móvil.

Obteniendo la respuesta del proceso de autenticación/autorización

Una vez que el usuario ha autorizado la operación mediante una autenticación con alguno de los factores de autenticación de Viafirma Fortress si el primer factor de autenticación ha sido delegado en el sistema cliente o contra dos factores de autenticación en Viafirma Fortress, el control vuelve al sistema cliente.

Respuestas válidas

Si el usuario aprueba el acceso (autenticándose correctamente usando cualquiera de los factores de autenticación), entonces la redirección de la página de autorización contiene un código de autorización en uno de sus parámetros (concretamente en el parámetro code).

{redirect_uri}?state=&code={codigo_de_autorizacion}

Ejemplo:

https://example.com/response?state=&code=9a3fff39-079c-45ec-b263-7d80afb18161

Respuestas en caso de error

Si el usuario no aprueba el acceso (u ocurre cualquier error durante el proceso), la redirección de la página de autorización contendrá un código de error en el parámetro error:

{redirect_uri}?error={codigo_de_error}&state=

Ejemplo:

http://example.com/?error=access_denied&state=

Obtención del token de acceso

Una vez obtenido el código de autorización es necesario canjearlo por un token de acceso. Para ello se realiza una petición REST (método POST) a Viafirma Fortress:

Método: POST
URL: {viafirma_fortress_url}/oauth2/v1/token

Donde:

• viafirma_fortress_url: URL base de la implementación de Viafirma Fortress, por ejemplo https://sandbox.viafirma.com/fortress o https://fortress.viafirma.com/fortress

Parámetros:

La repuesta a la petición será de tipo application/json, con el siguiente formato:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "user_code": "11111111H"
}

Si la solicitud de token está asociado al cliente, el resultado será

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer"
}

Descripción de la respuesta:

Acceso a las API

Una vez que se ha obtenido el token de acceso (access_token), la aplicación cliente puede acceder a los diferentes métodos del API que proporciona Viafirma Fortress enviando ese token en cada petición futura.

Dependiendo del scope seleccionado durante la petición de autorización se tendrá acceso a unas determinadas APIS:

• Para profile: Métodos para obtener la información del usuario
• Para certificate o certificates: Métodos para obtener la información del certificado o certificados seleccionados durante la fase de autorización.
• Para client: Métodos para realizar firma de documentos