Servicio de Informática y Comunicaciones - Universidad de SevillaUniversidad de SevillaSIC

HTML5

CSS3

SSO: API SAML PHP

Integración con SSO

Integración mediante SAML 2 usando simpleSAMLphp

La integración de una aplicación PHP en el SSO usando el protocolo SAML 2 se puede realizar mediante el software simpleSAMLphp.

simpleSAMLphp es un software publicado con licencia libre muy usado en el mundo de las federaciones de identidad basadas en SAML 2.

Al contrario que otras bibliotecas de integración, simpleSAMLphp requiere de una instalación básica para conseguir poner en marcha lo que se conoce como un SP (Service Provider).

Instalación

simpleSAMLphp tiene los siguientes requisitos:

  • PHP 5.2.0 o superior
  • Extensiones de PHP: date, dom, hash, libxml, openssl, pcre, SPL, zlib, mcrypt

Tras haberse asegurado de tenerlas todas, deberá descargar la última versión del software y descomprimirla en un directorio que no sea directamente accesible desde el servidor web. Por ejemplo:

# cd /var
# tar xzf simplesamlphp-1.xxxxx.tar.gz
# mv simplesamlphp-1.xxxxx simplesamlphp

Lo siguiente será indicarle al servidor web que debe servir cierto subdirectorio de simpleSAMLphp en una determina ruta. Por ejemplo, en Apache lo podría hacer añadiendo la siguiente definición a la configuración de un VirtualHost servido mediante SSL:

<VirtualHost *:443>
    # ...
    Alias /simplesaml /var/simplesamlphp/www
    # ...
</VirtualHost>

Nota: Si quiere usar otra ruta distinta de /simplesaml, deberá actualizar también el parámetro baseurlpath del fichero config.php de simpleSAMLphp.

Proceda entonces a editar el fichero config/config.php de simpleSAMLphp y modifique los siguientes parámetros como se indica:

$ tr -c -d '0123456789abcdefghijklmnopqrstuvwxyz' </dev/urandom | \
dd bs=32 count=1 2>/dev/null;echo
  • admin.adminpassword: contraseña de administración, en claro. Será necesaria más adelante.
  • admin.protectindexpage: proteger la página principal, se recomienda ponerla a true.
  • secretsalt: es una cadena que servirá para la generación de elementos aleatorios. Se puede poner cualquiera, aunque se aconseja generarla de manera aleatoria con una orden como la siguiente:
  • technicalcontact_name y technicalcontact_email: datos de contacto técnico.
  • timezone: Europe/Madrid
  • logging.handler: se puede poner file para que simpleSAMLphp genere ficheros de log en el subdirectorio log/. Hay que dar los permisos correctos al directorio.
  • language.default: lenguaje por defecto.

Tras la configuración básica, puede probar a dirigirse a https://su.host/simplesaml/. Si los pasos anteriores se han seguido correctamente, una página le solicitará su contraseña de administración (admin.adminpassword). Revise la pestaña Configuración para confirmar que todas las dependencias necesarias están cubiertas:

Dependencias

Configuración del SP

simpleSAMLphp está funcionando, pero no sabe cuál es su función. Le indicaremos que es un SP editando el fichero config/authsources.php y definiendo los siguientes parámetros para la entrada default-sp:

<?php
// ...
'default-sp' => array(
    'saml:SP',
    'certificate' => 'mi_aplicacion.pem',
    'privatekey' => 'mi_aplicacion.key',
    'entityID' => 'https://su.host/simplesaml/',
    'idp' => 'https://ssopre.us.es',
    'discoURL' => NULL,
    'redirect.sign' => TRUE,
),

Con esta configuración, simpleSAMLphp sabe que:

  • Es un SP
  • Tiene que usar internamente los certificados mi_aplicacion.pem y mi_aplicacion.key
  • Su identificador interno es https://su.host/simplesaml/. En SAML es muy común usar como identificador de un SP/IdP una URL que identifique al servicio.
  • El proveedor de identidad que debe usar es ssopre.us.es
  • Las peticiones van firmadas digitalmente

Certificados

El par de claves que usaremos como certificado puede ser autogenerado, no es necesario que esté emitido por ninguna CA de confianza, ni que sea el mismo certificado usado por el servidor web de la aplicación.

Generarlo es bastante sencillo:

# cd cert/
# openssl req -newkey rsa:2048 -new -x509 -days 3652 -nodes \
    -out mi_aplicacion.pem -keyout mi_aplicacion.key
Generating a 2048 bit RSA private key
.........+++
..........+++
writing new private key to 'mi_aplicacion.pem'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [XX]:ES
State or Province Name (full name) []:Sevilla
Locality Name (eg, city) [Default City]:Sevilla
Organization Name (eg, company) [Default Company Ltd]:Universidad de Sevilla
Organizational Unit Name (eg, section) []:Mi grupo
Common Name (eg, your name or your server's hostname) []:su.host
Email Address []:sucorreo@us.es

Metadatos del SSO (IdP)

Los certificados están listos, pero el SP aún no sabe quién es ssopre.us.es. Para que lo sepa hay que proporcionarle los metadatos del SSO como IdP SAML 2.0. Puede descargarlos ya preparados para simpleSAMLphp de la sección Servicio.

Copie el contenido de los metadatos (producción o preproducción) en el fichero metadata/saml20-idp-remote.php. Si lo desea, puede dejar en el fichero únicamente la definición del SSO de la Universidad de Sevilla, y borrar todo lo demás.

Solicitud de alta

El siguiente paso consistirá en solicitar el acceso al SSO mediante el formulario de solicitud que se encuentra en el Sistema de Gestión de Solicitudes del SIC https://sos.us.es. Rellene los datos que se le solicitan, y cuando llegue a la sección Protocolo de integración escoja SAML.

Seguidamente aparecerá un recuadro que encontrará debajo, donde se debe indicar los metadatos de su SP. Para obtenerlos, acceda a https://su.host/simplesaml, haga click en la pestaña Federación y busque el siguiente enlace:

Metadatos del SP

De entre los formatos que simpleSAMLphp le muestra, debe proporcionarnos los metadatos en formato XML.

Comprobación del correcto funcionamiento del SP

Cuando tenga el acceso concedido, y antes de proceder a la integración, puede comprobar que todo es correcto accediendo a la pestaña Autenticación de simpleSAMLphp, Probar las fuentes para la autentificación ya configuradas y default-sp. Si todo es correcto, debe ser redirigido al SSO, y una vez se autentique volverá a su SP, que le indicará los atributos que ha recibido del usuario.

Integración de la aplicación

simpleSAMLphp proporciona una interfaz muy simple para que cualquier aplicación en PHP haga uso de su funcionalidad. Puede ver la documentación completa de integración en SP API reference.

Para integrar su aplicación, necesita cargar las bibliotecas de simpleSAMLphp:

<?php
require_once '/var/simplesamlphp/lib/_autoload.php';

$as = new SimpleSAML_Auth_Simple('default-sp');

Para forzar la autenticación y leer los atributos cuando el usuario ya esté autenticado, puede usar el siguiente esquema:

<?php
// Carga de biblioteca

$as->requireAuth();

$attributes = $as->getAttributes();

Hay más métodos disponibles. Puede verlos en SP API reference.