IdP de referencia

1 Introducción

Esta guía ofrece los pasos a seguir para realizar una instalación desde cero de SimpleSAMLphp con el objetivo de disponer de un Proveedor de Identidad con el que conectarse a la federación SIR2 ofrecida por el Servicio de Identidad de RedIRIS. Para ello se ha creado un módulo para SimpleSAMLphp que a través de unos sencillos pasos prepara y pre-configura dicho software.

La integración con distintas fuentes de datos en la organización (directorios LDAP, bases de datos relacionales, o sistemas de single-sign-on como CAS o ADFS) queda del lado de la organización, sin embargo en la sección "recetas de integración" de esta guía, se irán poniendo ejemplos que pueden ser usados por las organizaciones realizando un despliegue.

Este documento no cubre los aspectos de una actualización de un despliegue ya realizado de SimpleSAMLphp, para lo cual recomendamos la lectura de la documentación oficial del software al respecto. Resumiendo el proceso de actualización, ésta pasaría por realizar una copia de seguridad de la versión previa de producción, la instalación de la nueva versión, y la sustitución de ficheros de configuración, plantillas y metadatos.

Esta guía ha sido desarrollada sobre la versión 1.13.2 de SimpleSAMLphp. Más adelante se describe cómo descargar e instalar este software ejecutando un sencillo comando.

1.1 Pre-requisitos del IdP de referencia

Para poder ejecutar el módulo que instala y realiza una configuración base de SimpleSAMLphp para conectarse al SIR, será necesario que esté disponible a través de un servidor web, en el ejemplo se utiliza un servidor Apache

Con carácter general, los prerequisitos de SimpleSAMLphp están listados en la siguiente URL:

    https://simplesamlphp.org/docs/stable/simplesamlphp-install#section_3

Resumimos en la siguiente lista los prerequisitos mínimos que deberemos tener en el servidor donde se va a desplegar SimpleSAMLphp:

  • Servidor web con capacidad de ejecutar PHP
  • PHP versión 5.3.0 o superior
  • Módulos PHP: date, dom, hash, libxml, openssl, pcre, SPL, zlib, mcrypt y posix
  • El paquete del sistema de control de versiones git
  • Existen otros módulos opcionales que deberán instalarse en el caso de querer utilizar determinada funcionalidad:
    • Módulo LDAP de PHP, si se quiere utilizar LDAP para la autenticación o la atribución
    • Módulo PDO de PHP, si se quiere utilizar una base de datos para la autenicación o la atribución. Además, será necesario instalar algún driver específico de PDO: mysql, pgsql, etc.
    • Módulo Memcache de PHP, si se va a utilizar Memcache para gestionar las sesiones PHP

IMPORTANTE: se recomienda que la instalación del IdP de referencia sea efectuada por una persona con experiencia en el despliegue de servidores web (Apache como servidor web de referencia) y aplicaciones PHP.

2 Descarga del instalador del IdP de referencia 

Para poder descargar el instalador del IdP de referencia, que incluye la última versión del simpleSAMLphp, por favor sigue los siguientes pasos:

  • Situate en el directorio raiz del servidor Web (el que hayas configurado en el http como DocumentRoot). En nuestro ejemplo, el directorio por defecto del Apache /var/www/html.
  •  Ejecuta el siguiente comando, que te instalará todo lo necesario en el directorio actual:​ 

                curl -sS https://www.rediris.es/sir2/IdP/install/?v0 | sh 

  • Tambien es posible que te interese la alternativa de descargar el instalador (por ejemplo al fichero install.sh) y revisar su código antes de ejecutarlo:

                curl -sS https://www.rediris.es/sir2/IdP/install/?v0-o install.sh

Si, eventualmente, el proceso de descarga se queda colgado o da un timeout, puede que el FW de tu organización esté filtrando el puerto del git (9418), prueba a desbloquearlo y relanza el comando.


3 Modificación de la URL base de simpleSAMLphp

Al ejecutar el instalador, se ha debido de configurar de manera satisfactoria todos los ficheros de configuración del simplesamlphp, de todos modos debemos cerciorarnos, para poder continuar con la instalación, que la  directiva “baseurlpath” ubicada en el fichero de configuración /var/www/html/simplesamlphp/config/config.php se encuentre como sigue:

24  'baseurlpath' => '/',

25  'certdir' => 'cert/',

26  'loggingdir' => 'log/',

27  'datadir' => 'data/', 

En la línea 24: '/', es importante que se dejen las comillas simples puesto que si no es así se producirá un error al ejecutar SimpleSAMLphp. En caso de que la máquina que sirve el contenido se encuentre tras un balanceador, es posible poner en este campo la dirección completa (por ejemplo:'https://sso.rediris.es:443/).

NOTA IMPORTANTE: En este ejemplo se asume que la instalación se ha realizado en el raíz del servidor web, en caso de que se realiza sobre otra localización, en baseurlpath debería ponerse la ruta web, por ejemplo 'baseurlpath' => '/login',.

4 Configuración de Apache

En el siguiente ejemplo se asume que SimpleSAMLphp está instalado en la localización que por defecto espera el software: /var/www/html/simplesamlphp

Del mismo modo se asume que usted ya dispone de un servidor web Apache en su sistema y que está configurado para responder peticiones HTTP seguras.

El único subdirectorio de SimpleSAMLphp al que debe tener acceso el servidor web es el directorio www/. Existen varias opciones para servir SimpleSAMLphp en función de como esté estructurado el servidor web apache3. La configuración aquí utilizada es la recomendada por los desarrolladores de SimpleSAMLphp, donde se sirve dicho software host virtual de Apache. Busque el fichero de configuración de Apache para los “virtual hosts” donde quiera ejecutar SimpleSAMLphp. La configuración del virtual host, deberá ser parecida a la siguiente:                 

<VirtualHost *:443>
        ServerName nombreDelServidor
        DocumentRoot /var/www/html/simplesamlphp/www
       

        # Configuración de servidor seguro

        ...

        # Fin configuración de servidor seguro

        Alias / /var/www/html/simplesamlphp/www/

        <Directory /var/www/html/simplesamlphp/www>
                Options -Indexes +FollowSymLinks
                AllowOverride None
                Order deny,allow
                Allow from all
        </Directory>

        <Location />
                Options FollowSymLinks
                AllowOverride None
                Order deny,allow
                Allow from all
        </Location>
</VirtualHost>

Tras realizar la modificación del fichero de configuración de Apache debe reiniciar el servidor para que los cambios surtan efecto.

Una vez reiniciado el servidor web Apache puede acceder al interfaz web de instalación y configuración de SimpleSAMLphp en una URL con el siguiente formato:

       https://miservidorweb/module.php/idpinstaller/

5 Seguimiento del proceso de instalación 

El instalador de conexión con SIR está compuesto por 8 pasos que deberán seguirse para completar el proceso.

5.1 Paso 1: Preparación del sistema

El primer paso es comprobar si se cumplen todos los requisitos de sistema para proceder con la intalación. 

Si alguno de los requisitos necesarios para proceder con la instalación no se cumpliese, aparecerá en este paso un mensaje de error con una lista de los elementos necesarios para poder continuar, en este caso será necesario proceder a la instalación del elemento requerido en el sistema. 

También podría ser necesaria la modificación de los permisos de algunos ficheros o directorios de los que hará uso la herramienta de instalación, en caso de que no se hayan ajustado los permisos, tal y como se indica en el epígrafe 2.1. Desempaquetado de SimpleSAMLphp. En dicho caso se proporcionará al usuario la información necesaria para continuar con el proceso. 

Si todo esta configurado correctamente, tendremos una pantalla como la que sigue:

Paso1Instalacion.png

5.2 Paso 2: Configuración básica del sistema

Configuración de datos de acceso a la herramienta SimpleSAMLphp y de la organización que gestionará el sistema.

  • Contraseña de la herramienta de administración: esta contraseña es la que se asocia al administrador en la herramienta visual de SimpleSAMLphp.
  • Nombre y apellidos del contacto técnico: datos de la persona técnica responsable del SimpleSAMLphp que se está desplegando. Estos datos serán publicados en los metadatos como Proveedor de Identidad SAML 2.
  • Correo electrónico: correo electrónico de dicho contacto técnico. Este correo se utilizará tanto en los metadatos como para la recepción de errores que SimpleSAMLphp envíe en el caso de que se produzcan.
Paso2Instalacion.jpg

Tras continuar y comprobar que los datos introducidos son los correctos, se hace una comprobación de la zona horaria, si esta es incorrecta, se deberá comprobar la configuración del parámetro timezone en el fichero php.ini y también modificar el timezone en el fichero de configuración de simpleSAMLphp. config.php, tal y como se indica aquí 

5.3 Paso 3: Configuración de fuente de datos

En este paso se configura la fuente de datos que se quiere utilizar para autenticar y realizar la atribución. Los tipos de fuentes de datos que estarán disponibles para ser seleccionados serán LDAP o bien PDO en el caso de querer utilizar una base de datos. 

En caso de no tener establecidos correctamente los permisos los ficheros y directorios, la herramienta proporcionará al usuario la información necesaria para continuar con el proceso. 

5.3.1 Tipo de fuente de datos LDAP

  • Nombre de host del servidor LDAP: FQDN del servidor LDAP en el que se encuentran las cuentas de usuario de la organización. Por ejemplo: ldap.rediris.es
  • TLS: “Sí” en el caso de querer realizar una conexión segura con el servidor LDAP, “No” en caso contrario
  • Referral: activación del uso de referrals en el LDAP. Puede ser necesario desactivarla en el caso de utilizar un Directorio Activo de Microsoft. 
Paso_3-7-SIR2.png

Para terminar de configurar correctamente la conexión con el LDAP, tendremos que hacer algunas otras modificaciones en el fichero simpleSAMLphp/config/authsources.php. Puede encontrar ejemplos de configuración de este fichero en la "Receta para conexión del IdP con fuentes de datos LDAP".

5.3.2 Tipo de fuente de datos PDO

Dentro de las fuentes de datos tipo PDO se incluyen las Bases de Datos y las fuentes SQL (MySQL, Postgresql, Oracle, etc).

  •  DSN de conexión de la base de datos: Éste es el nombre de la fuente que se usará para realizar la conexión. Deberá tener el siguiente formato: ‘<driver>:host=<host>;port=<port>;dbname=<dbname>;unix_socket=<socket>‘

Donde ‘<driver>’ será el conector de la fuente (p.e. ‘mysql’), ‘<host>’ será el nombre que identifique al anfitrión (p.e. ‘localhost’), ‘<port>’ será el número del puerto de conexión, ‘<dbname>’ el nombre de la base de datos a conectar, y ‘<socket>’ la ruta del socket a utilizar (si procede).

  • Nombre de usuario: Nombre del usuario que figura como administrador de la fuente de datos.
  • Contraseña: Contraseña del usuario que figura como administrador de la fuente de datos. Este campo podría estar vacío si la fuente de datos no estuviera protegida por contraseña. 

NOTA: Podemos ver ejemplos de configuración de fuentes PDO en la sección de recetas de esta guía.

5.4 Paso 4: Creación de certificados del IdP y configuración del protocolo SAML 2.0

Este paso permite crear los certificados digitales necesarios para la instalación, o bien la utilización de uno ya creado.

El instalador posee la capacidad de crear automáticamente los certificados del proveedor de identidad. Para ello es necesario introducir como dato el nombre de la organización a la que hará referencia dicho certificado. 

Paso4Instalacion.png

Si desea modificar el script de creación de certificados digitales, puede encontrar dicho script bajo la ruta modules/idp_installer/lib/makeCert.sh de su instalación.

Como segunda opción, si ya se posee un certificado y una clave privada para el proveedor de identidad pueden introducirse manualmente. El certificado y la clave privada deben ser válidos, y coincidir. 

Paso4ImportarCertificado.png

Si no existe el directorio ‘simplesamlphp/cert’ aparecerá un mensaje de error junto con unas indicaciones que le permitirán resolverlo, y otorgarle los permisos necesarios al directorio.

También se realiza en este paso la configuración como Proveedor de Identidad SAML 2.0 y la comprobación de los metadatos para el correcto funcionamiento de SimpleSAMLphp. Adicionalmente se dará la posibilidad de comprobar dichos metadatos siguiendo el enlace proporcionado por la herramienta. 

5.5 Paso 6: Añadiendo metadatos del SIR

Se realiza la comprobación de la correcta incorporación de los metadatos del SIR en el SimpleSAMLphp. 

Paso6-7-SIR2.png

5.6 Paso 7: Fin de la configuración

Este paso muestra un mensaje de confirmación tras la finalización del proceso de instalación, junto con una recomendación referente al cambio de permisos de los ficheros y directorios de SimpleSAMLphp.

Adicionalmente se muestra también el certificado del IdP junto con la ruta en la que se ha guardado. 

Paso7Instalacion.png

6 Configuración de metadatos de la federación

La federación SIR2 utiliza un único conjunto de metadatos SAML para el hub, independientemente de que el IdP esté disponible a través del entorno de pruebas o el de producción.

Si no se ha utilizado el instalador del IdP de referencia, es necesario incorporar los metadatos del hub de la federación en nuestro IdP. Estos metadatos serían los correspondientes a un único proveedor de servicios (el hub de SIR2), con independencia también de que el proveedor de identidad quiera añadir otros proveedores de servicio adicionales.

Para incorporar manualmente los metadatos de la federación, hay que ir a la página de metadatos de la federación, y descargar el conjunto de metadatos XML del hub.

En el caso del IdP de referencia, los metadatos han de ser convertidos al formato de metadatos que acepta el proveedor de identidad, para ello, podemos utilizar la propia herramienta de análisis de metadatos XML de nuestro IdP, que se puede localizar a través de un enlace que encontraremos en la sección «Federación» de nuestro SimpleSAMLphp.

La herramienta tiene este aspecto:

Conversion metadatos federacion.png

El array asociativo resultante, hay que añadirlo al fichero saml20-sp-remote.php que encontraremos en el directorio metadata/ de nuestro IdP.

7 Pautas para la instalación de un servidor web seguro

<sección por completar>

8 Recetas de integración

8.1 Conexión con directorios LDAP

8.2 Conexión con bases de datos relacionales

8.3 Conexión con CAS

8.4 Conexión con ADFS

8.5 Liberación de atributos recomendados por la federación

8.6 Personalización de la interfaz y pantalla de inicio

9 Actualización del IdP de referencia

Al igual que para el proceso de pre-instalación, se ha creado un script de actualización para el software de IdP de referencia. Aunque se ha puesto el empeño en que dicho script respete la configuración previa de un IdP en funcionamiento, siempre es posible que con la actualización se puedan romper algunas cosas. En concreto hay que tener en cuenta lo siguiente:

  • el script actualizador detecta la versión de SimpleSAMLphp en uso, y hace una copia de seguridad completa de la misma sobre un fichero .tar.bz2. Además hace una copia adicional con el nombre simplesamlphp-x.y.z, donde x.y.z es la versión previamente instalada.
  • el script hace una instalación del software más actual, pero partiendo de la misma base de módulos que configura el instalador. Si ha instalado y configurado algún módulo adicional, este no será instalado, pero siempre será posible recuperar la versión configurada en el IdP anterior.
  • el script copia de la versión anterior los directorios config/, metadata/, cert/, y www/resources/. Si ha realizado cambios en la interfaz o en el tema distribuido (sir2skin), debe de tener en cuenta de que serán sobreescritos, excepto por lo que pudiera existir en el directorio www/resources general de la instalación.

Tenga en cuenta que siempre es conveniente tener un entorno de pre-producción, y otro de producción. Es conveniente probar una actualización primero sobre un entorno de pre-producción que se asemeje en todo lo posible al entorno de producción.

La forma de descargar y ejecutar el script de actualización sería según el siguiente guión de comandos, asumiendo que se encuentra un nivel por encima del directorio sobre el que está instalado, simplesamlphp/ (por ejemplo, nos encontramos en /var/www):

$ curl -sS https://www.rediris.es/sir2/IdP/upgrade/ -o upgrade.sh

$ chmod 755 upgrade.sh

$ ./upgrade.sh