Manual para el desarrollador

Transcripción

1 Manual para el desarrollador Autenticación de Servicios Web con Clave Ciudad V1.0 Página 1 de 13

2 Tabla de contenidos Tabla de contenidos... 2 Revisión histórica... 3 Introducción... 4 Breve descripción Objetivos... 4 Conceptos Básicos:... 4 Servicio... 4 Clientes... 4 Representante... 4 Alias... 4 Token... 5 Sign... 5 Certificado Digital... 5 LoginWS... 5 Secuencia de autenticación y ejecución (Cliente)... 5 Descripción General del Servicio... 6 Referencias... 6 Invocación del LoginWs... 7 Sincronización de Clocks... 7 WSDL del LoginWs... 7 Especificación Técnica del WebService Adminitración de Certificados... 7 Flujo Principal... 7 Generación del documento del TRA (LoginTicketRequest.xml)... 7 Atributos... 8 Generación del Ticket de Requerimiento de Acceso (TRA)... 9 Codificación en Base64 el TRA... 9 Envió del TRA al LOGINWS... 9 Mensajes de Error Extracción y validación del TA Requerimientos de los certificados pertenecientes a los COE Página 2 de 13

3 Revisión Histórica Versión Fecha Edición Descripción /05/2017 Creación del documento Página 3 de 13

4 Introducción Breve descripción Objetivos En este documento se definen los aspectos más importantes del proceso de utilización de servicios web en Clave Ciudad. Conceptos Básicos: Servicio: Es el servicio al cual se intenta dar un acceso autenticado, este puede estar desarrollado en cualquier tecnología, por ejemplo RES o SOAP, el único requisito que posee es implementar los mecanismos de validación de la autenticación que se detallan en este documento, por lo cual deberá tener un parámetro extra pare este fin. Clientes: Los clientes son aplicaciones de software desarrolladas por terceros que utilizan los servicios. Usuario: El usuario o representado es la persona física o jurídica que quiere hacer uso del servicio a través del Cliente y que obligatoriamente posee Clave Ciudad. Cuando el usuario es una persona jurídica obligatoriamente operará a través de un representante, esto es opcional en el caso que usuario sea una persona física. Representante: Es la persona física responsable de crear los Alias de sus representados. Alias: Es una función que está incluida dentro de la aplicación Administración de Certificados que permite efectuar la administración de los accesos a los distintos Clientes. Con el Alias se relacionan los servicios generando de esta forma la autorización de acceso. Es recomendable generar un Alias por Cliente para que cada uno tenga acceso sólo a los servicios asignados. Por ejemplo, el representante tiene un sistema de facturación que accede a servicios del e-arciba y además un sistema de gestión interna que utiliza los servicios de Trámites a Distancias (TAD). Para evitar que los sistemas pudieran tener un acceso indebido, el representante deberá tener dos Alias y darle acceso a cada uno. Página 4 de 13

5 Administrador de Certificados: Es designado por el Representante en el momento que define el Alias. Esta asignación le permitirá agregar un certificado con el que accederá al servicio correspondiente al Alias. Esta también puede ser función del Representante Token: Parámetro que contiene toda la información sobre la autenticación, información sobre el usuario y el representante, tiempo de expiración, etc. Sign: Parámetro que sirve para validar que la información contenida dentro del token fue generada por la y permite verificar que no fue adulterado su contenido por un tercero Certificado Digital: Para poder acceder a un servicio, el cliente debe presentar un certificado de seguridad que fue previamente generado en el sitio de la y determina tanto al usuario como al representante. Los certificados deben estar asociados a un alias y tienen un tiempo de vigencia provisto por la. LoginWS: Es un servicio web SOAP publicado por la cuyo objetivo es que el cliente realice el pedido de autenticación. En el llamado se envía el certificado digital y el nombre del servicio al que se desea acceder. En caso de error en la autenticación, se devolverá un mensaje detallado con un código de error. Si la autenticación fue correcta se devuelve un token y sign con toda la información que necesita el cliente. El token tiene una validez de 12 hs., por lo que el cliente podrá guardarlo y reutilizarlo durante ese tiempo todas las veces que lo necesite. Secuencia de autenticación y ejecución (Cliente): El cliente llama al LoginWS y obtiene el token y sign que le servirá por las próximas 12 hs. El cliente llama al servicio enviándole la información propia del mismo más el token y sign provistos por LoginWs Vencidas las 12 hs., el cliente vuelve a llamar a LoginWs para poder continuar con las próximas ejecuciones del servicio. Página 5 de 13

