MARCO DE REFERENCIA PARA LA PLATAFORMA DE INTEROPERABILIDAD VOLUMEN IV: MANUAL DEL INTEGRADOR

Interoperabilidad de los servicios telemáticos de la Administración Pública de la CAC Página 1 de 22 MARCO DE REFERENCIA PARA LA PLATAFORMA DE INTEROPERABILIDAD VOLUMEN IV: MANUAL DEL INTEGRADOR SERVICIO DE GENERACIÓN DE PETICIONES Y PROCESAMIENTO DE RESPUESTAS PARA CL@VE v4.0 Documento : PLA-DOC-FIN-v4.0-Vol I. Servicio Cl@ve.pdf Ubicación en eroom: Preparado por Revisado por Aprobado por D. Gral. de Telecomunicaciones y Nuevas Tecnologías D. Gral. de Telecomunicaciones y Nuevas Tecnologías D. Gral. de Telecomunicaciones y Nuevas Tecnologías Fecha: 25/04/2017 Fecha: 25/04/2017 Fecha: 25/04/2017

de 22 ÍNDICE 1 INTRODUCCIÓN...3 1.1 CAMBIOS EN EL DOCUMENTO RESPECTO A LA VERSIÓN ANTERIOR...3 2 VERSIÓN DEL SERVICIO...4 3 FUNCIONAMIENTO...5 3.1 Diagrama de secuencia (entre consumidor, Platino y sistema Cl@ve)...5 3.2 Operaciones del servicio...8 3.2.1 DESCRIPCIÓN DE LAS OPERACIONES DEL SERVICIO...8 3.2.2 EJEMPLOS DE SOLICITUDES Y RESPUESTAS...11 3.3 Logout y autenticación con certificado...16 3.4 Valores para idplist y qaalevel y sus implciaciones en la aplicación web...17 3.4.1 TABLA DE CORRESPONDENCIA ENTRE IDPS Y QAA...17 3.4.2 INTERFAZ DEL SISTEMA CL@VE CON DIFERENTES VALORES PARA IDPLIST Y QAA...17

1 Página 3 de 22 INTRODUCCIÓN El Servicio de Generación de Peticiones y Procesamiento de Respuestas para Cl@ve, dentro del marco de la Plataforma de Interoperabilidad del Gobierno de Canarias, consiste en un servicio horizontal que podrá ser utilizado por las aplicaciones de sus diversos organismos (Consejerías) para facilitar la delegación de la identificación de usuarios en el Sistema Cl@ve del Gobierno de España. La función de este servicio es simplificar la integración con el Sistema Cl@ve del Gobierno de España, ofreciendo operaciones que extraen lógica repetitiva que es necesaria para gestionar la comunicación con el sistema externo. Las operaciones que provee el servicio Cl@ve de Platino facilitan tanto la generación de peticiones como el procesamiento de respuestas del Sistema Cl@ve del Gobierno de España. 1.1 CAMBIOS EN EL DOCUMENTO RESPECTO A LA VERSIÓN ANTERIOR Se ha añadido un nuevo parámetro opcional(forceauthn) al método: generarparametrospeticionclave(urlrespuesta, allowlegalperson, idplist, qaalevel, [application],[forceauthn]) Dicho parámetro sirve para poder mantener la sesión en Cl@ve Gobierno de España. Se ha cambiado el valor del parámetro afirmaresponse devuelto por el método procesarrespuestasamlclave(), con la verdadera respuesta de afirma, codificada de base64.

2 Página 4 de 22 VERSIÓN DEL SERVICIO Este documento corresponde a las versiones del servicio 4.0.X. Para consultar la información completa de cambios del servicio ver Release Notes.

