Subdirección de las Tecnologías de la Información y Comunicaciones

Área de Gobernanza y Calidad

Image RemovedImage Added

Cumplimiento normativo

Histórico de cambios

Los cambios en la normativa vendrán acompañados de un registro de las modificaciones. De este modo se podrá realizar un seguimiento y consultar su evolución. Ordenándose de mas recientes a menos recientes, prestando especial cuidado a las cabezeras de la tablas dónde se indican las fechas de entrada en vigor y versión.

• Versión inicial sobre el componente que permite la integración con MACO fácilmente

Histórico de cambios

SAS.MacoApiClient

Introducción

En el presente documento se presenta la librería SAS.MacoApiClient, que permite el acceso a datos de Maco.

Dispone de dos versiones, .NET Framework 4.5.2 y .NET Standard 2.0:

• .NET Framework 4.5.2: Permite el acceso a los datos de MACO utilizando el servicio web. Versión de la API 1.7.6
• .NET Standard 2.0: Permite el acceso a los datos de Maco utilizando dos implementaciones diferentes: una que utiliza internamente el servicio web de Maco y otra que utiliza réplica de BBDD. Versión de la API >= 2.0.0

La versión actual de la librería .NET Standard , en su versión acceso a réplica de BBDD, solo dispone de métodos para acceso a la información de módulos y perfiles.

Se recomienda la instalación de la versión de la librería .NET Standard 2.0, en su versión Servicio Web, compatible con .NET Framework desde la versión 4.6.1 de .NET Framework. por su actualización más periódica.

Dependencias

Se define las siguientes dependencia de la librería:

Versión API 1.7.6 y Versión API >= 2.0.0

Versión API >= 2.0.0

Errores conocidos

• Bug al parsear fecha en formato cadena a un formato DateTime determinado.

  Problema al parsear una fecha en formato cadena, en la que la hora solo contiene un dígito. Corregido en la versión 1.7.3 y desde de la version 2.0.2

• Bug al hacer loging con Maco: ticket devuelto nulo. Corregido en la versión 1.7.4.

Integración de la librería

Configurar en Visual Studio un nuevo origen de paquetes Nuget ( clic en “Administrar Paquetes Nuget …” del proyecto al que se desea añadir la referencia el componente MacoApiClient) indicando en el campo Origen la dirección de repositorios de componentes .NET del SAS: http://net.lib.repository.alm.sas.junta-andalucia.es/.

Versión API < 2.5.0

• • Instalar el componente SAS.MacoApiClient.

Versión API >= 2.5.0

• • Instalar el componente SAS.MacoApiClient.WebService para el acceso a datos de Maco utilizando los servicios web de Maco y validación de tickets,firma, operaciones y fecha del mensaje.
  • Solo en el caso de que se necesite consultar datos de módulos y perfil, instalar el componente SAS.MacoApiClient.ManagedDataAccess.Oracle.
  • En el caso de que solo se quiera utilizar la funcionalidad de validar ticket, firma, operaciones y fecha del mensaje, instalar SAS.MacoApiClient.Ticket.

Configuración

Prerequisitos

Previo a la configuración de la librería se debe de disponer de los siguientes datos proporcionados por la Oficina Técnica de Interoperabilidad:

• Clave pública de Maco, tanto de PRE como de PRO. Se corresponde con una clave de encriptación en formato RSA: <RSAKeyValue><Modulus>...</RSAKeyValue>
• Código del módulo del sistema en Maco. Se corresponde con el código en el que está identificado el sistema en Maco.
• Endpoints de los servicios web de Maco, tanto de PRE como de PRO. En el caso de PRE, son los siguientes:
  • https://servicios.pre.sas.junta-andalucia.es/maco/wsValidacion.asmx Servicio web de validación de Maco.
  • https://servicios.pre.sas.junta-andalucia.es/maco /wsOperador.asmx Servicio web para la gestión de datos de Operadores de Maco.
  • https://servicios.pre.sas.junta-andalucia.es/maco /wsProfesional.asmx Servicio web para la gestión de datos de Profesionales de Maco.

Otros parámetros de configuración

El validador de ticket requiere la configuración de los siguientes parámetros:

• RsaKey: Se corresponde con la Clave pública de Maco.
• ReferenceDate: Fecha de referencia utilizada para conocer si un ticket ha expirado
• FutureTicketToleranceMilli: Se utiliza para la validación de tolerancia de ticket futuro. Si su valor es inferior a 0, no se realiza validación de ticket futuro. Si su valor es mayor que 0, indica el número de milisegundos que se tolera en la validación de la fecha del ticket futuro. Si no se desea ticket a futuro, su valor se establecerá a 0.
• TicketTtlMillis: Se utiliza para validar la expiración de un ticket. Si ReferenceDate - TicketTtlMillis es superior a la fecha del ticket, se considera que el ticket ha expirado.
• TicketValidations. Listado de tipos de validación que se le aplica al ticket. Pueden ser los siguientes:
  
  • Expiración (TicketValidationType.Expired). Valida si el ticket ha expirado
  • Futuro (TicketValidationType.Future). Valida si se ha recibido un ticket con fecha futura y no cumple la tolerancia definida en el campo FutureTicketToleranceMilli.
  • Permisos (TicketValidationType.Permission). Valida que el ticket tiene los permisos adecuados para poder hacer la operación.
  • Firma (TicketValidationType.Signature). Valida que la firma del ticket sea correcta.

Procedimiento de configuración a partir de la versión 1.7.3

Cómo ejemplo de configuración, la clase UserService provee un servicio de autenticación y autorización contra el servicio de MACO.

En el ejemplo siguiente se utiliza el fichero de configuración app.config para definir los parámetros de configuración de Maco: clave pública de Maco, ruta principal servicio web de Maco y endpoints de Validación, Operador y Profesional de Maco.

<appSettings>
<add key="MacoXmlKey" value="CLAVE_PUBLICA_DE_MACO" />
<add key="MacoModule" value="CODIGO_EN_MACO_DEL_SISTEMA" />
<add key="ServiceAddressMaco" value="https://servicios.pre.sas.junta-andalucia.es/" />
<add key="EndPointAddressMacoValidacion" value="/maco/wsValidacion.asmx" />
<add key="EndPointAddressMacoOperador" value="/maco/wsOperador.asmx" />
<add key="EndPointAddressMacoProfesional" value="/maco/wsProfesional.asmx" /> 
</appSettings>

Se consulta la clave pública de Maco del fichero de configuración

string _xmlMacoKey = ConfigurationManager.AppSettings.Get("MacoXmlKey");

Se crea el objeto de configuración de Maco, MacoApiConfig. La url que recibe como parámetro se consultará de fichero de configuración o BBDD. En el ejemplo se ha utilizado la ruta inicial de PRE.

string serviceAddressMaco= ConfigurationManager.AppSettings.Get("ServiceAddressMaco");
MacoApiConfig macoApiConfig = new MacoApiConfig(serviceAddressMaco); 

Se consulta el código de módulo asignado al sistema en Maco.

macoApiConfig.ModuleCode = ConfigurationManager.AppSettings.Get("MacoModule"); 

Se define los enpoints de los diferentes servicios web de Maco en el objeto macoApiConfig: Validación, Operador y Profesionales.

string endPointAddressMacoValidacion = ConfigurationManager.AppSettings.Get("EndPointAddressMacoValidacion");
string endPointAddressMacoOperador = ConfigurationManager.AppSettings.Get("EndPointAddressMacoOperador");
string endPointAddressMacoProfesional = ConfigurationManager.AppSettings.Get("EndPointAddressMacoProfesional");


macoApiConfig.EndPoints = new Dictionary<MacoApiClient.Api.Entity.EndPointType, string>
{
         { MacoApiClient.Api.Entity.EndPointType.Validacion,  endPointAddressMacoValidacion  }, 
         { MacoApiClient.Api.Entity.EndPointType.Operador,  endPointAddressMacoOperador },
         { MacoApiClient.Api.Entity.EndPointType.Profesional,  endPointAddressMacoProfesional  }
};

Se define la configuración del validador de ticket. En el ejemplo, se comprueba que la fecha del ticket sea de 24 horas máximo y no se permite ticket a futuro (FutureTicketToleranceMillis =0).