6 Descripción General del Servicio El WS de Autenticación de Servicios Web con CC (LoginWS) es un servicio B2B ( Business to Business ) que permite que los computadores pertenecientes a la y Entes Externos a la intercambien información en forma directa sin intervención de operadores. En dicha tarea intervienen los siguientes componentes: Un cliente de WS desarrollado por un EE siguiendo las especificaciones de este documento. El WS publicado por la que implementa la autenticación de los computadores del EE (CEE) mediante certificados digitales X.509 y la autorización del mismo como consumidor de un determinado WebService de Negocio (WSN). Al usar especificaciones y protocolos estándares (PKI, XML, CMS, WSDL y SOAP) el cliente puede ser desarrollado con cualquier lenguaje de programación moderno. Para que un Ente Externo a la (EE) esté autorizado a usar un WSN de, deberá realizar un trámite administrativo previo, cuya descripción esta fuera del alcance de este documento. Una vez finalizado exitosamente dicho trámite, el que incluye el alta de los CEE, el EE quedará registrado en el servicio de autorización de como entidad autorizada para usar el WSN. Para que un CEE pueda utilizar efectivamente un WSN, deberá solicitar un Ticket de Acceso (TA) por medio del WS de Autenticación de Servicios Web CC (LoginWS). Dicho requerimiento se realiza mediante el envió de un "Ticket de Requerimiento de Acceso" (TRA) del CEE al LoginWS, mediante mensajería SOAP. El LoginWS realiza la verificación del TRA y si el requerimiento es correcto, devuelve un mensaje que contiene el TA que habilita al CEE a utilizar el WSN solicitado. El TA deberá ser utilizado por el CEE para acceder al WSN. En términos generales, el presente documento detalla las operaciones a realizar para: Generar un "Ticket de Requerimiento de Acceso" (TRA) Invocar el "Web Service de Autenticación y Autorización" (LoginWS) Interpretar el mensaje de respuesta del LoginWS y obtener el "Ticket de Acceso" (TA) Referencias Para mejor entendimiento de la presente especificación, se recomienda estar familiarizado con los siguientes estándares: PKI, XML, SOAP, WSDL, CMS, NTP, Página 6 de 13

7 Invocación del LoginWs Sincronización de Clocks: La fecha y hora del computador deberá estar sincronizada a través del protocolo NTP. WSDL del LoginWs: A continuación, se expone el WSDL perteneciente al LoginWS. El mismo estará disponible en una URL de la. Homologación: Producción: Flujo Principal: A continuación se describen los pasos que se deberán seguir para solicitar un TA al LoginWS. Cada uno de los puntos es explicado detalladamente en los apartados siguientes. 1. Generar el mensaje del TRA (LoginTicketRequest.xml) 2. Generar un CMS que contenga el TRA, su firma electrónica y el certificado X.509 (LoginTicketRequest.xml.cms) 3. Codificar en Base64 el CMS (LoginTicketRequest.xml.cms.bse64) 4. Invocar LoginWS con el CMS y recibir LoginTicketResponse.xml 5. Extraer y validar la información de autorización (TA). Generación del documento del TRA (LoginTicketRequest.xml): El primer paso para solicitar un TA es preparar el documento del TRA (denominado LoginTicketRequest.xml). Se puede utilizar una estructura XML ya definida que puede ser obtenida de un archivo externo o declarada como constante en el propio código. El esquema (schema, XSD) que describe dicho XML es el siguiente: <?xml version="1.0" encoding="utf8"?> <xsd:schema xmlns:xsd=" <xsd:element name="loginticketrequest" type="loginticketrequest" /> <xsd:complextype name="loginticketrequest"> <xsd:sequence> <xsd:element name="header" type="headertype" minoccurs="1" maxoccurs="1"/> <xsd:element name="service" type="servicetype" minoccurs="1"maxoccurs="1"/> </xsd:sequence> <xsd:attribute name="version" type="xsd:decimal" use="optional"default="1.0" /> </xsd:complextype> <xsd:complextype name="headertype"> <xsd:sequence> <xsd:element name="source" type="xsd:string" minoccurs="0" maxoccurs="1" /> <xsd:element name="destination" type="xsd:string" minoccurs="0" maxoccurs="1"/> <xsd:element name="uniqueid" type="xsd:unsignedint" minoccurs="1" maxoccurs="1"/> <xsd:element name="generationtime" type="xsd:datetime" minoccurs="1" maxoccurs="1"/> <xsd:element name="expirationtime" type="xsd:datetime" minoccurs="1" maxoccurs="1" /> </xsd:sequence> </xsd:complextype> <xsd:simpletype name="servicetype"> <xsd:restriction base="xsd:string"> <xsd:pattern value="[a-z,a-z][a-z,a-z,\-,_,0-9]*"/> Página 7 de 13

8 <xsd:minlength value='3'/> <xsd:maxlength value='32'/> </xsd:restriction> </xsd:simpletype> </xsd:schema> A continuación se detalla la descripción de los atributos. Los mismos deben respetar el formato definido en el XSD: source: Campo opcional. Indica el DN del certificado que será utilizado por LoginWS para verificar la firma electrónica del TRA generado por el computador (CEE) que realiza el requerimiento. Si no se incluye, se utilizará el primer certificado de firma incluido en el CMS. Si se incluye, deberá corresponder a uno de los certificados de firma incluidos en el CMS. destination: Campo opcional. Indica el DN del LoginWS, En caso de utilizarse, deberá ser C=ar,O=GCBA,CN=,serialNumber=CUIT " tanto para el ambiente de homologación como de producción. uniqueid: Entero de 32 bits sin signo que junto con generationtime identifica el requerimiento. generationtime: Momento en que fue generado el requerimiento. La tolerancia de aceptación será de hasta 24 horas previas al requerimiento de acceso. expirationtime: Momento en el que expira la solicitud. La tolerancia de aceptación será de hasta 12 horas posteriores al requerimiento de acceso. service: Identificación del WSN para el cual se solicita el TA. Consulte en la documentación el nombre del servicio correspondiente. El siguiente es un ejemplo del documento LoginTicketRequest.xml generado por la empresa SA cuya CUIT es y el DN del CEE es cn=srv1,o=empresa s.a.,c=ar,serialnumber =CUIT CUIT CUIT solicitando acceso al WSN wsfe: <?xml version="1.0" encoding="utf8"?> <loginticketrequest version="1.0"> <header> <source>cn=srv1,o=empresa s.a.,c=ar,serialnumber=cuit CUIT CUIT </source> <destination>c=ar,o=gcba,cn=,serialnumber=cuit </destination> <uniqueid> </uniqueid> <generationtime> t12: 00:0003: 00</generationTime> <expirationtime> t12: 10:0003: 00</expirationTime> </header> <service>nombre_servicio</service> </loginticketrequest> Página 8 de 13

9 Generación del Ticket de Requerimiento de Acceso (TRA) Se deberá generar un mensaje CMS del tipo SignedData que contenga el mensaje anteriormente generado (LoginTicketRequest.xml) y su firma electrónica utilizando SHA1+RSA. De esta forma, se obtiene el TRA (LoginTicketRequest.xml.cms). Codificación en Base64 el TRA: Para poder enviar el TRA al LoginWS, el mismo deberá ser codificado en Base64 (LoginTicketRequest.xml.cms.bse64) Envió del TRA al LoginWS: Se debe invocar al método getloginticketfromcms del LoginWS. El mismo recibe como parámetro una cadena correspondiente a la codificación en Base64 del TRA (LoginTicketRequest.xml.cms.base64) y devuelve una cadena denominada LoginTicketResponse.xml. De esta última se deberá extraer el Ticket de Acceso (TA). Página 9 de 13

10 Mensajes de Error: En caso de encontrarse algún error, el mensaje SOAP devolverá un SoapFault conteniendo el código y descripción del error producido. La descripción podrá contener adicionalmente detalles más específicos del error (ej: el XML expiró hace 10 minutos). La siguiente tabla lista los códigos de errores y su correspondiente descripción. En caso de que la considere necesario, nuevos códigos de errores y su descripción serán agregados. Código Descripción 50 No fue valido el CMS 51 No se pudo obtener la firma del CMS 52 No se pudo obtener el certificado del CMS 53 La firma del CMS no es válida. 54 El certificado no fue firmado por la. 55 El CMS no posee firma. 56 No se encontró la firma que se corresponde con el source indicado. 57 El CMS no posee certificado para la firma. 58 No se encontró el certificado que se corresponde con el source indicado. 59 Formato inválido del XML logintokenrequest. 60 No se admite un GenerationTime futuro. 61 No se admite un GenerationTime mas antiguo de 24hs. 62 No se admite un ExpirationTime ya expirado. 63 No se admite un ExpirationTime de mas de 24hs. 64 Certificado no encontrado en 65 Serialnumber del certificado inválido. 66 Certificado distinto al firmado por 67 No se encontró el servicio o no se tiene acceso al mismo con el alias. 68 Servicio indicado no es un servicio web 69 Servicio deshabilitado 70 El contribuyente debe inscribirse en DFE 71 uniqueid duplicado. 72 Debe especificar un header. Página 10 de 13

11 73 Debe especificar un GenerationTime. 74 Debe especificar un ExpirationTime. 75 La firma de la no pudo ser verificada. 76 No pudo ser leido el CMS Error interno del sistema Extracción y validación del TA LoginTicketResponse.xml es descripto en el siguiente esquema (schema, XSD): <?xml version="1.0" encoding="utf8"?> <xsd:schema xmlns:xsd=" <xsd:element name="loginticketresponse" type="loginticketresponse" /> <xsd:complextype name="loginticketresponse"> <xsd:sequence> <xsd:element name="header" type="headertype" minoccurs="1" maxoccurs="1" /> <xsd:element name="credentials" type="credentialstype" minoccurs="1" maxoccurs="1" /> </xsd:sequence> <xsd:attribute name="version" type="xsd:decimal" use="optional" default="1.0" /> </xsd:complextype> <xsd:complextype name="headertype"> <xsd:sequence> <xsd:element name="source" type="xsd:string" minoccurs="1" maxoccurs="1" /> <xsd:element name="destination" type="xsd:string" minoccurs="1" maxoccurs="1" /> <xsd:element name="uniqueid" type="xsd:unsignedint" minoccurs="1" maxoccurs="1" /> <xsd:element name="generationtime" type="xsd:datetime" minoccurs="1" maxoccurs="1" /> <xsd:element name="expirationtime" type="xsd:datetime" minoccurs="1" maxoccurs="1" /> </xsd:sequence> </xsd:complextype> <xsd:complextype name="credentialstype"> <xsd:sequence> <xsd:element name="token" type="xsd:string" minoccurs="1" maxoccurs="1" /> <xsd:element name="sign" type="xsd:string" minoccurs="1" maxoccurs="1" /> </xsd:sequence> </xsd:complextype> </xsd:schema> Los datos incluidos son los siguientes: source: DN correspondiente al LoginWS que generó el documento (producción / homologación) destination: DN correspondiente del CEE autenticado por el LoginWS uniqueid: Entero de 32 bits sin signo que junto a generationtime identifica al requerimiento. generationtime: Momento en que fue generado el TA. expirationtime: Momento en el que expira el TA. token y sign: cadenas de caracteres que deben ser informadas al WSN (como variables TOKEN y SIGN). Las mismas componen el TA. El formato interno de estas cadenas puede diferir de un servicio a otro y su información contenida es interpretada por el WSN. Página 11 de 13

12 Se deberá verificar que el mensaje de respuesta, que incluye al TA, no se encuentre expirado mediante la variable expirationtime y su momento de generación sea válido mediante la variable generationtime. Un ejemplo de respuesta al requerimiento expuesto anteriormente es el siguiente: <?xml version="1.0" encoding="utf8"?> <loginticketresponse version="1.0"> <header> <source> </source> <destination>cn=srv1, C=ar,O=GCBA,CN=,serialNumber=CUIT CUIT CUIT </destination> <uniqueid> </uniqueid> <generationtime> t12: 00:0203: 00</generationTime> <expirationtime> t00: 00:0203: 00</expirationTime> </header> <credentials> <token>ces0ssuwiiplfe5/dltb0qeg2jquvyuusedorz+w2enaqiees86gzyf7ehiu3uayit5frb9z/3zq</token> <sign>a6qsszbglf0ttcktsnteesg3qxsmvjo/f5py/gtw7xuctruwbsrvcdioge8cm1bixpuvplr58k6n</sign> </credentials> </loginticketresponse> Notar que el tiempo de vida del TA presente en este ejemplo es de 12 horas. El CEE podría utilizar este TA sin necesidad de solicitar otro, indistintamente de la cantidad de veces que consuma el servicio al cual solicito acceso. Para el acceso a un WSN para el cual un CEE posea un TA valido, se recomienda utilizar dicho TA y no solicitar uno nuevo. Requerimientos de los certificados pertenecientes a los COE: La autenticación de los CEE, se realizara mediante certificados X.509v3. Los mismos deberán cumplir con los siguientes requerimientos: 1. Ser emitido por una autoridad certificante reconocida por. 2. El DN deberá enmarcarse dentro de la RFC 2253 ( 3. El contenido del DN se debe cumplir los siguientes requisitos establecidos por la Oficina Nacional de Tecnologías de Información (ONTI), disponible en: de_certificados_y_crls_v1.pdf 4. Los campos obligatorios son los siguientes: Campo 'commonname': DEBE corresponder al nombre del servicio o aplicación (ej. Sistema de Consulta) o al nombre de la unidad operativa responsable del servicio (ej. Gerencia de Compras). Campo 'serialnumber' (OID : Nro de serie): DEBE contener el número de identificación de la Persona Jurídica Pública o Privada, expresado como texto y respetando el siguiente Página 12 de 13

13 formato y codificación: "CUIT numero_de_cuit" CUIT numero_de_cuit" CUIT numero_de_cuit" (el primer CUIT corresponde al representado, el segundo al representante y el tercero al administrado) Campo 'organizationname': DEBE coincidir con el nombre de la Persona Jurídica Pública o Privada. Campo 'countryname': DEBE representar el país en el cual está constituida la Persona Jurídica, codificado según el estándar [ISO3166]. Página 13 de 13