3 Página 5 de 22 Funcionamiento Dado que la autenticación con el Sistema Cl@ve del Gobierno de España consiste en una redirección desde una aplicación web a dicho sistema, especificando una URL de respuesta para la vuelta tras la autenticación; es inevitable que cualquier organismo del Gobierno de Canarias que quiera delegar la autenticación de sus aplicaciones en el Sistema Cl@ve tenga que implementar la comunicación con el mismo. No obstante, desde Platino se ofrece un servicio web SOAP que provee a los organismos del Gobierno de Canarias de dos operaciones que simplifican significativamente la integración con Cl@ve. Las operaciones que se ofrecen son: 1) generación de peticiones para invocar al sistema Cl@ve; y 2) procesamiento de respuestas SAML de Cl@ve y devolución de la información del usuario. Dado que el servicio de Platino solamente provee las operaciones mencionadas anteriormente, para realizar una integración completa con el sistema es necesario que se consulte la documentación oficial para integradores de Cl@ve. En caso de que no haya un manual para integradores en la web oficial de Cl@ve ni en el portal de administración electrónica (PAE), en nuestro repositorio de manuales hemos adjuntado el documento de integracion para SP en su versión 1.1.7. NOTA: En la nomenclatura de Cl@ve, un SP es un Proveedor de servicios de administración electrónica. 3.1 Diagrama de secuencia (entre consumidor, Platino y sistema Cl@ve) En el siguiente diagrama de secuencia se puede apreciar el flujo de comunicación entre la aplicación consumidora (por ejemplo la Sede Electrónica del Gobierno de Canarias), el servicio web Cl@ve de Platino (que a su vez hace uso internamente de la librería SamlEngine proveída por Cl@ve) y el Sistema Cl@ve del Gobierno de España. Como se observa en el diagrama y se ha expresado anteriormente, el servicio ofrecido por Platino simplifica tanto la generación de los parámetros que se han de enviar a Cl@ve (entre ellos el token SAML), como el procesamiento de la respuesta SAML (devuelta por Cl@ve a la aplicación una vez el usuario se ha autenticado o se haya realizado el logout).

de 22 A continuación se indican los nombres de los parámetros que se usan para invocar a Cl@ve así como los parámetros que se deben recoger de la respuesta POST:

de 22 Para la autenticación: POST a la URL de Cl@ve, devuelta al realizar la llamada previa generarparametrospeticionclave(), pasándole los parámetros: allowlegalperson, idplist, SAMLRequest Parámetros devueltos por Cl@ve que debemos recoger del resultado de la petición POST: SAMLResponse, islegalperson, urluser Para el logout: POST a la URL de Cl@ve, devuelta al realizar la llamada previa generarpeticionlogout(), pasándole el parámetro samlrequestlogout. Parámetro devuelto por Cl@ve que debemos recoger del resultado de la petición POST: samlresponselogout

3.2 3.2.1 Página 8 de 22 Operaciones del servicio Descripción de las operaciones del servicio Las operaciones que actualmente se ofrecen desde el Servicio Cl@ve de Platino son: 1. GenerarParametrosPeticionClave : se encarga de devolver todos los parámetros necesarios para invocar al sistema para poder realizar la autenticación. 2. ProcesarRespuestaSAMLClave: se encarga de procesar las respuestas del sistema y devolver la información del usuario. 3. GenerarPeticionLogout: genera la petición necesaria para solicitar el logout del sistema. 4. ProcesarRespuestaLogout: procesa la respuesta del sistema y devuelve la misma al usuario. generarparametrospeticionclave(urlrespuesta, allowlegalperson, idplist, qaalevel, [application],[forceauthn]): ParametrosPeticionClave o Parámetros: urlrespuestaclave: indica la URL (de la aplicación consumidora) a la que se debe volver tras finalizar la autenticación en el Sistema Cl@ve nacional por parte del usuario. Este parámetro es necesario para generar el token y debe ser una URL válida. allowlegalperson: indica si permitiremos personas jurídicas o no a la hora de autenticarse en Cl@ve. Solicitamos este parámetro a pesar de que no se utilizará en nuestra lógica salvo para devolverlo como uno de los campos de la respuesta de Platino (que componen los parámetros de la solicitud que se debe enviar a Cl@ve). Con esto se busca que el consumidor del servicio Cl@ve de Platino no tenga que conocer la interfaz del Sistema Nacional, sino solamente la de Platino. idplist: especifica cuáles son los proveedores de servicios de identificación y autenticación que se desea permitir. Si no se especifica ningún valor, se utiliza el valor por defecto afirma (el más restrictivo)

