manual de integrador - soluciones virtuales de firma ... · a viafirma platform, cuál es la url de...

Manual de Integrador .NET

viafirma platform

v3.5

ÍNDICE

ÍNDICE

1. INTRODUCCIÓN ............................................................................... 5 1.1. Objetivos ..................................................................................................... 5 1.2. Referencia .................................................................................................... 5

2. GUÍA RÁPIDA .................................................................................. 5 2.1. Añadir las dependencias necesarias ...................................................................... 5 2.2. Página de acceso a la Autenticación ..................................................................... 6 2.3. Implementar evento autenticarButton_Click ........................................................... 6 2.4. Obtener los datos de respuesta ........................................................................... 8

3. CREAR APLICACIÓN .NET .................................................................... 8 3.1. Añadir dependencias necesarias .......................................................................... 9 3.2. Página de ejemplo ......................................................................................... 10 3.3. Implementar método FirmarButton_Click .............................................................. 11 3.4. Obtener datos de respuesta .............................................................................. 13

4. APLICACIÓN DE EJEMPLO ................................................................. 14 4.1. Página de inicio ............................................................................................. 14 4.2. Interacción con el Applet ................................................................................. 15 4.3. Página del Resultado de Autenticación ................................................................. 15 4.4. Opciones con Intervención del Usuario ................................................................. 16 4.5. Página del Resultado de Firma ........................................................................... 17 4.6. Ejemplo de Documento Firmado ......................................................................... 17

5. INICIALIZACIÓN DEL CLIENTE ............................................................. 18 5.1. Inicialización Standard ................................................. ¡Error! Marcador no definido. 5.2. Con URL de retorno personalizada ................................... ¡Error! Marcador no definido. 5.3. Para consumo on-demand .............................................. ¡Error! Marcador no definido.

6. MÉTODOS DEL API .......................................................................... 19

7. CONFIGURACIÓN CAPA CLIENTE ......................................................... 20 7.1. Configuraciones Posibles de la Capa de Cliente ....................................................... 20

ANEXO I : ENTREGABLES, KIT DE DESARROLLO .......................................... 22

ÍNDICE

CONTROL DE DOCUMENTO

CONTROL DE DOCUMENTO

Título: Manual de Instalación

Asunto: viafirma platform

Versión: 3.5 Fecha: 05-04-2013

Código: Revisión anterior:

Idioma: ES Núm. Páginas: 22

CONTROL DE CAMBIOS Y VERSIONES

Fecha Versión Motivo del Cambio 05-04-13 3.5 Primera versión para el soporte con viafirma platform v3.5

17-06-13 3.5 Correcciones en código y explicaciones referente a las mismas.

de 22 Manual de Integrador .NET :: viafirma platform

1. INTRODUCCIÓN

1.1. Objetivos

Este documento tiene como objetivo facilitar a usuarios integradores la utilización de las librerías de cliente de viafirma platform para dotar a sistemas externos de las funcionalidades de autenticación, firma, verificación y custodia de documentos.

1.2. Referencia

Aunque viafirma platform ofrece todos sus servicios mediante métodos estándar (Servicios Web y OpenID, etc.), hemos desarrollado un cliente para .Net que permite de una forma muy sencilla integrar aplicaciones desarrolladas en esta tecnología con los servicios que ofrece viafirma.

En este capítulo mostraremos cómo añadir las DLLs necesarias al proyecto y cómo hacer uso de los diferentes servicios de autenticación, custodia y verificación, accediendo a las distintas fuentes de verificación (CRLS, OCSP, LDAP).

2. GUÍA RÁPIDA

2.1. Añadir las dependencias necesarias

Es necesario que incorporemos al proyecto las siguientes DLLs incluidas en el Kit de desarrollo de viafirma:

• DotNetOpenId.dll

• log4net.dll

• ViafirmaClientDotNet.dll

Por otro lado también necesitaremos añadir el directorio “viafirma”, que contiene los ficheros:

• Default.aspx: con los métodos que se ejecutarán cuando el proceso de autenticación o firma finalice.


• viafirmaStyle.css: con la apariencia que viafirma platform adoptará para el proceso de autenticación o firma.

Todos estos recursos están incluidos en el kit de desarrollo. En el ANEXO I se ofrece más detalle sobre los entregables.

2.2. Página de acceso a la Autenticación

Creamos una primera página aspx en la que simplemente colocaremos un botón de acción asociado a un controlador de página que utilizará el API de viafirma platform para autenticar con certificado digital al usuario.

El código de la aplicación de ejemplo queda como el siguiente:

<%@Page Language="C#" Inherits="AplicacionEjemploClienteViafirma.Default" %> <html> <body> <h2>Ejemplo de integración Viafirma con .Net</h2> <form id="form1" runat="server"> <p>Pruebe la autenticación</p> <asp:button id="autenticarButton" runat="server" text="Autenticar al usuario con certificado o dnie" onClick="autenticarButton_Click" /> </form> </body> </html>

2.3. Implementar evento autenticarButton_Click

En este método simplemente indicaremos al cliente de Viafirma cuál es la url pública de acceso a viafirma y cuál es la url de acceso al servicio web de viafirma.

public void autenticarButton_Click(object sender,EventArgs e){ // Configuramos el cliente de viafirma ( En una aplicación real esto se realiza al iniciar la aplicación) ViafirmaClientFactory.Init("http://services.viafirma.com/viafirma/tokenConnector",http://services.viafirma.com/viafirma, "API_KEY","API_PASS"); // Obtenemos una instancia del cliente e iniciamos la autenticación ViafirmaClient clienteViafirma=ViafirmaClientFactory.GetInstance();


clienteViafirma.Autenticate(); }

Destacamos algunas líneas:

• Inicializamos: ViafirmaClientFactory.Init(urlViafirma,url_WS,"API_KEY","API_PASS");

• Instanciamos el cliente:

◦ ViafirmaClient clienteViafirma=ViafirmaClientFactory.GetInstance();

• Iniciamos la autenticación: clienteViafirma.Autenticate();

El init de evento autenticarButton_Click tendrá los siguientes parámetros:

• urlViafirma: es la dirección donde se encuentran los servicios OpenID para autenticación. Debe ser el nombre de máquina.

Ej. http://myhost/viafirma/

• urlViafirmaWS: es la dirección donde se encuentran los WebServices para firma. En este caso es recomendable que se informe la IP y no el nombre de máquina.

Ej. http://192.168.10.20:8080/viafirma/

• API-KEY / API_PASS: credenciales que podréis obtener a través de developers.viafirma.com y que son necesarias para comenzar con el desarrollo.

Con este simple código ya conseguimos que nuestra aplicación ASP.NET utilice viafirma platform para que sea ésta la responsable de solicitar, validar y recuperar el certificado o DNIe del usuario. Una vez que el proceso termine, viafirma platform devolverá el control a la aplicación ASP.NET retornando todos los datos obtenidos del certificado.


2.4. Obtener los datos de respuesta

Una vez que Viafirma obtenga los datos del certificado de usuario invocará al método ProcessResponseAutenticacion, que se encuentra en el fichero Default.aspx dentro del directorio Viafirma.

Lo único que tendremos que hacer es sobreescribir dicho método con el comportamiento deseado y recuperar todos los datos del certificado del objeto UsuarioGenericoViafirma.

En el siguiente ejemplo, si la autenticación ha sido correcta, redireccionamos al usuario a una página de destino.

<%@ Page Language="C#" Inherits="Viafirma.ViafirmaClient"%> override public void ProcessResponseAutenticaction(Viafirma.Estado

estado,Viafirma.UsuarioGenericoViafirma usuario){ Viafirma.Log.Debug("Autenticación Viafirma realizada correctamente. Resultado:"+

estado); // Aquí ya tenemos todos los datos asociados al cliente. y redireccionar al usuario a la

página destino // considerando el usuario ya autenticado. if(Viafirma.Estado.OK== estado){ Session["resultadoAutenticacion"]= usuario; Uri url=new Uri(HttpContext.Current.Request.Url,

HttpContext.Current.Response.ApplyAppPathModifier("~/resultadoAutenticacion.aspx"));

HttpContext.Current.Response.Redirect(url.AbsoluteUri); }else{ // Hay problemas al validar. } }

3. CREAR APLICACIÓN .NET

En este apartado se muestran los pasos a seguir para utilizar los servicios de firma digital (XAdES, Facturae, PDF-Signature, etc.) desde aplicaciones ASP.NET gracias a viafirma platform.


3.1. Añadir dependencias necesarias

Es necesario que incorporemos al proyecto las siguientes dlls incluidas en el Kit de desarrollo de Viafirma:

• DotNetOpenId.dll

• log4net.dll

• ViafirmaClientDotNet.dll


Por otro lado también necesitaremos añadir el directorio “viafirma”, que contiene los ficheros:

• Default.aspx: con los métodos que deben ser sobreescritos con el comportamiento específico a ejecutar cuando finalice el proceso de firma.

• viafirmaStyle.css: con la apariencia que Viafirma adoptará para el proceso de autenticación o firma. Este css puede ser adaptado a la identidad corporativa de la aplicación cliente.

• xrds.aspx: necesario para el correcto funcionamiento de la comunicación OpenID (sólo en el caso de usar este protocolo).

3.2. Página de ejemplo

Creamos una primera página aspx en la que simplemente colocaremos un botón de acción asociado a un controlador de página que utilizará el API de viafirma para firmar digitalmente un fichero de ejemplo con el certificado digital al usuario.

El código de la aplicación de ejemplo queda como el siguiente:

<%@ Page Language=”C#”Inherits=”AplicacionEjemploClienteViafirma.Default” %> <html> <body> <h2>Ejemplo de integración Viafirma con .Net</h2> <form id="form1" runat="server"> ViafirmaClientFactory.Init("http://services.viafirma.com/viafirma/tokenConnector","http://services.viafirma.com/viafirma", "API_KEY","API_PASS"); <p>Pruebe la autenticación</p> <asp:button id=”firmarButton” runat=”server” text=”Firmar un documento de ejemplo con Viafirma” onClick=”FirmarButton_Click” /> </form> </body> </html>


3.3. Implementar método FirmarButton_Click

En este método simplemente indicaremos al cliente de Viafirma cuál es la url pública de acceso a viafirma platform, cuál es la url de acceso al servicio web de viafirma platform, y registraremos un fichero para su firma.

public void FirmarButton_Click(object sender, EventArgs e){ // Configuramos el cliente de viafirma ( En una aplicación real esto se realiza al iniciar la aplicación) ViafirmaClientFactory.Init(“http://services.viafirma.com/viafirma/tokenConnector”, http://services.viafirma.com/viafirma/tokenConnector, "API_KEY","API_PASS"); // Recuperamos / Generamos el contenido del documento a firmar. //Como ejemplo generamos un txt byte[]datos_a_firmar = System.Text.ASCIIEncoding.ASCII.GetBytes(“Contenido del documento firmado”); // Enviamos a firmar el documento ViafirmaClient clienteViafirma = ViafirmaClientFactory.GetInstance(); // Registramos el documento que deseamos firmar. Obteniendo un identificador temporal. string idTemporalFirma = clienteViafirma.PrepareFirmaWithTypeFileAndFormatSign(“FicheroEjemplo.txt”, typeFile.txt, typeFormatSign.XADES_EPES_ENVELOPED, datos_a_firmar); System.Console.Write(“idTemporalFirma: “ + idTemporalFirma); // Iniciamos el proceso de firma redireccionando al usuario a Viafirma interactuando con el usuario.. clienteViafirma.Sign(idTemporalFirma); }

Destacamos las siguientes líneas:

• Inicialización. Los únicos parámetros que debemos modificar en este punto es el API-KEY y el API_PASS, credenciales que podréis obtener a través de developers.viafirma.com

ViafirmaClientFactory.Init ("http://services.viafirma.com/viafirma/tokenConnector", "http://services.viafirma.com/viafirma", "API_KEY","API_PASS");


• Preparamos la firma. En el método PrepareFirmaWithTypeFileAndFormatSign podemos definir diferentes parámetros. Por ejemplo en el caso de TypeFormatSign podremos definir XADES_EPES_ENVELOPED, XADES_T_ENVELOPED, CMS, PDF_PKCS7, etc.

String idTemporalFirma = clienteViafirma.PrepareFirmaWithTypeFileAndFormatSign(“FicheroEjemplo.txt”, typeFile.txt, typeFormatSign.XADES_EPES_ENVELOPED, datos_a_firmar);

• Procesamos los datos, según los parámetros de el punto anterior.

clienteViafirma.Sign(idTemporalFirma);

Con este simple código ya conseguimos que nuestra aplicación ASP.NET utilice viafirma platform para que sea ésta la responsable de solicitar, validar, recuperar el certificado o DNIe del usuario y firmar el documento digitalmente.

Una vez que el proceso termine, viafirma platform devolverá el control a la aplicación ASP.NET retornando todos los datos obtenidos del certificado, junto con el identificador de firma asociado al documento firmado.


3.4. Obtener datos de respuesta

Una vez que viafirma platform obtenga los datos del certificado de usuario invocará al método ProcessResponseSign, que se encuentra en el fichero Default.aspx dentro del directorio viafirma. Lo único que tendremos que hacer es sobreescribir dicho método con el comportamiento deseado y recuperar todos los datos de la firma del objeto FirmaInfoViafirma.

En el siguiente ejemplo, si la firma ha sido correcta, redireccionamos al usuario a una página de destino.

<%@ Page Language="C#" Inherits="Viafirma.ViafirmaClient"%> override public void ProcessResponseSign(Viafirma.Estado

estado,Viafirma.FirmaInfoViafirma firma){ Viafirma.Log.Debug(“Firma realizada correctamente.”); // Aquí ya tenemos todos los datos asociados al cliente y a su firma. //redireccionamos al usuario a la página destino considerando el usuario ya ha

finalizado la firma. if(Viafirma.Estado.OK== estado){ Session[“resultadoFirma”]= firma; Uri url=new Uri(HttpContext.Current.Request.Url, HttpContext.Current.Response.ApplyAppPathModifier(“~/resultadoFirma.aspx”)); HttpContext.Current.Response.Redirect(url.AbsoluteUri); } else{ // Hay problemas al firmar. } }


4. APLICACIÓN DE EJEMPLO

A continuación se muestran algunas capturas de pantalla de la aplicación de ejemplo ASP.NET que se incluye en el kit de desarrollo.

4.1. Página de inicio


4.2. Interacción con el Applet

4.3. Página del Resultado de Autenticación


4.4. Opciones con Intervención del Usuario


4.5. Página del Resultado de Firma

4.6. Ejemplo de Documento Firmado


5. INICIALIZACIÓN STANDARD DEL CLIENTE

ViafirmaClientFactory.Init("urlViafirma","urlViafirmaWS","API_KEY","API_PASS");

Parámetro Descripción

urlViafirma

es la dirección donde se encuentran los servicios de autenticación. Debe ser el nombre de máquina. Dependiendo del protocolo deseado, se deberá inicializar de la siguiente forma:

• Usando Token Connector:

https://services.viafirma.com/viafirma/tokenConnector

• Usando openID:

https://services.viafirma.com/viafirma/

UrlViafirmaWS es la dirección donde se encuentran los WebServices para firma. En este caso es recomendable que se informe la IP y no el nombre de máquina.

API_KEY Nombre de la app asignado (facilitada por viafirma y gestionado desde viafirma manager).

API_PASS Password asignada a la app. (facilitada por viafirma y gestionada desde viafirma manager)


6. MÉTODOS DEL API

Como parte del kit de desarrollo se entregará la documentación del API .NET con la descripción de cada método disponible. Además, esta documentación se encontrará siempre actualizada en el portal de ayuda a integradores http://developers.viafirma.com.

Dentro del kit de desarrollo estará disponible la versión HTML navegable:


7. CONFIGURACIÓN CAPA CLIENTE

7.1. Configuraciones Posibles de la Capa de Cliente

Debido a las amplias capacidades de abstracción de viafirma platform, se permite al desarrollador modificar la capa cliente al gusto de sus necesidades. Esta operación será realizada mediante hojas de estilo (CSS). Simplemente con colocar un fichero llamado viafirmaStyle.css en el directorio raíz de la aplicación, viafirma platform automáticamente se visualizará con el aspecto configurado por esta hoja de estilo.

Un ejemplo del contenido de este fichero podría seria el siguiente:

body {

background: #fff;

margin: 0;

padding: 0;

}

#global {

background: #fff;

padding-top: 0;

width: 520px;

}

#cabecera {

background: none;

height: 87px;

}

#cabecera h1 a {

background: url(./images/layout/cabecera2.png) no-repeat 100% 0;

height: 87px;

width: 475px;

}

#contenido {

background: none;


}

#cuerpo {

background: none;

}

body.interior #cuerpo .texto {

background: none;

padding-left: 8px;

}

#ayuda {

padding-left: 120px;

}

#ayuda .ayuda h2 {

left: 15px;

}

* html #ayuda .ayuda h2 {

left: -100px;

}

#pie {

background: none;

}

de 22 ANEXO I : Entregables, kit de desarrollo

ANEXO I : ENTREGABLES, KIT DE DESARROLLO

Para esta instalación de viafirma platform se hace entrega del kit dev_kit_viafirmaClientDotNet_2.9.53.zip con los siguientes recursos:

Recurso Descripción

man-integracion-net-platform-3.5.pdf Manual de Integrador.

API-doc_2.9.53.zip Documentación del API.

ViafirmaClientDotNet.dll Librería incluida en el kit.

EjemploWebViafirmaClientDotNet_2.9.53.zip Aplicación .NET de ejemplo.

DotNetOpenId.dll Librería incluida en la aplicación de ejemplo.

log4net.dll Librería incluida en la aplicación de ejemplo.

Default.aspx Página incluida en la aplicación de ejemplo.

viafirmaStyle.css Hoja de estilo librería incluida en en la aplicación de ejemplo.

Consultar siempre la última versión del kit de desarrollo para .NET en el portal de desarrolladores:

http://developers.viafirma.com/download/

manual de integrador - soluciones virtuales de firma ... · a viafirma platform, cuál es la url de...

Documents