Manual de Integrador.NET viafirma platform v3.5
Í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
ÍNDICE
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. CONTROL DE DOCUMENTO
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. Página 5 de 22
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://ser vices.viafirma.com/viafirma, "API_KEY","API_PASS"); // Obtenemos una instancia del cliente e iniciamos la autenticación ViafirmaClient clienteviafirma=viafirmaclientfactory.getinstance(); Página 6 de 22
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. Página 7 de 22
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. Página 8 de 22
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 Página 9 de 22
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> Página 10 de 22
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"); Página 11 de 22
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. Página 12 de 22
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. Página 13 de 22
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 Página 14 de 22
4.2. Interacción con el Applet 4.3. Página del Resultado de Autenticación Página 15 de 22
4.4. Opciones con Intervención del Usuario Página 16 de 22
4.5. Página del Resultado de Firma 4.6. Ejemplo de Documento Firmado Página 17 de 22
5. INICIALIZACIÓN STANDARD DEL CLIENTE ViafirmaClientFactory.Init("urlViafirma","urlViafirmaWS","API_KEY","API_PASS"); Parámetro Descripción 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: urlviafirma Usando Token Connector: https://services.viafirma.com/viafirma/tokenconnector Usando openid: https://services.viafirma.com/viafirma/ UrlViafirmaWS API_KEY API_PASS 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. Nombre de la app asignado (facilitada por viafirma y gestionado desde viafirma manager). Password asignada a la app. (facilitada por viafirma y gestionada desde viafirma manager) Página 18 de 22
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: Página 19 de 22
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; Página 20 de 22
#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; Página 21 de 22
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 man-integracion-net-platform-3.5.pdf API-doc_2.9.53.zip ViafirmaClientDotNet.dll EjemploWebViafirmaClientDotNet_2.9.53.zip DotNetOpenId.dll log4net.dll Default.aspx viafirmastyle.css Descripción Manual de Integrador. Documentación del API. Librería incluida en el kit. Aplicación.NET de ejemplo. Librería incluida en la aplicación de ejemplo. Librería incluida en la aplicación de ejemplo. Página incluida en la aplicación de ejemplo. 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/ ANEXO I : Entregables, kit de desarrollo Página 22 de 22