de 22 Los posibles valores que se pueden utilizar en este campo son afirma, Stork, SS y/o AEAT. Se pueden indicar varios de ellos separados por ; (por ejemplo AEAT;aFirma ) Para ver las implicaciones de los valores del campo idplist en la interfaz, ver la sección 3.4 de este documento. Aunque no es necesario para la generación del token, este parámetro se solicita porque es parte de los que se deben enviar al Sistema Cl@ve. Si no lo incluyéramos aquí no podríamos generar una respuesta completa que contuviera todos los parámetros necesarios para que el integrador pueda preparar la petición al Sistema Cl@ve del Gobierno de España. De esta forma, al incluir este parámetro, además de poder validarlo podremos devolverlo en la respuesta, con lo que el integrador solamente tendrá que preocuparse de utilizar los valores de la respuesta de esta operación al hacer la petición al Sistema Cl@ve. qaalevel: es un entero que especifica el nivel de seguridad que se desea exigir (ver tabla de la página 10 del Documento de Integración del Cl@ve). Si no se especifica ningún valor, se utiliza el valor por defecto 4 (el más restrictivo) Para ver las implicaciones de los valores del campo idplist en la interfaz, ver la sección 3.4 de este documento. application: es una cadena que identifica a la aplicación consumidora (por ejemplo, para fines estadísticos de consumo). Es un parámetro opcional. Si no se especifica, Platino generará una cadena alternativa en base a la información del certificado del consumidor (uriinvoker). Si tampoco es posible obtener información del certificado, entonces se invocará al Sistema Cl@ve del Gobierno de España enviando simplemente el campo application con el valor Platino. forceauthn: parámetro para poder mantener la sesión en Cl@ve Gobierno de España, es opcional, puede tomar los valores true / false, si no se indica se pasará por defecto el valor false, o Respuesta:

de 22 Se genera el token SAML que se ha de enviar en la petición POST al sistema Cl@ve nacional. Se devuelven otros 3 parámetros además del token SAML: allowlegalperson: Parámetro solicitado como entrada que se devuelve como parte de la solicitud que se ha de enviar a Cl@ve. Se ha explicado en la sección parámetros de esta misma operación. idplist: Lista de métodos de identificación y autenticación que permitiremos para nuestros usuarios en Cl@ve. qaalevel: Nivel de seguridad de la petición. o Se devuelve para posibles verificaciones que desee realizar el integrador con la generación del token, pero no es necesario utilizarlo posteriormente para realizar la petición al Sistema Cl@ve del Gobierno de España. urlclave: URL del Sistema Cl@ve del Gobierno de España a la que se debe enviar la petición POST con los parámetros anteriores. procesarrespuestasamlclave(samlresponse, islegalperson, urluser): DatosUsuarioValidado o Parámetros: samlresponse: La respuesta SAML del Servicio de Cl@ve nacional (de la que se extraerán los datos). islegalperson: Un boolean que especifica si el usuario es una persona jurídica. urluser: La URL del usuario (deberá coincidir con la que se especificó como URL de respuesta al generar el token) o Respuesta Se devuelven los datos de usuario presentes en la respuesta SAML (que serán aquellos del usuario que se autenticó en el Sistema Cl@ve del Gobierno de España cuando fue enviado allí por el consumidor). AfirmaResponse: respuesta de afirma codificada en base64 con los datos del certificado del usuario, se se accedió mediante autenticación con certificado.