TicketValidatorConfig ticketConfig = new TicketValidatorConfig()
            {
                RsaKey = _xmlMacoKey,
                ReferenceDate = DateTime.Now,
                FutureTicketToleranceMillis = 0,
                TicketTtlMillis = 24 * 60 * 60 * 1000,
                TicketValidations = new HashSet<TicketValidationType>()
            };

Se añaden los diferentes tipos de validaciones. En el ejemplo, validación de firma, expiración de ticket, ticket futuro y permisos.

ticketConfig.TicketValidations.Add(TicketValidationType.Signature); //SignatureTicketValidation: Valida que la firma es correcta 
ticketConfig.TicketValidations.Add(TicketValidationType.Expired); //ExpiredTicketValidation: Valida que el ticket no esté caducado 
ticketConfig.TicketValidations.Add(TicketValidationType.Future); //FutureTicketValidation: Valida que el ticket no sea futuro 
ticketConfig.TicketValidations.Add(TicketValidationType.Permission); //PermissionTicketValidation: Valida que el permiso requerido se encuentre en el ticket 

Se inicializa un objeto de tipo MacoFactory, el cual recibe un objeto configuración de la api y del ticket. Permite crear el resto de objetos necesarios para la utilización de la API.

factory = new MacoFactory(macoApiConfig, ticketConfig);

Se crea el objeto de autenticación de Maco, el cual permite realizar la autenticación o comprobar la autorización de un módulo concreto de Maco.

macoAuthentication = new MacoAuthentication(factory.MacoUserManager, macoApiConfig, factory.TicketValidator, factory.WsMacoManager, factory.MacoExceptionManager);

A continuación se presenta el código completo del ejemplo:

 public class UserService
{
        MacoFactory factory;
        MacoAuthentication macoAuthentication;
        public UserService()
        {
            string _xmlMacoKey = "CLAVE_PUBLICA_MACO"; 
       
            MacoApiConfig macoApiConfig = new MacoApiConfig("https://servicios.pre.sas.junta-andalucia.es/"); 
            macoApiConfig.ModuleCode = "MODULO_MACO_DEL_SISTEMA"; 
            macoApiConfig.EndPoints = new Dictionary<MacoApiClient.Api.Entity.EndPointType, string>
                   {
                       { MacoApiClient.Api.Entity.EndPointType.Validacion, @"/maco/wsValidacion.asmx" }, 
                       { MacoApiClient.Api.Entity.EndPointType.Operador, @"/maco/wsOperador.asmx"},
                       { MacoApiClient.Api.Entity.EndPointType.Profesional, @"/maco/wsProfesional.asmx" }
                   };

            TicketValidatorConfig ticketConfig = new TicketValidatorConfig()
            {
                RsaKey = _xmlMacoKey,
                ReferenceDate = DateTime.Now,
                FutureTicketToleranceMillis = -1,
                TicketTtlMillis = 24 * 60 * 60 * 1000,
                TicketValidations = new HashSet<TicketValidationType>()
            };
            ticketConfig.TicketValidations.Add(TicketValidationType.Signature); //SignatureTicketValidation: Valida que la firma es correcta 
            ticketConfig.TicketValidations.Add(TicketValidationType.Expired); //ExpiredTicketValidation: Valida que el ticket no este caducado 
            ticketConfig.TicketValidations.Add(TicketValidationType.Future); //FutureTicketValidation: Valida que el ticket no sea futuro 
            ticketConfig.TicketValidations.Add(TicketValidationType.Permission); //PermissionTicketValidation: Valida que el permiso requerido se encuentre en el ticket 

            factory = new MacoFactory(macoApiConfig, ticketConfig);
            macoAuthentication = new MacoAuthentication(factory.MacoUserManager, macoApiConfig, factory.TicketValidator, factory.WsMacoManager, factory.MacoExceptionManager);
        }
}

Procedimiento de configuración a partir de la versión 2.0.0

La configuración de la API depende del tipo de implementación que se vaya a utilizar, según se acceda a los datos mediante el Servicio Web de Maco o mediante réplicas de base de datos. Veamos cada una de ellas:

En ambos ejemplos se utiliza como base un proyecto .NET MVC.

Primero, en el fichero Startup.cs, método ConfigureServices, se inicializa el contenedor de inyección de dependencia:

 public void ConfigureServices(IServiceCollection services)
        {
          ...
          ContainerDI.SetAsyncScopedLifestyle(); // establecer estilo de vida por defecto del contenedor de inyección. Permite procesar tanto operaciones asíncronas como síncronas
          ContainerDI.RegisterServices(ref services); 
        ...
      } 

ContainerDI, clase del componente común SAS.Util.Injection, el cual permite el registro por inyección de dependencia de los diferentes servicios y tipos utilizados en el sistema.

Configuración de la API versión Servicio Web

En el fichero appsettings se definen secciones en las que se establece configuración de Maco: clave pública de maco y módulo del sistema en Maco, y servicio web de Maco: dirección del servicio web de Maco y los endpoints de Validación, Operador y Profesional

"MacoApiClient": { 
	"XmlKey": "CLAVEPUBLICAMACO", 
	"Module": "MODULOMACO" 
},  
"WebServiceLocator": { 
	"ServiceAddressMaco": "https://servicios.pre.sas.junta-andalucia.es/",
	"EndPointAddressMacoValidacion": "/maco/wsValidacion.asmx",
	"EndPointAddressMacoOperador": "/maco/wsOperador.asmx",
	"EndPointAddressMacoProfesional": "/maco/wsProfesional.asmx" 
},

En el fichero Startup.cs, método Configure(IApplicationBuilder app, IHostingEnvironment env), añadir la siguiente configuración de los controladores , viewcomponents de MVC y la llamada al nuevo método InitializeContainer :

 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            ContainerDI.RegisterMvcControllers(ref app);
            ContainerDI.RegisterMvcViewComponents(ref app);          

            this.InitializeContainer();
           ...
        } 

A continuación, en el fichero Startup.cs, crear el método void InitializeContainer() y añadir la siguiente configuración para definir la configuración del validador de ticket, configuración con los endpoints de los servicios web de Maco y registrar por inyección de dependencia los diferentes servicios utilizados de la API:

 services.AddMacoWSServices (macoApiConfig,ticketValidatorConfig );

Configuración de la validación del ticket de Maco. Se define validación de firma, fecha del ticket y permisos

/// <summary>
/// Inicializador de contenedor utilizando el inyector de dependencia ContainerDI.
/// </summary>
private void InitializeContainer()
{
	var ticketValidatorConfig = new TicketValidatorConfig
	{ 
		RsaKey = ConfigurationManager.AppSettings["MacoApiClient:XmlKey"],
		ReferenceDate = DateTime.Now,
		FutureTicketToleranceMillis = -1,
		TicketTtlMillis = 24 * 60 * 60 * 1000,
		TicketValidations = new HashSet<TicketValidationType>()
	};

	ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Signature); // SignatureTicketValidation: Valida que la firma es correcta 
	ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Expired); // ExpiredTicketValidation: Valida que el ticket no este caducado 
	ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Future); // FutureTicketValidation: Valida que el ticket no sea futuro 
	ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Permission); // PermissionTicketValidation: Valida que el permiso requerido se encuentre en el ticket 

Configuración de la api de Maco, en la que se le pasa la dirección del servicio web de Maco y el código del módulo. También se define los endpoints de los servicios web de Maco.

var macoApiConfig = new MacoApiConfig(this.Configuration.GetSection("WebServiceLocator:ServiceAddressMaco").Value)
{
	ModuleCode = this.Configuration.GetSection("MacoApiClient:Module").Value
};

   macoApiConfig.EndPoints = new Dictionary<MacoApiClient.WebService.Api.Entity.EndPointType, string>
   {
           { MacoApiClient.WebService.Api.Entity.EndPointType.Validacion, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoValidacion").Value },
           { MacoApiClient.WebService.Api.Entity.EndPointType.Operador, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoOperador").Value},
           { MacoApiClient.WebService.Api.Entity.EndPointType.Profesional, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoProfesional").Value }
   };

Registro del tipo TicketValidator que implementa la interfaz ITicketValidator. Se encarga de gestionar la validación de tickets.

ContainerDI.Register<ITicketValidator>(() => new TicketValidator(ticketValidatorConfig), ContainerDI.LifeStyleContainer.Transient); 

Registro del tipo MacoExceptionManager que implementa la interfaz IMacoExceptionManager. Se encarga de gestionar las excepciones y errores informados del servicio web de Maco.

ContainerDI.Register<IMacoExceptionManager, MacoExceptionManager>(ContainerDI.LifeStyleContainer.Transient); 

Registro del tipo MacoUserTransformer que implementa la interfaz IMacoUserTransformer. Se encarga de transformar los mensajes XML recibidos del servicio web de MACO a objetos.

ContainerDI.Register<IMacoUserTransformer, WSMacoUserTransformer>(ContainerDI.LifeStyleContainer.Transient);

Registro del tipo MacoApiConfig que implementa la interfaz IMacoApiConfig. Contiene la información de configuración de la API.

 ContainerDI.Register<IMacoApiConfig>(() => macoApiConfig, ContainerDI.LifeStyleContainer.Transient);

Registro del tipo WsMacoManager que implementa la interfaz IWsMacoActions. Es la clase wrapper encargada de llamar a los servicios web de Maco.

ContainerDI.Register<IWsMacoActions>(() => new WsMacoManager(macoApiConfig), ContainerDI.LifeStyleContainer.Transient);

Registro del servicio WSMacoAuthentication que implementa la interfaz IMacoAuthentication. Encargada de gestionar las consultas al servicio de Autenticación de Maco

ContainerDI.Register<IMacoAuthentication, WSMacoAuthentication>(ContainerDI.LifeStyleContainer.Transient);

Registro del servicio WSMacoProfessionalManager que implementa la interfaz IMacoProfessionalManager. Encargada de gestionar las consultas al servicio Profesional de Maco.

 ContainerDI.Register<IMacoProfessionalManager, WSMacoProfessionalManager>(ContainerDI.LifeStyleContainer.Transient); 

        
 Registro del servicio WSMacoOperatorManager que implementa la interfaz IMacoOperatorManager. Encargada de gestionar las consultas al servicio Operador de Maco

ContainerDI.Register<IMacoOperatorManager, WSMacoOperatorManager>(ContainerDI.LifeStyleContainer.Transient)

Configuración de la API versión Réplica de BBDD

Registro del servicio IConfigContextApiConnection, configuración del contexto de BBDD con el tipo concreto MacoContextConnection. Recibe como parámetros la cadena de conexión de la réplica, en este caso del fichero de configuración app.config, tipo de esquema Maco y nombre del esquema de la BBDD.

var macoContextConnection = new MacoContextConnection( new ManagedConfigConnectionBase<SchemaMacoType>[] { new ManagedConfigConnectionBase<SchemaMacoType>(ConfigurationManager.ConnectionStrings["MACOConnection"].ConnectionString, SchemaMacoType.Maco, "NOMBRE_ESQUEMA_REPLICA_MACO") });


ContainerDI.Register<IConfigContextApiConnection<SchemaMacoType>>(() =>macoContextConnection, ContainerDI.LifeStyleContainer.Transient);

            
Registro del tipo MacoOperatorReplicaManager que implementa la interfaz IMacoOperatorManager. Servicio encargado de consultar datos de operadores vía réplica de BBDD.

        
      

 ContainerDI.Register<IMacoOperatorManager, MacoOperatorReplicaManager>(ContainerDI.LifeStyleContainer.Transient);

        
          

          
Registro del tipo MacoRepository que implementa la interfaz IMacoRepository. Repositorio encargado de consultar datos de Maco vía réplica de BBDD.

        
      

 ContainerDI.Register<IMacoRepository, MacoRepository>(ContainerDI.LifeStyleContainer.Transient); 

        
          
 Registro del tipo MacoModuleManager que implementa la interfaz IMacoModuleManager . Servicio engargado de consultar datos de módulos en Maco vía réplica de BBDD.

ContainerDI.Register<IMacoModuleManager<object>, MacoModuleManager>(ContainerDI.LifeStyleContainer.Transient); 
}

services.AddMacoOracleServices(macoContextConnection );

A continuación se presenta el código completo del ejemplo de configuración de la versión >= 2.0.0:

 public class Startup
{
	public Startup(IConfiguration configuration)
	{
		Configuration = configuration;
	}

	public IConfiguration Configuration { get; }
	private static string _xmlMacoKey;
	private static TicketValidatorConfig _ticketValidatorConfig;

	// This method gets called by the runtime. Use this method to add services to the container.
	public void ConfigureServices(IServiceCollection services)
	{
		...
		ContainerDI.SetAsyncScopedLifestyle();
		ContainerDI.RegisterServices(ref services); 
	}

	// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
	public void Configure(IApplicationBuilder app, IHostingEnvironment env)
	{
		ContainerDI.RegisterMvcControllers(ref app);
		ContainerDI.RegisterMvcViewComponents(ref app);

		app.UseDeveloperExceptionPage();

		this.InitializeContainer(); 
		...
	}

	/// <summary>
	/// Inicializador de contenedor utilizando el inyector de dependencia ContainerDI.
	/// </summary>
	private void InitializeContainer()
	{
		#region registrar maco
			_xmlMacoKey = Configuration.GetSection("MacoApiClient:MacoXmlKey").Value;

			_ticketValidatorConfig = new TicketValidatorConfig
			{
				RsaKey = _xmlMacoKey,
				ReferenceDate = DateTime.Now,
				FutureTicketToleranceMillis = 0,
				TicketTtlMillis = 24 * 60 * 60 * 1000,

				TicketValidations = new HashSet<TicketValidationType>()
			};
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Signature); //SignatureTicketValidation: Valida que la firma es correcta 
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Expired); //ExpiredTicketValidation: Valida que el ticket no este caducado 
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Future); //FutureTicketValidation: Valida que el ticket no sea futuro 
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Permission); //PermissionTicketValidation: Valida que el permiso requerido se encuentre en el ticket 

			ContainerDI.Register<IMacoExceptionManager, MacoExceptionManager>(ContainerDI.LifeStyleContainer.Transient);
			ContainerDI.Register<IMacoUserTransformer, WSMacoUserTransformer>(ContainerDI.LifeStyleContainer.Transient);
			

			var macoApiConfig = new MacoApiConfig(Configuration.GetSection("WebServiceLocator:ServiceAddressMaco").Value)
			{
				ModuleCode = Configuration.GetSection("MacoApiClient:MacoModule").Value
			};
			macoApiConfig.EndPoints = new Dictionary<MacoApiClient.WebService.Api.Entity.EndPointType, string>
			{
				{ MacoApiClient.WebService.Api.Entity.EndPointType.Validacion, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoValidacion").Value },
				{ MacoApiClient.WebService.Api.Entity.EndPointType.Operador, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoOperador").Value},
				{ MacoApiClient.WebService.Api.Entity.EndPointType.Profesional, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoProfesional").Value }
			};

			ContainerDI.Register<IMacoApiConfig>(() => macoApiConfig, ContainerDI.LifeStyleContainer.Transient);
			ContainerDI.Register<ITicketValidator>(() => new TicketValidator(_ticketValidatorConfig), ContainerDI.LifeStyleContainer.Transient);
			ContainerDI.Register<IWsMacoActions>(() => new WSMacoManager(macoApiConfig), ContainerDI.LifeStyleContainer.Transient);
			ContainerDI.Register<IMacoAuthentication, WSMacoAuthentication>(ContainerDI.LifeStyleContainer.Transient);
			ContainerDI.Register<IMacoOperatorManager, WSMacoOperatorManager>(ContainerDI.LifeStyleContainer.Transient);


            //descomentar en caso de consultar datos de módulo y perfil vía réplica de BBDD
 			//var macoContextConnection = new MacoContextConnection( new ManagedConfigConnectionBase<SchemaMacoType>[] { 
			//new ManagedConfigConnectionBase<SchemaMacoType>(ConfigurationManager.ConnectionStrings["MACOConnection"].ConnectionString, SchemaMacoType.Maco, "NOMBRE_ESQUEMA_REPLICA_MACO") }); 
			//ContainerDI.Register<IConfigContextApiConnection<SchemaMacoType>>(() =>macoContextConnection, ContainerDI.LifeStyleContainer.Transient);
			//ContainerDI.Register<IMacoOperatorManager, MacoOperatorReplicaManager>(ContainerDI.LifeStyleContainer.Transient);
			//ContainerDI.Register<IMacoRepository, MacoRepository>(ContainerDI.LifeStyleContainer.Transient);
			//ContainerDI.Register<IMacoModuleManager<object>, MacoModuleManager>(ContainerDI.LifeStyleContainer.Transient);

		#endregion registrar maco	
	}
}

using SAS.MacoApiClient.WebService.IoC;
//using SAS.MacoApiClient.ManagedDataAccess.Oracle.IoC; 
public class Startup
{
	public Startup(IConfiguration configuration)
	{
		Configuration = configuration;
	}

	public IConfiguration Configuration { get; }
	private static string _xmlMacoKey;
	private static TicketValidatorConfig _ticketValidatorConfig;

	// This method gets called by the runtime. Use this method to add services to the container.
	public void ConfigureServices(IServiceCollection services)
	{

		#region Inyección de dependencia utilizando el inyector por defecto de .NET

			#region registrar Maco
			_xmlMacoKey = Configuration.GetSection("MacoApiClient:MacoXmlKey").Value;

			_ticketValidatorConfig = new TicketValidatorConfig
			{
				RsaKey = _xmlMacoKey,
				ReferenceDate = DateTime.Now,
				FutureTicketToleranceMillis = 0,
				TicketTtlMillis = 24 * 60 * 60 * 1000,

				TicketValidations = new HashSet<TicketValidationType>()
			};
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Signature); //SignatureTicketValidation: Valida que la firma es correcta 
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Expired); //ExpiredTicketValidation: Valida que el ticket no este caducado 
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Future); //FutureTicketValidation: Valida que el ticket no sea futuro 
			_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Permission); //PermissionTicketValidation: Valida que el permiso requerido se encuentre en el ticket 

			var macoApiConfig = new MacoApiConfig(Configuration.GetSection("WebServiceLocator:ServiceAddressMaco").Value)
			{
				ModuleCode = Configuration.GetSection("MacoApiClient:MacoModule").Value
			};
			macoApiConfig.EndPoints = new Dictionary<SAS.MacoApiClient.WebService.Api.Entity.EndPointType, string>
			{
				{ SAS.MacoApiClient.WebService.Api.Entity.EndPointType.Validacion, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoValidacion").Value },
				{ SAS.MacoApiClient.WebService.Api.Entity.EndPointType.Operador, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoOperador").Value},
				{ SAS.MacoApiClient.WebService.Api.Entity.EndPointType.Profesional, Configuration.GetSection("WebServiceLocator:EndPointAddressMacoProfesional").Value }
			};

			//registro de servicios de la API MacoApiClient implementación webservices utilizando el inyector de dependencia por defecto de .NET
			services.AddMacoWSServices(macoApiConfig, _ticketValidatorConfig);
			
			#endregion
			#region registrar servicios Maco que acceden a datos vía réplica BBDD
				//descomentar en caso de consultar datos de módulo y perfil vía réplica de BBDD 
				//var macoContextConnection = new MacoContextConnection( new ManagedConfigConnectionBase<SchemaMacoType>[] { 
					//new ManagedConfigConnectionBase<SchemaMacoType>(ConfigurationManager.ConnectionStrings["MACOConnection"].ConnectionString, SchemaMacoType.Maco, "NOMBRE_ESQUEMA_REPLICA_MACO") }); 
			   //services.AddMacoOracleServices(macoContextConnection);
			#endregion

		#endregion Inyección de dependencia utilizando el inyector por defecto de .NET
	}
}

Uso

A continuación se describe el uso de la librería.

Funcionalidades utilizando Servicio Web de Maco Autenticación

Para poder realizar la autenticación y autorización con Maco se deberá de hacer uso de la clase MacoAuthentication, mediante el uso del método LoginAuthentication() que devuelve un objeto MacoUser, y con el que se podrá realizar la autenticación con Maco. Si la autenticación no se ha podido realizar con éxito se lanzará una excepción de tipo MacoException. .

Ejemplo:

public MacoUser login(string username, string password) { 
	return _macoAuthentication.LoginAuthentication(username, password); 
} 

Para realizar la comprobación de autorización de un módulo concreto con Maco se deberá de hacer uso del método ServiceAuthorization(). Si la autorización no se ha podido realizar con éxito se lanzará una excepción de tipo MacoException.

Ejemplo:

public boolean autorizarServicio(MacoUser user, string requestedService) { 
	return _macoAuthentication.ServiceAuthorization(user, requestedService); 
}

Para realizar la comprobación de autenticación y autorización de un módulo concreto con Maco se deberá de hacer uso del método LoginAuthentication, pasando como argumento username, password y código del módulo en Maco. Si la autorización no se ha podido realizar con éxito se lanzará una excepción de tipo MacoException.

Ejemplo:

public boolean LoginAuthentication(string username, string password,string moduleCode) { 
	return _macoAuthentication.LoginAuthentication(username, password,moduleCode); 
}

Operadores

Para poder buscar operadores en Maco se deberá de hacer uso de la función FindOperator, para un solo resultado, o FindOperators, para múltiples resultados. Los campos que pueden ser usados en el dto para la búsqueda son:

UsersPerPage: Número de usuarios por página PageNumber: Numero de la página a recibir Name: Nombre a buscar (puede ser parcial) FirstSurname: Apellido 1 (puede ser parcial) SecondSurname: Apellido 2 (Puede ser parcial) Login: login del usuario DirayaCode: código de diraya ModuleCode: código del módulo UnitCode: código de la unidad organizativa UnitTypeCode: tipo de unidad organizativa

Ejemplo:

public MacoUser BuscarUsuarioPorLogin(string login) { 
	QuerysUserSearchDto querysUserSearchDto= new QuerysUserSearchDto(); 
	querysUserSearchDto.PageNumber= 1; 
	querysUserSearchDto.UsersPerPage = 1; 
	querysUserSearchDto.Login = login; 
	return _macoOperatorManager.FindOperator(usuarioMacoQueRealizaLaPeticion, querysUserSearchDto); 
} 

//Permite la búsqueda por nombre, devuelve una lista de usuarios 
public PaginationList<MacoUser> BuscarUsuariosPorNombre(string name) { 
	QuerysUserSearchDto querysUserSearchDto= new QuerysUserSearchDto(); 
	querysUserSearchDto.PageNumber = 1; 
	querysUserSearchDto.UsersPerPage = 10; 
	querysUserSearchDto.Name = name; 
	return _macoOperatorManager.FindOperators(usuarioMacoQueRealizaLaPeticion, querysUserSearchDto); 
}

Para realizar un cambio de contraseña de un usuario en Maco, se deberá de hacer uso de la función ChangeUserPassword:

//realiza un cambio de contraseña 
public void CambiarContraseña(MacoUser user, string password) { 
	//la manera de generar una contraseña que acepte MACO puede variar y debe de ser consultada en la documentación de MACO.
	var passwordRSA = MacoUtil.RSA(password,rsaKey); 
	// rsaKey es la clave pública de Maco: <RSAKeyValue><Modulus>...</RSAKeyValue> proporcionada por la Oficina Técnica de Interoperabilidad 
	_macoOperatorManager.ChangeUserPassword(user, passwordRSA); 
}

siendo _macoOperatorManager un objeto de tipo IMacoOperatorManager.

Profesionales

Para poder buscar profesionales en Maco se deberá de hacer uso de la función FindProfessional, para un solo resultado, o FindProfessionals ,para múltiples resultados, de la misma manera que se realiza con los Operadores. Los campos que, adicionalmente a los descritos en Operador, podrán ser usados son los siguientes:

• • • ProfessionalCode: Código de profesional.
    • LicenseNumber: Código de Colegiado.
    • ProfessionalType : Tipo de profesional.
    • ProfessionalSpecialtyCode : Código de la especialidad del profesional.
    • StatusCode: Estado del usuario, cuyos posibles valores son:StatusAny, StatusActive, StatusPassive, StatusLocked, StatusChangePassword.

Validación de tickets Maco

• • Si se quiere validar un ticket + permisos concretos, se realizará pasándole la lista de permisos a validar en la llamada IsTicketValid. Por ejemplo:

List<string> permissions = new List<string>() { "CUSTOMPERMISSION", "CUSTOMPERMISSION2" }; 
HashSet<string> hSetPermissions = new HashSet<string>(permissions); 
return new _ticketValidator.IsTicketValid(ticket,null, hSetPermissions)

• • Si solo se quiere validar los valores por defecto, registrados por inyección de dependencia en la configuración TicketValidatorConfig, no será necesario pasarle la lista de permisos:

private bool Validate(string ticket, string signature) { 
	return new _ticketValidator.IsTicketValid(ticket, signature); 
}

Siendo _ticketValidator un objeto de tipo ITicketValidator.

• • En el siguiente ejemplo se muestra la validación de ticket, firma, operación y fecha de un mensaje:

private bool ValidarTicket(string sTicketEntrada, string sFirmaEntrada, string sOperacionEntrada, DateTime dtFechaMensaje

SAS.MacoApiClient

Introducción

En el presente documento se presenta la librería SAS.MacoApiClient, componente .NET Standar 2.0, para el acceso a datos de Maco.

Esta librería permite el acceso a los datos de Maco utilizando dos implementaciones diferentes: una que utiliza internamente el servicio web de Maco y otra que utiliza réplica de BBDD.

La versión actual de la librería , en su versión acceso a réplica de BBDD, solo dispone de métodos para acceso a la información de módulos y perfiles.

Dependencias

Errores conocidos

• Bug al parsear fecha en formato cadena a un formato DateTime determinado.

  Problema al parsear una fecha en formato cadena, en la que la hora solo contiene un dígito. Corregido desde de la version 2.0.2

Historial de cambios

Histórico de cambios realizados en la librería

• • 2.0.0 - Versión inicial .NET Standard 2.0. Se refactoriza el proyecto a la versión .NET Standard del .NET Framework. Proyecto MacoApiClient

    • src/Api/Boundary

      • IMacoAuthentication: Interfaz del servicio de autenticación de Maco.

           bool ServiceAuthorization(MacoUser macoUser, string requestedService);
           MacoUser LoginAuthentication(string username, string password, string moduleCode = null);
           MacoUser LoginAuthentication(MacoUser macoUser);
        

      • IMacoOperatorManager: Interfaz del servicio de gestión de Operadores Maco. Permite consultar operadores y cambiarles el password

        MacoUser FindOperator(MacoUser petitionerUser, QuerysUserSearchDto querysUserSearchDto);
        PaginationList<MacoUser> FindOperators(MacoUser petitionerUser, QuerysUserSearchDto querysUserSearchDto);
        void ChangeUserPassword(MacoUser user, string password);
        

      • IMacoProfessionalManager: Interfaz del servicio que consulta datos de profesionales

            MacoUser FindProfessional(MacoUser petitionerUser, QuerysUserSearchDto querysUserSearchDto);
            PaginationList<MacoUser> FindProfessionals(MacoUser petitionerUser, QuerysUserSearchDto querysUserSearchDto);
        

      • MacoAuthentication. Servicio que implementa la interfaz IMacoAuthentication
      • MacoOperatorManager. Servicio que implementa la interfaz IMacoOperatorManager
      • MacoProfessionalManager. Servicio que implementa la interfaz IMacoProfessionalManager

    • src/Api/control/messages

      • CambioClaveOperadorMessage: Tipo que encapsula el mensaje Maco de cambio clave de operador y que es enviado al servicio web de Maco. Deriva de MacoMessage y le añade a éste información de la nueva contraseña del operador y del atributo cambio_clave con valor 'S'

      • ConsultarOperadorMessage: Tipo que encapsula el mensaje Maco de consulta operador y que es enviado al servicio web de Maco. Deriva de MacoMessage y le añade a éste información de: Número de resultados por página, número de página, nombre del operador, login, código diraya, número de profesional, número colegiado, tipo profesional etc.

      • ConsultarProfesionalMessage: Tipo que encapsula el mensaje Maco de consulta profesional y que es enviado al servicio web de Maco. Deriva de MacoMessage.

      • MacoMessage: Tipo que encapsula el mensaje Maco que es enviado al servicio web de Maco. Deriva de Message y le añade a éste información para comprobar que el usuario pertenece al módulo destino y que se devuelva los datos del operador registrados en Operador Único.

        [!NOTA] Para más información sobre estos parámetros, consulte la Documentación Técnica del Servicio Web de Maco.

      • MacoVerificationType: Enumerado con el tipo de verificación que se solicita al servicio web de Maco: Ticket, Password o Normal

      • Message: Tipo que encapsula el mensaje Maco que es enviado al servicio web de Maco

      • PreValidarMessage: Tipo que encapsula el mensaje Maco de prevalidar que es enviado al servicio web de Maco. Deriva de MacoMessage y le añade a éste información sobre: login, password, código módulo, unidad y perfil.

      • ValidarCabeceraMessage:Tipo que encapsula el mensaje Maco de validar cabecera que es enviado al servicio web de Maco. Deriva de MacoMessage y le añade a éste información sobre código de entidad destino.

    • src/Api/control/

      • IMacoExceptionManager: Interfaz que permite comprobar si la respuesta del servicio web de Maco contiene un nodo error así como lanzar una excepción de tipo MacoBusinessException

        void ThrowIfErrorIsPresent(XmlDocument response);
        void ThrowException(short errorCode, string errorDescription = "");
        

      • MacoExceptionManager: Clase que implementa la interfaz IMacoExceptionManager

    • src/Api/entity

      • Config
        • IMacoApiConfig: Configuración de la api de Maco en su versión consulta por servicio web. Contiene información de: url del servicio web de Maco, código del módulo, end point del servicio web de Maco
        • MacoApiConfig: Implementación de la interfaz IMacoApiConfig
      • Exception: listado de excepciones soportado por la librería: CouldNotCreateProfessional, CouldNotCreateRole, etc.
      • Rules
        • ModulePerfilValueRuleForQuerysUser: Validación del dto del criterio de búsqueda,QuerysUserSearchDto, a nivel de perfil. Lanza una excepción de tipo MacoFilterLocationException en caso de que el atributo código de Rol, RoleCode, se encuentre vacío.
        • ModuleValueRuleForQuerysUser.Validación del dto del criterio de búsqueda,QuerysUserSearchDto, a nivel de módulo. Lanza una excepción de tipo MacoFilterLocationException en caso de que el atributo código de módulo, ModuleCode, se encuentre vacío.
      • Validation
        • IRule: Interfaz genérica de validación. Indica si una entidad genérica, TEntity, es válida.

          bool IsValid(TEntity entity);
          

        • ValidatorHelper: Clase de soporte para validaciones de entidades. Aplica una lista de reglas IRule a una entidad genérica TEntity.
      • EndPointType: Enumerado que indica el tipo de endpoint: Validación, Operador o Profesional
      • MacoMessageType: Enumerado que indica el tipo de mensaje Maco: ValidarCabecera, ConsultaOperador, Cambioclaveoperador, Prevalidar.
      • PaginationList: Clase soporte para paginación de elementos.
      • QuerysUserSearchDto: Dto en el que se define los criterios de filtros de usuarios

    • src/Ticket

      • Boundary
        • ITicketValidator: Interfaz de validación de Tickets Maco

          TicketValidatorConfig Config { get; set; }
          HashSet<TicketValidation> Validations { get; }
          bool IsTicketValid(string ticket, string ticketSignature = null,   HashSet<string> permissions = null);
          

        • TicketValidator: Implementación de la interfaz ITicketValidator
      • Control
        • ExpiredTicketValidation: Valida la expiración de un ticket.
        • FutureTicketValidation: Validación de un ticket futuro
        • PermissionTicketValidation: Validación de los permisos de un ticket
        • RSACryptoServiceProviderExtensions: Extensión del método RSA de encriptación
        • SignatureTicketValidation: Validación de la firma de un ticket.
        • TicketValidation: Clase abstracta de validación de un ticket.
      • Entity
        • TicketValidationType: Enumerado con los tipos de validación de ticket soportados: Future, Expired, Permission, Signature.
        • TicketValidatorConfig: Configuración de la validación de tickets.

    • src/User

      • Boundary
        • IMacoUserManager: Interfaz para la creación de usuarios Maco, a partir de un XmlNode, XmlDocument o un string que contiene la respuesta xml del servicio web de Maco.

          MacoUser NewMacoUser(XmlNode oper);
          MacoUser NewMacoUser(XmlDocument doc);     
          PaginationList<MacoUser> ProccessUsersResponse(string xmlResponse, int? pageNumber, int? usersPerPage);
          

        • MacoUserManager: Implementa la interfaz IMacoUserManager.
      • Entity
        • ContactInformation: Entidad en el que se define información de contacto del usuario: emails, faxes, teléfonos móvil, etc
        • MacoAuthority: Entidad con información de autorización de Maco: Código de Rol y Rol.
        • MacoLocation: Entidad con información de localización: código de módulo, código y nombre de unidad
        • MacoUser: Entidad de usuario Maco. Contiene información de: DirayaCode, Login, PasswordMd5, PasswordDate, ModuleCode, etc
        • MacoUserStatus: Enumerado con los tipos de estado en lo que puede estar una entidad de usuario Maco: StatusAny, StatusActive, StatusPasive, StatusLocked, StatusChangePassword.
        • Person: Entidad persona, en la que se define información de: Name, FirstSurname, SecondSurname, IdentifierTypeCode, IdentifierType, IdentifierCode.
        • Professional: Entidad Profesional de tipo Person y en la que se define además: Código de profesional, número de licencia, tipo de profesional y código de especialidad del profesional.

    • src/utils

      • IMacoFactory: Clase utilidad para la creación de diversas entidades Maco, en el caso de no usar inyección de dependencia.
      • MacoUtil: Define diversas utilidades: parsear fecha de cadena a tipo DateTime a partir un array de formatos de fechas determinados, SubstringAfterLast(string ticket, string s): dada una cadena, y una subcadena, obtiene la subcadena existente después de la subcadena pasada por parámetro, etc.

    • src/WebService

      • Boundary
        • IWsMacoActions: Interfaz con las posibles acciones realizadas con el servicio web de Maco

          string PreValidar(Api.Control.Messages.Message message);
          string ValidarCabecera(Api.Control.Messages.Message message);
          string ConsultarOperador(Api.Control.Messages.Message message);
          string CambioClaveOperador(Api.Control.Messages.Message message);
          string ConsultarProfesional(Api.Control.Messages.Message message);
          string ConsultarListaProfesionales(Api.Control.Messages.Message message);
          string ConsultarListaProfesionalesUnidad(Api.Control.Messages.Message message);
          string ConsultarAOProfesionalYModulo(Api.Control.Messages.Message message);
          

        • WsMacoManager: Implementación de la interfaz IWsMacoActions.
      • Control
        • WSOperadorSoap. Clase proxy del servicio web Maco para la gestión de operadores.
        • WSProfesionalSoap. Clase proxy del servicio web Maco para la gestión de profesionales.
        • WSValidacionSoap. Clase proxy del servicio web Maco para las operaciones de validación.

  • 2.0.1 - Actualizar la versión de las librerías utilizadas del namespaces System.ServiceModel a la 4.5.3

  • 2.0.2 - Se sustituye en la definición del formato de fecha 'dd/MM/yyyy HH:mm:ss' , el HH por H, para que se contemple la hora tanto para uno como dos dígitos.

  • 2.1.0 - Se añade implementación por réplica de BBDD para la consulta de módulos y perfil.
    Proyecto MacoApiClient

    • src/Api/Boundary
      • IMacoModuleManager: Se añade servicio de consulta de módulos y perfiles

        MacoLocation GetModuleByCode(IGenericAuthContext<T> context, QuerysUserSearchDto filtro);
        MacoLocation GetRoleModuleByCode(IGenericAuthContext<T> context, QuerysUserSearchDto filtro);
        

      • MacoModuleManager : Implementa la interfaz IMacoModuleManager

    Proyecto SAS.MacoApiClient.Core : Nuevo proyecto añadido a la solución

    • Boundary/Contracts/Repositories
      • IMacoRepository: Se añade interfaz repositorio de acceso a datos de módulos y roles de Maco utilizando réplicas de BBDD Oracle. Obtener módulo por código

        Modulo GetModuleByCode(QueryCriteriaModule filtro);
        

        Obtener perfil a través del código del módulo

        ModuloPerfil GetRoleModuleByCode(QueryCriteriaModule filtro);
        

    • Boundary/Entity/
      • Criteria/QueryCriteriaModule: Criterios de filtros para la entidad módulo y perfil
      • Modulo: Entidad módulo
      • ModuloPerfil: Entidad módulo/perfil

    Proyecto SAS.MacoApiClient.ManagedDataAccess.Oracle : Nuevo proyecto añadido a la solución. Acceso a datos de Maco utilizando réplica de BBDD Oracle

    • Boundary/
      • MacoContextConnection: Clase de configuración del contexto para la conexión con la BBDD. Implementa la interfaz IConfigContextApiConnection. SchemaMacoType es un tipo enumerado en el que se ha definido el tipo de los diferentes esquemas contemplados: Especializada, Bdu o Maco
      • MacoRepository: Clase que implementa la interfaz IMacoRepository. Es la que se comunica con la BBDD
    • Entity
      • EntityFramework: Contiene las diferentes entidades de Entity Framework de la BBDD
      • MacoConexion: Conexión no manejado del contexto Maco
      • SchemaMacoType: tipos de esquemas de BBDD: Especializada, Bdu, Maco. En este caso el esquema utilizado es Maco.

    [!NOTA] >Todo sistema que utilice el modo réplica de BBDD tiene que tener acceso a las tablas de Maco siguientes: ModuloEntity y PerfilModuloEntity .

  • 2.2.0 - Se añade posibilidad de contexto no manejado Proyecto SAS.MacoApiClient.ManagedDataAccess.Oracle :

    • Entity
      • MacoConexion: Se modifica para que no utilice configuración por código en la definición del contexto, es decir, utiliza contexto no manejado: su configuración hay que definirla en fichero de configuración.
      • MacoManagedConexion: Conexión manejado del contexto Maco. En la declaración de la clase se define su tipo de configuración. En este caso: [DbConfigurationType(typeof(ConfiguracionOracleProvider))]

  • 2.3.0 - Se añade posibilidad de configurar tipo de contexto utilizado (manejado o no manejado) Proyecto SAS.MacoApiClient.ManagedDataAccess.Oracle :

    • Boundary/
      • MacoContextConnection: Se implementa el nuevo método GetIsManagedContext de la interfaz IConfigContextApiConnection, el cual devuelve si para la configuración del tipo de esquema que se pasa por parámetro se utiliza contexto manejado o no.

        public bool GetIsManagedContext(SchemaMacoType tipo)
        {
            return this.configuracion.FirstOrDefault(d => d.ShemaType == tipo).IsManagedContext;
        }
        

      • MacoRepository: Se modifica el método GetConexion() para que, dependiendo del parámetro IsManagedContext, de la configuración, se devuelva una conexión Maco manejada o no.

  • 2.4.0 - Se añade la versión réplica del método FindOperator Proyecto SAS.MacoApiClient :

    • src/Api/Boundary/
      • MacoOperatorReplicaManager: Implementa el método FindOperator de la interfaz IMacoOperatorManager en su versión réplica de BBDD. Proyecto SAS.MacoApiClient.ManagedDataAccess.Oracle :
    • /Boundary

      • MacoRepository: Se añade método GetOperadorByDirayaCode en el que se obtiene los datos del profesional u operador a traves de su código Diraya. Si devuelve el CNP indica que el usuario que se obtiene es un profesional. En el caso de que el número de profesional devuelto sea null, se está recuperando una persona operador (no profesional).

        public IList GetOperadorByDirayaCode(string dirayaCode)

        [!NOTA] >En esta versión el método GetOperadorByDirayaCode sólo devuelve: Nombre, Apellidos y NumeroProfesional. Está pendiende que el profesional/operador devuelto contenga la misma información que la versión ServicioWeb del método FindOperator.

  • 2.4.1 - Se actualiza la versión del componente SAS.Common.Oracle a v1.3.3, en el que se actualiza los componentes Oracle.ManagedDataAccess y Oracle.ManagedDataAccess.EntityFramework a la versión 19.6.0

  • 2.4.2 - Se actualiza la versión del componente SAS.Common.Kernel a v1.1.0

  • 2.4.3 - Se añade modo de Seguridad Básica para la comunicación HTTPS de los servicios web de Maco Debido a que el protocolo de comunicación HTTP de los servicios web de maco han cambiado a HTTPS, se ha añadido la posibilidad de comunicación de transporte con cliente anónimo. Los cambios han sido los siguientes

    • MacoApiClient/src/WebService/Boundary
      • WsMacoManager

        private static readonly BasicHttpBinding Binding = new BasicHttpBinding
      {
          MaxReceivedMessageSize = 2147483647,
          MaxBufferSize = 2147483647
      };
      

      Se añade un objeto de tipo BasicHttpsBinding, el cual utiliza modo de seguridad básico de Transporte

       private static readonly BasicHttpsBinding HttpsBinding = new BasicHttpsBinding
      {
          MaxReceivedMessageSize = 2147483647,
          MaxBufferSize = 2147483647
      };
      

      Se crea el método GetBinding, el cual devuelve el objeto HttpsBinding o Binding, según se esté utilizando comunicación HTTPS o no.

       /// <summary>
      /// Obtiene un objeto BasicHttpBinding o BasicHttpsBinding
      /// </summary>
      /// <param name="endpoint"></param>
      /// <returns></returns>
      private HttpBindingBase GetBinding(EndpointAddress endpoint)
      {
          if (endpoint.Uri.Scheme.ToLower() == "https")
          {
              return HttpsBinding;
          }            
          return Binding;
      }
      

      Por último, a la hora de crear la clase proxy, el objeto de tipo Binding que se pasa es el que devuelve el método GetBinding.

        using (var proxy = new GenericProxy<WSValidacionSoap>(GetBinding(Endpoint), Endpoint))
          {
          ...
          }
      

Integración de la librería

Acceder a nuget e instalar la librería SAS.MacoApiClient.

Configuración

La configuración de la API depende del tipo de implementación que se vaya a utilizar, según se acceda a los datos mediante el Servicio Web de Maco o mediante réplicas. Veamos cada una de ellas:

La siguiente configuración se añadiría en la clase Startup del proyecto MVC:

         Primero, en el fichero Startup.cs, método ConfigureServices, inicializamos el contenedor de inyección de dependencia:

        public void ConfigureServices(IServiceCollection services)

        {

          ...

          ContainerDI.SetAsyncScopedLifestyle(); // establecer estilo de vida por defecto del contenedor de inyección. Permite procesar tanto operaciones asíncronas como síncronas

          ContainerDI.RegisterServices(ref services); 

        ...

      }

        ContainerDI, clase del componente común SAS.Util.Injection, el cual permite el registro por inyección de dependencia de los diferentes servicios y tipos utilizados en el sistema.

Configuración de la API versión Servicio Web En el fichero appsettings se definen secciones en las que se establece configuración de Maco y servicio web de Maco

(1)  "MacoApiClient": {
    "XmlKey": "CLAVEPUBLICAMACO",
    "Module": "MODULOMACO"
      },
(2)  "WebServiceLocator": {
    "ServiceAddressMaco": "http://WEBSERVICEMACO/",
    },

(1) Configuración de la clave púba de Maco , XmlKey, y código del módulo Maco, "MODULOMACO. La Oficina  Técnica de Interoperabilidad es la que proporciona esta información.

(2) Configuración de la dirección url del servicio web de Maco, "WEBSERVICEMACO"

En el fichero Startup.cs, método InitializeContainer, añadir la siguiente configuración:

(3) var ticketValidatorConfig = new TicketValidatorConfig

            {   
                RsaKey = ConfigurationManager.AppSettings["MacoApiClient:XmlKey"],
                ReferenceDate = DateTime.Now,
                FutureTicketToleranceMillis = -1,
                TicketTtlMillis = 24 * 60 * 60 * 1000,
                TicketValidations = new HashSet<TicketValidationType>()
            };
            // SignatureTicketValidation: Valida que la firma es correcta 
            ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Signature); 
            // ExpiredTicketValidation: Valida que el ticket no este caducado 
            ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Expired); 
            // FutureTicketValidation: Valida que el ticket no sea futuro 
            ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Future);
            // PermissionTicketValidation: Valida que el permiso requerido se encuentre en el ticket 
            ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Permission); 
(4) ContainerDI.Register<ITicketValidator>(() => new TicketValidator(ticketValidatorConfig), ContainerDI.LifeStyleContainer.Transient);
(5) ContainerDI.Register<IMacoExceptionManager, MacoExceptionManager>(ContainerDI.LifeStyleContainer.Transient);
(6) ContainerDI.Register<IMacoUserManager, MacoUserManager>(ContainerDI.LifeStyleContainer.Transient);
(7)  var macoApiConfig = new MacoApiConfig(this.Configuration.GetSection("WebServiceLocator:ServiceAddressMaco").Value)
            {
                ModuleCode = this.Configuration.GetSection("MacoApiClient:Module").Value
            };
(8) ContainerDI.Register<IMacoApiConfig>(() => macoApiConfig, ContainerDI.LifeStyleContainer.Transient);
(9) ContainerDI.Register<IWsMacoActions>(() => new WsMacoManager(macoApiConfig), ContainerDI.LifeStyleContainer.Transient);
(10) ContainerDI.Register<IMacoAuthentication, MacoAuthentication>(ContainerDI.LifeStyleContainer.Transient);

(3) Configuración de la validación del ticket de Maco

(4) Registro del tipo TicketValidator que implementa la interfaz ITicketValidator

(5) Registro del tipo MacoExceptionManager que implementa la interfaz IMacoExceptionManager

(6) Registro del tipo MacoUserManager que implementa la interfaz IMacoUserManager

(7) Configuración de la api de Maco, en la que se le pasa la dirección del servicio web de Maco y el código del módulo

(8) Registro del tipo MacoApiConfig que implementa la interfaz IMacoApiConfig

(9) Registro del servicio WsMacoManager que implementa la interfaz IWsMacoActions

(10) Registro del servicio MacoAuthentication que implementa la interfaz IMacoAuthentication

Configuración de la API versión Réplica de BBDD

    (11) ContainerDI.Register<IConfigContextApiConnection<SchemaMacoType>>(() =>
            new MacoContextConnection(
              new ManagedConfigConnectionBase<SchemaMacoType>[]
              {
                    new ManagedConfigConnectionBase<SchemaMacoType>(ConfigurationManager.ConnectionStrings["MACOConnection"].ConnectionString, SchemaMacoType.Maco, "REP_PRO_MACO")
              })
            , ContainerDI.LifeStyleContainer.Transient);
    (12) ContainerDI.Register<IMacoRepository, MacoRepository>(ContainerDI.LifeStyleContainer.Transient);
    (13) ContainerDI.Register<IMacoModuleManager<object>, MacoModuleManager>(ContainerDI.LifeStyleContainer.Transient); 

         (11) Registro del servicio IConfigContextApiConnection, configuración del contexto de BBDD con el tipo concreto MacoContextConnection. Recibe como parámetros la cadena de conexión de la réplica, tipo de esquema Maco y nombre del esquema de la BBDD.

         (12) Registro del tipo MacoRepository que implementa la interfaz IMacoRepository

         (13) Registro del tipo MacoModuleManager que implementa la interfaz IMacoModuleManager

Uso

A continuación se describe el uso de la librería.

Funcionalidades utilizando Servicio Web de Maco Autenticación

Para poder realizar la autenticación y autorización con Maco se deberá de hacer uso de la clase MacoAuthentication, mediante el uso del método .loginAuthentication() que devuelve un objeto MacoUser, y con el que se podrá realizar la autenticación con Maco. Si la autenticación no se ha podido realizar con existo se lanzara una excepción de tipo MacoException.

Ejemplo:

  public MacoUser login(string username, string password) {
        return _macoAuthentication.LoginAuthentication(username, password);
    }

Para realizar la comprobación de autorización de un módulo concreto con Maco se deberá de hacer uso del método .ServiceAuthorization(). Si la autorización no se ha podido realizar con éxito se lanzará una excepción de tipo MacoException.

Ejemplo:

  public boolean autorizarServicio(MacoUser user, string requestedService) {
        return _macoAuthentication.ServiceAuthorization(user, requestedService);
    }

Operadores

Para poder buscar operadores en Maco se deberá de hacer uso de la función FindOperator, para un solo resultado, o FindOperators, para múltiples resultados. Los campos que pueden ser usados en el dto para la búsqueda son:

UsersPerPage: Número de usuarios por página PageNumber: Numero de la página a recibir Name: Nombre a buscar (puede ser parcial) FirstSurname: Apellido 1 (puede ser parcial) SecondSurname: Apellido 2 (Puede ser parcial) Login: login del usuario DirayaCode: código de diraya ModuleCode: código del módulo UnitCode: código de la unidad organizativa UnitTypeCode: tipo de unidad organizativa

Ejemplo:

  public MacoUser BuscarUsuarioPorLogin(string login) {
       QuerysUserSearchDto querysUserSearchDto= new QuerysUserSearchDto();
       querysUserSearchDto.PageNumber= 1;
       querysUserSearchDto.UsersPerPage = 1;
       querysUserSearchDto.Login = login;
       return _macoOperatorManager.FindOperator(usuarioMacoQueRealizaLaPeticion, querysUserSearchDto);
    }
    //Permite la búsqueda por nombre, devuelve una lista de usuarios
    public PaginationList<MacoUser> BuscarUsuariosPorNombre(string name) {
       QuerysUserSearchDto querysUserSearchDto= new QuerysUserSearchDto();
        querysUserSearchDto.PageNumber = 1;
        querysUserSearchDto.UsersPerPage = 10;
        querysUserSearchDto.Name = name;
        return _macoOperatorManager.FindOperators(usuarioMacoQueRealizaLaPeticion, querysUserSearchDto); 
    }

Para realizar un cambio de contraseña de un usuario en Maco, se deberá de hacer uso de la función ChangeUserPassword:

    //realiza un cambio de contraseña
    public MacoUser CambiarContraseña(MacoUser user, string password) {
        //la manera de generar una contraseña que acepte MACO puede variar y debe de ser consultada en la documentación de MACO.
        return _macoOperatorManager.ChangeUserPassword(user, password);
    }

siendo _macoOperatorManager un objeto de tipo IMacoOperatorManager.

Profesionales

Para poder buscar profesionales en Maco se deberá de hacer uso de la función FindProfessional, para un solo resultado, o FindProfessionals ,para múltiples resultados, de la misma manera que se realiza con los Operadores. Los campos que, adicionalmente a los descritos en Operador, podrán ser usados son los siguientes:

ProfessionalCode: Código de profesional. LicenseNumber: Código de Colegiado. ProfessionalType : Tipo de profesional. ProfessionalSpecialtyCode : Código de la especialidad del profesional. StatusCode: Estado del usuario, cuyos posibles valores son:StatusAny, StatusActive, StatusPassive, StatusLocked, StatusChangePassword.

Validación de tickets Maco El siguiente método permite obtener ticket y firma, pasando al servicio web de Maco: login,password y código módulo Maco

)
        {
            

var 

_xmlMacoKey = 

"CLAVE_PUBLICA_MACO";
           

 var result;
            var _ticketValidatorConfig = new TicketValidatorConfig
            {
                RsaKey = _xmlMacoKey,
                ReferenceDate = dtFechaMensaje,
          

  FutureTicketToleranceMillis = 0,
        

      TicketTtlMillis = 24 * 60 * 

60 

* 1000,

               

TicketValidations = new 

HashSet<TicketValidationType>()
            };
            

_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Signature); //SignatureTicketValidation: Valida que la firma es correcta 
          

_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Expired); //ExpiredTicketValidation: Valida que el ticket no este caducado 
         

Si se quiere validar un ticket + permisos concretos, se realizará pasándole la lista de permisos a validar en la llamada IsTicketValid. Por ejemplo:

    List<string> permissions = new List<string>() { "CUSTOMPERMISSION", "CUSTOMPERMISSION2" };
    HashSet<string> hSetPermissions = new HashSet<string>(permissions);
	return new _ticketValidator.IsTicketValid(ticket,null, hSetPermissions)

Si solo se quiere validar los valores por defecto, registrados por inyección de dependencia en la configuración TicketValidatorConfig, no será necesario pasarle la lista de permisos:

   private bool Validate(string ticket, string signature) {
		return new _ticketValidator.IsTicketValid(ticket, signature);
	} 

Siendo _ticketValidator un objeto de tipo ITicketValidator.

Llamada Https a los servicios web de Maco

En la versión 2.4.3 se ha añadido la posibilidad de llamar a las nuevas direcciones HTTPS del servicio Web de Maco.

• • • PRE: https://servicios.pre.sas.junta-andalucia.es/maco/
    • PRO: https://servicios.sas.junta-andalucia.es/maco/ Para ello, definimos en el fichero de configuración de la aplicación, la dirección web y los endpoints de Validación, Operador y Profesional. En el caso de PRE, para una aplicación .NET Core añadiríamos al fichero de configuración appsettings.json:

"WebServiceLocator": {
    "ServiceAddressMaco": "https://servicios.pre.sas.junta-andalucia.es/maco/",
    "EndPointAddressMacoValidacion": "/wsValidacion.asmx",
    "EndPointAddressMacoOperador": "/wsOperador.asmx",
    "EndPointAddressMacoProfesional": "/wsProfesional.asmx"
  }

A continuación, definimos un objeto de tipo MacoApiConfig, al que se le añade: la dirección HTTPS del servicio web de MACO (PRE o PRO), el módulo y los endpoints.

_ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Future); //FutureTicketValidation: Valida que el ticket no sea futuro 
            _ticketValidatorConfig.TicketValidations.Add(TicketValidationType.Permission); //Valida que los permisos son los indicados en el ticket

            List<string> permissions = new List<string>() { sOperacionEntrada }; //si sOperacionEntrada está formado por diferentes permisos separados por un caracter separador, realizar una operación Split por dicho caracter separador
            HashSet<string> hSetPermissions = new HashSet<string>(permissions);

            var ticketValidator = new TicketValidator(_ticketValidatorConfig);
            try
            {
                result = ticketValidator.IsTicketValid(sTicketEntrada, sFirmaEntrada, hSetPermissions);
            }
            

catch (MacoException me)
            {
    

          result = 

false;
     

       }

            

return result;
        

[!NOTA] >En las versiones <= 2.4.2 no era necesario definir los endpoints de maco, la librería MacoApiClient lo añadía por defecto (/wsCentralizada/wsValidacion.asmx)

}

En el ejemplo anterior se crea un objeto de tipo TicketValidator con el operador "new". En el caso de haber usado inyección por dependencia para la configuración de los servicios, sólo habría que obtener una instancia de ITicketValidator y asignarle en el atributo Config, ticketValidator.Config, la configuración _ticketValidatorConfig adecuada.

En el siguiente ejemplo se muestra métdoos de autenticación de un usuario y validación de un ticket utilizando interfaces:

	private IMacoAuthentication _macoAuthentication;
	private ITicketValidator _ticketValidator;


	public UserService( IMacoAuthentication macoAuthentication, ITicketValidator ticketValidator)
	{
		_macoAuthentication = macoAuthentication;
		_ticketValidator = ticketValidator;
	}

	public MacoUser LoginAuthentication(string loginName, string password, string moduleCode)
	{
		try
		{
			return _macoAuthentication.LoginAuthentication(loginName, password, moduleCode);
		}
		catch (Exception ex)
		{
			throw ex;
		}
	}

	public bool IsTicketValid(string ticket, string ticketSignature)
	{
		return _ticketValidator.IsTicketValid( ticket, ticketSignature);
	}