Manual Usuario Modulo Seguridad ASF

MANUAL DE USUARIO
Librería SFTP
Versión 1.0
Área de Aplicaciones Especiales y Arquitectura de
Software
Framework Atlas
Librería SFTP
Hoja de Control
Título
Manual de Usuario Uso de librería Jsch con el Framework Atlas.
Documento de
Referencia
NORMATIVA ATLAS
Responsable
Área de Aplicaciones Especiales y Arquitectura de Software
Versión
1.0
Fecha Versión
13/05/2014
Registro de Cambios
Versión
Causa del Cambio
Responsable del Cambio
Fecha del Cambio
Área de Integración y Arquitectura de
1.0
Versión inicial del documento
Aplicaciones
2 de 20
13/05/2014
Framework Atlas
Librería SFTP
Índice
1.
INTRODUCCIÓN ................................................................................................................................................................ 4
1.1.
1.2.
AUDIENCIA OBJETIVO ...................................................................................................................................................... 4
CONOCIMIENTOS PREVIOS ............................................................................................................................................... 4
2.
DESCRIPCIÓN .................................................................................................................................................................... 5
3.
INSTALACIÓN Y CONFIGURACIÓN............................................................................................................................. 6
3.1.
INSTALACIÓN .............................................................................................................................................................. 6
3.2. CONFIGURACIÓN ....................................................................................................................................................... 6
3.2.1.
Paso 1: Parámetros de configuración del environment.properties ........................................................................ 6
4.
USO ........................................................................................................................................................................................ 7
4.1.
CREAR SERVICIO DE SFTP ............................................................................................................................................... 9
4.1.1.
Crear interfaz del servicio de SFTP........................................................................................................................ 9
4.1.2.
Crear implementación del servicio de SFTP ........................................................................................................ 11
4.1.3.
Definir servicio de sftp en applicationContext-services.xml ................................................................................. 12
4.2.
CREAR FACHADA ........................................................................................................................................................... 13
4.2.1.
Crear interfaz de la fachada ................................................................................................................................. 13
4.2.2.
Crear implementación de la fachada .................................................................................................................... 14
4.2.3.
Definir fachada en applicationContext-services.xml ............................................................................................ 15
4.3.
CREAR PRESENTACIÓN JSF ............................................................................................................................................ 15
4.3.1.
Crear backing bean............................................................................................................................................... 15
4.3.2.
Crear página JSF .................................................................................................................................................. 17
5.
ENLACES RELACIONADOS .......................................................................................................................................... 18
6.
ANEXOS .............................................................................................................................................................................. 19
6.1.
INSTALACIÓN Y CONFIGURACIÓN DE SERVIDOR SSH FTP ............................................................................................. 19
6.1.1.
Crear usuario del Servidor SSH FTP ................................................................................................................... 19
6.1.2.
Establecer directorio del Servidor SSH FTP ........................................................................................................ 20
6.1.3.
Establecer puerto del Servidor SSH FTP .............................................................................................................. 20
6.1.4.
Iniciar servicio SSH del Servidor. ......................................................................................................................... 20
3 de 20
Framework Atlas
Librería SFTP
Contenido
1. INTRODUCCIÓN
En este documento se explica cómo conectarse a un servidor SSH FTP, también conocido como SFTP y hacer una
serie de operaciones como listar los ficheros que se encuentran en un directorio, subir, descargar y eliminar un
fichero que se encuentra en el SFTP a través de una aplicación web.
1.1.
Audiencia objetivo
El lector objetivo de este documento es toda aquella persona que esté desarrollando una aplicación basada en el
framework Atlas y necesite acceder y gestionar ficheros de un servidor de ficheros SSH FTP.
1.2.
Conocimientos Previos
Para un completo entendimiento del documento, el lector deberá tener conocimientos previos sobre las siguientes
tecnologías:
-
Java Server Faces (JSF)
-
Spring Framework
Para saber más sobre dichas tecnologías, consultar el apartado de este documento, Enlaces Relacionados
4 de 20
Framework Atlas
Librería SFTP
2. DESCRIPCIÓN
Para poder conectarse a un servidor SSH FTP usaremos la librería jsch la cual nos permite transferir seguramente
ficheros sobre SSH, esta librería nos permite hacer una seria de operaciones sobre sftp como:
Listar ficheros
Subir ficheros
Renombrar ficheros
Descargar ficheros
Crear directorios
Eliminar directorios
El resto de características se encuentran en la web de la librería http://www.jcraft.com/jsch/
El paquete principal que utilizaremos será com.jcraft.jsch.JSch el cual nos permitirá crear una sesión
remota (session) en un servidor estableciendo el host, puerto y un usuario, una vez establecida la sesión
indicaremos la clave, si toda va bien entonces tendremos una conexión abierta y podemos crear un canal (channel)
El canal de uso aquí será de tipo “sftp” (pueden ser de tipo como Shell, exec y subsystem; más información en
http://wiki.jsch.org/index.php?Manual#ae1f7edf), una vez abierto el canal sftp podemos hacer las operaciones
comunes como rm, rmdir, mkdir, cd, get, put, etc.
5 de 20
Framework Atlas
Librería SFTP
3. INSTALACIÓN Y CONFIGURACIÓN
3.1.
INSTALACIÓN
Para poder usar la librería java Jsch se deberá incluir la siguiente dependencia en el archivo pom.xml del proyecto.
pom.xml
<!--
3.2.
Dependencias para SFTP-->
<dependency>
<groupId>com.jcraft</groupId>
<artifactId>jsch</artifactId>
<version>0.1.51</version>
</dependency>
CONFIGURACIÓN
Éste es el punto más importante, aquí definimos y configuramos los beans que usaremos para operar con los
ficheros del servidor SSH SFTP. Para que los valores de los parámetros de configuración sean invisibles al
entorno de la aplicación, estos son obtenidos del fichero environment.properties.
3.2.1.
Paso 1: Parámetros de configuración del environment.properties
Para establecer la configuración de conexión el SFTP se deberá ingresar los datos del servidor como el host
(puede ser la ip del servidor), el puerto, el usuario, el directorio donde se descargan los ficheros, el directorio
remoto donde se encuentras los ficheros que vamos a operar.
La clave o password de acceso al servidor se deberá ingresar encriptada, para ello usar el servicio proporcionado
por ICM en la página http://intranet.madrid.org/arquitecturasw/desarrollos-atlas/utilidades/encriptacion , el valor
devuelto por ese servicio deberá ser el que se ingrese a la derecha de sftp.clave=
environment.properties
# Configuración de acceso a SFTP
sftp.host=localhost
sftp.puerto=22
sftp.usuario=usuario
sftp.clave=7583256AF7A2BE12
sftp.dirDescarga=/borrame/
sftp.dirRemoto=.
NOTA
Para más información sobre el fichero de configuración environment.properties consultar el manual de
arquetipos.
6 de 20
Framework Atlas
Librería SFTP
4. USO
Una vez configurado el entorno para el uso del servicio, puede procederse a su utilización. Análogamente al resto
de servicios de Spring, para hacer uso de los beans de sftp, declararemos los atributos respectivos a cada uno de
ellos en el servicio que los queramos usar -con sus métodos set correspondientes-.
Ejemplo de listar ficheros
7 de 20
Framework Atlas
Librería SFTP
.....
/**
* The sftpFacade, la fachada
*/
@ManagedProperty(value = "#{sftpFacade}")
private SftpFacade sftpFacade;
/**
* @return the sftpFacade
*/
public SftpFacade getSftpFacade() {
return sftpFacade;
}
/**
* @param sftpFacade the sftpFacade to set
*/
public void setSftpFacade(SftpFacade sftpFacade) {
this.sftpFacade = sftpFacade;
}
/**
* Método que sirve para listar los fichero del directorio
* remoto del SFTP.
*/
@SuppressWarnings("unchecked")
public void listarFicheros() {
try {
Vector vFicheros = sftpFacade.listarFicheros();
agregarFicheros(vFicheros);
} catch (ServiceException e) {
AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(),
"sftp.listar.error");
}
}
/**
* Método que sirve para agregar ficheros
* al componente select.
* @param vFicheros Lista de ficheros.
*/
@SuppressWarnings("unchecked")
private void agregarFicheros(Vector vFicheros) {
ficheros = new ArrayList<SelectItem>();
int numeroFicheros = vFicheros.size();
for (int ii = 0; ii < numeroFicheros; ii++) {
Object obj = vFicheros.elementAt(ii);
if (obj instanceof LsEntry) {
String nombreFichero = ((LsEntry) obj).getFilename();
agregarSelectItem(nombreFichero);
}
}
}
.....
8 de 20
Framework Atlas
Librería SFTP
4.1.
Crear servicio de SFTP
4.1.1.
Crear interfaz del servicio de SFTP
Comenzamos con la implementación de un servicio, creando una interfaz, para obligarnos a implementar una serie
de métodos, los típicos para sftp (listar, subir, descargar y eliminar ficheros).
NOTA
El servicio que se muestra a continuación no tiene como finalidad ser utilizado como servicio gestión de
ficheros de un SFTP, simplemente se trata de un ejemplo de integración con el framework. Cada
proveedor debe hacer los cambios oportunos para adecuarlos a sus necesidades.
9 de 20
Framework Atlas
Librería SFTP
Para nuestro ejemplo usaremos los siguientes:
SftpService.java
/**
* Esta interfaz representa las operaciones
* de operaciones con un servidor seguro SFTP.
* @author ICM
* @version 1.0.
*/
public interface SftpService {
/**
* Método que devuelve el listado ficheros del directorio remoto
* del servidor SFTP.
* @return Vector, listado de ficheros del directorio
* @throws ServiceException ex
*/
@SuppressWarnings("unchecked")
Vector listarFicheros() throws ServiceException;
/**
* Método que permite descargar un fichero del SFTP
* @param fichero el fichero a descargar
* @throws ServiceException ex
*/
void descargarFichero(String fichero) throws ServiceException;
/**
* Método que permite eliminar u fichero del SFTP
* @param fichero el fichero a eliminar
* @throws ServiceException ex
*/
void eliminarFichero(String fichero) throws ServiceException;
/**
* Método que permite subir un fichero al SFTP
* @param nombreFichero el nombre del fichero
* @param is inputstream del fichero
* @throws ServiceException ex
*/
void subirFichero(InputStream is, String nombreFichero) throws
ServiceException;
}
10 de 20
Framework Atlas
Librería SFTP
4.1.2.
Crear implementación del servicio de SFTP
Creamos la implementación de los métodos definidos en la interfaz SftpService.
SftpServiceImpl.java
/**
* Esta clase representa el servicio de ejemplo de sftp
*/
@Service
public class SftpServiceImpl implements SftpService {
/** El host sftp */
private String host;
/** El puerto del SFTP */
private int puerto;
/** Usuario del sftp */
private String usuario;
/** password para acceder al sftp */
private String password;
/** directorio remoto del sftp*/
private String dirRemoto;
/** {@inheritDoc} */
@SuppressWarnings("unchecked")
@Override
public Vector listarFicheros() throws ServiceException {
Session session = null;
ChannelSftp channelSftp = null;
Channel
channel
= null;
Vector vFicheros = new Vector();
session = conectar();
if (session.isConnected()) {
try {
channel = session.openChannel("sftp");
channel.connect();
channelSftp = (ChannelSftp) channel;
vFicheros = channelSftp.ls(dirRemoto);
} catch (JSchException e) {
throw new ServiceException(e);
} catch (SftpException e) {
throw new ServiceException(e);
} finally {
session.disconnect();
}
}
return vFicheros;
}
. . .
11 de 20
Framework Atlas
Librería SFTP
4.1.3.
Definir servicio de sftp en applicationContext-services.xml
Publicamos nuestro servicio en el contexto, inyectándole la dependencia al servicio de envío propio de Spring y la
plantilla.
applicationContext-services.xml
<bean id="sftpService" class="atlas.sftp.services.SftpServiceImpl">
<property name="host" value="${sftp.host}"/>
<property name="puerto" value="${sftp.puerto}"/>
<property name="usuario" value="${sftp.usuario}"/>
<property name="password" value="${sftp.clave}"/>
<property name="dirDescarga" value="${sftp.dirDescarga}"/>
<property name="dirRemoto" value="${sftp.dirRemoto}"/>
</bean>
NOTA
Con la implementación de la interfaz y esta configuración ya podemos hacer uso de nuestro servicio de
envío desde cualquiera de nuestras clases de negocio gestionadas por Spring.
A continuación mostraremos un ejemplo de uso del servicio a través de una página JSF. Si ya se tiene claro cómo
utilizarlo (igual que el resto de servicios Spring) se puede dar por finalizado el manual.
El siguiente ejemplo ha sido extraído de la aplicación de ejemplo de integración*.
Aplicación de ejemplo de integración
Aplicación de ejemplo creada para mostrar la integración con los diferentes servicios Atlas
Url de acceso (usuario_ok/usuario_ok)
Código fuente
12 de 20
Framework Atlas
Librería SFTP
4.2.
Crear fachada
Como se explica en la normativa, las páginas JSF interactúan con los servicios a través de una fachada. Así pues,
para nuestro ejemplo, creamos la fachada SftpFacade (interfaz e implementación) para que llame a nuestro
servicio SftpService.
4.2.1.
Crear interfaz de la fachada
SftpFacade.java
/**
* Esta interfaz representa las operaciones
* de la fachada para SFTP.
* @author ICM
* @version 1.0.
*/
public interface SftpFacade {
/**
* Método que obtiene un listado de ficheros del servidor SFTP
* @return Vector listado de ficheros del directorio remoto
* @throws ServiceException error en la invocación
*/
@SuppressWarnings("unchecked")
Vector listarFicheros() throws ServiceException;
/**
* Método que permite descargar un fichero que se encuentra
* en el SFTP a un directorio.
* @param fichero el fichero que se va a descargar
* @throws ServiceException error en la invocación
*/
void descargarFichero(String fichero) throws ServiceException;
/**
* Método que permite eliminar un fichero del SFTP
* @param fichero el fichero a eliminar
* @throws ServiceException ex
*/
void eliminarFichero(String fichero) throws ServiceException;
/**
* Método que permite subir un fichero al SFTP
* @param nombreFichero el nombre del fichero
* @param is inputstream del fichero
* @throws ServiceException error en la invocación
*/
void subirFichero(InputStream is, String nombreFichero) throws
ServiceException;
}
13 de 20
Framework Atlas
Librería SFTP
4.2.2.
Crear implementación de la fachada
SftpFacadeImpl.java
/**
* Esta clase representa la fachada para sftp.
* @author ICM
* @version 1.0.
*/
@Service
public class SftpFacadeImpl implements SftpFacade {
/** Servicio de sftp */
private SftpService sftpService;
/** {@inheritDoc} */
@SuppressWarnings("unchecked")
@Override
public Vector listarFicheros() throws ServiceException {
return this.sftpService.listarFicheros();
}
/** {@inheritDoc} */
@Override
public void descargarFichero(String fichero) throws ServiceException {
this.sftpService.descargarFichero(fichero);
}
/** {@inheritDoc} */
@Override
public void eliminarFichero(String fichero) throws ServiceException {
this.sftpService.eliminarFichero(fichero);
}
/** {@inheritDoc} */
@Override
public void subirFichero(InputStream is, String nombreFichero) throws
ServiceException {
this.sftpService.subirFichero(is, nombreFichero);
}
/**
* @param sftpService the sftpService to set
*/
public void setSftpService(SftpService sftpService) {
this.sftpService = sftpService;
}
}
14 de 20
Framework Atlas
Librería SFTP
4.2.3.
Definir fachada en applicationContext-services.xml
Definir y configurar la fachada, sftpFacade, para que haga uso de nuestro servicio de sftp.
applicationContext-services.xml
<bean id="sftpFacade" class="atlas.sftp.services.facade.SftpFacadeImpl">
<description>
Bean que representa la fachada por la cual acceder a los servicios
para SFTP
</description>
<property name="sftpService" ref="sftpService" />
</bean>
4.3.
Crear presentación JSF
4.3.1.
Crear backing bean
Creamos un bean JSF que realiza la acción de listar ficheros del SFTP. Esta clase hace uso del servicio de sftp a
través de la fachada recién creada.
SftpFormBean.java
15 de 20
Framework Atlas
Librería SFTP
/**
* The Class SftpFormBean.
* @author ICM
*/
public class SftpFormBean extends BaseBean {
/**
* La fachada
*/
@ManagedProperty(value = "#{sftpFacade}")
private SftpFacade sftpFacade;
/**
* El fichero seleccionado.
*/
private String fichero;
/**
* Método que sirve para listar los fichero del directorio
* remoto del SFTP.
*/
@SuppressWarnings("unchecked")
public void listarFicheros() {
try {
Vector vFicheros = sftpFacade.listarFicheros();
agregarFicheros(vFicheros);
} catch (ServiceException e) {
AtlasFacesUtils.storeOnRequestError(FacesContext.getCurrentInstance(),
"sftp.listar.error");
} finally {
}
}
/**
* Método que sirve para agregar ficheros que tengan extensiones permitidas
* al componente select.
* @param vFicheros Lista de ficheros.
*/
@SuppressWarnings("unchecked")
private void agregarFicheros(Vector vFicheros) {
ficheros = new ArrayList<SelectItem>();
int numeroFicheros = vFicheros.size();
for (int ii = 0; ii < numeroFicheros; ii++) {
Object obj = vFicheros.elementAt(ii);
if (obj instanceof LsEntry) {
String nombreFichero = ((LsEntry) obj).getFilename();
agregarSelectItem(nombreFichero);
}
}
}
/**
* Método que permite agregar un
* elemento a selectitem
* @param nombreFichero nombre del fichero
*/
private void agregarSelectItem(String nombreFichero) {
ficheros.add(new SelectItem(nombreFichero, nombreFichero));
}
/** NOTA: faltan los getters y setters de los atributos */
}
16 de 20
Framework Atlas
Librería SFTP
4.3.2.
Crear página JSF
Por simplicidad, sólo mostramos el botón y el componente h:selectOneListBox donde se mostrarán los ficheros del
servidor SFTP.
Como se ha indicado anteriormente, todo el código de la aplicación está disponible a través de la siguiente
dirección: Código fuente de la aplicación de ejemplo de integración de servicios Atlas
sftpSample.xhtml
. . .
<div class="botonera_izquierda">
<a4j:commandLink id="listar" value="Listar ficheros de SFTP"
styleClass="botonAplicacionTXT"
render="listaFicheros"
action="#{sftpFormBean.listarFicheros}">
<h:graphicImage value="/img/ico_nuevo.gif"
alt="#{bundle['lv.enviar']}" />
</a4j:commandLink>
</div>
<div class="space2"/>
<div class="space2"/>
<h:panelGrid columns="1">
<h:selectOneListbox id="listaFicheros" value="#{sftpFormBean.fichero}"
size="4" style="width: 230px;">
<f:selectItems value="#{sftpFormBean.ficheros}" />
</h:selectOneListbox
</h:panelGrid>
. . .
17 de 20
Framework Atlas
Librería SFTP
5. ENLACES RELACIONADOS
Producto
URL
Ajax4JSF
http://www.jboss.org/jbossrichfaces/
Commons Configurations
http://commons.apache.org/configuration/
JSF
http://java.sun.com/javaee/javaserverfaces/
MyFaces Core
http://myfaces.apache.org/
RichFaces
http://www.jboss.org/jbossrichfaces/
Spring
http://www.springframework.org/
Atlas Integración
http://intranet.madrid.org/arquitecturasw/desarrollos-atlas/integracion
18 de 20
Framework Atlas
Librería SFTP
6. ANEXOS
6.1.
Instalación y configuración de Servidor SSH FTP
Para instalar el servidor SFTP y poder usarlo como servidor de pruebas, debemos descargarlo de
http://www.freesshd.com/?ctt=download.
Seguir los pasos de instalación normalmente.
6.1.1. Crear usuario del Servidor SSH FTP
Primero deberemos crear un usuario para que nuestra aplicación web pueda conectarse al servidor
mediante este usuario, para ello debemos ejecutar la aplicación haciendo doble click sobre su icono
El servidor empezara como un icono en la barra derecha inferior de Windows como se aprecia en la figura:
Hacer click derecho y luego hacer click en el menú “Settings…” para abrir la pantalla de configuración del
servidor.
Ir a la pestaña “Users”, hacer click en el botón “Add”, en la nueva ventana ingresar los datos del usuario:
Login: Este será equivalente al valor del campo sftp.usuario que hemos indicado en el fichero
environment.properties.
Authorization: Seleccionar el valor “Password stored as SHA1 hash”
Password: ingresar el password para este usuario (recordar que este valor tendremos que ingresarlo en la
página http://intranet.madrid.org/arquitecturasw/desarrollos-atlas/utilidades/encriptacion y el valor devuelto
se debe ingresar en campo sftp.clave del fichero environment.properties).
User can use: Marcar la opción SFTP.
Hacer click en el botón “Aceptar” para crear el usuario, no debe quedar una pantalla como la siguiente:
19 de 20
Framework Atlas
Librería SFTP
6.1.2. Establecer directorio del Servidor SSH FTP
Para establecer el directorio debemos ir a la pestaña “SFTP”, ahí ubicaremos un directorio que será
nuestro directorio por defecto cuando un usuario se conecte a nuestro servidor.
6.1.3. Establecer puerto del Servidor SSH FTP
Para establecer el puerto debemos ir a la pestaña “SSH”, ahí indicaremos el puerto de nuestro servidor
SFTP, en este ejemplo es 22 (este valor se corresponde con el campo sftp.puerto del fichero
environment.properties), dejar los demás valores de esta pestaña como están.
6.1.4. Iniciar servicio SSH del Servidor.
Para iniciar el servicio SSH del servidor debemos ir a la pestaña “Server status” y hacer click en el aspa
correspondiente al servicio SSH de tal forma que esta pestaña quede como la que se muestra a
continuación:
20 de 20