de 22 3.2.2 Los campos que se devuelven serán: nombre, apellido1, apellido2, nundocumento (NIF) y tipocert (PF / persona física o PJ / persona jurídica) generarpeticionlogout(string urlrespuesta) o Parámetros urlrespuesta: indica la URL (de la aplicación consumidora) a la que se debe volver tras finalizar el logout en el Sistema Cl@ve nacional por parte del usuario. Este parámetro es necesario para generar el token y debe ser una URL válida. o Respuesta El token SAML que se ha de enviar en la petición POST al sistema Cl@ve nacional. urlclave: URL del Sistema Cl@ve del Gobierno de España a la que se debe enviar la petición POST para realizar el logout con el parámetro anterior. procesarrespuestalogout(string samlresponselogout) o Parámetros samlresponselogout: La respuesta SAML devuelta por el Sistema de Cl@ve nacional. o Respuesta RespuestaLogout: Se devuelven los datos presentes en la respuesta SAML devuelto por el Sistema Cl@ve del Gobierno de España. Los campos que se devuelven serán: samlid, destination, distinguishedname, tokensaml, issuer, country, alias, statuscode, substatuscode, statusmessage, fail, inresponseto Ejemplos de Solicitudes y respuestas Ejemplo de llamada a la operación generarparametrospeticionclave del servicio:

de 22 Ejemplo de respuesta de la operación generarparametrospeticionclave del servicio: Ejemplo de llamada a la operación procesarrespuestasamlclave del servicio:

de 22 Ejemplo de respuesta de la operación procesarrespuestasamlclave del servicio: Ejemplo de llamada a la operación generarpeticionlogout del servicio: Ejemplo de respuesta de la operación generarpeticionlogout del servicio:

de 22 Ejemplo de llamada a la operación procesarrespuestalogout del servicio:

de 22 Ejemplo de respuesta de la operación procesarrespuestalogout del servicio: 3.3 Logout y autenticación con certificado El uso de certificados electrónicos como método de autenticación en Cl@ve tiene actualmente un problema en relación al sistema Single-Sign On (SSO). Es importante recalcar que no es un problema del sistema Cl@ve sino de la forma de funcionar del túnel SSL cliente que se establece durante el proceso de identificación por certificado. La única manera de deshacerlo es cerrando todas las instancias abiertas del navegador web. Por ello, en este caso, si se hace logout, la sesión con la pasarela (dominio se-pasarela.clave.gob.es) se cierra pero no el túnel SSL con el dominio del IdP de certificados (se-pasarela-ident.clave.gob.es) por lo que si se vuelve a elegir autenticación por certificado se toma automáticamente el que ya se tenía seleccionado anteriormente. Indicar que el handshake SSL establecido lo administra el navegador web, así como todo lo relacionado con las tareas de selección de certificados, contraseñas de acceso, caché, etc. que dependen de la implementación que tenga el propio navegador. Por tanto Cl@ve no almacena el certificado como sesión, sino que siempre consulta por el que está establecido en el navegador para la sesión SSL.

3.4 Página 17 de 22 Valores para idplist y qaalevel y sus implciaciones en la aplicación web En base a los valores especificados para los parámetros idplist y qaalevel, se mostrarán al usuario final diferentes opciones de autenticación en la aplicación web del Sistema Cl@ve. 3.4.1 Tabla de correspondencia entre idps y qaa 3.4.2 Interfaz del Sistema Cl@ve con diferentes valores para idplist y qaa A continuación se adjuntan capturas del resultado que implican algunas de las configuraciones de estos parámetros.

de 22 Pantalla de autenticación del Sistema Cl@ve, todos los idp habilitados: Pantalla de autenticación del Sistema Cl@ve, @Firma y Stork deshabilitados:

de 22 Autenticación con @Firma: Autenticación con Cl@ve Pin:

de 22 Autenticación con Cl@ve Permanente:

de 22 Autenticación con Stork: