Servidor de Autenticación/Autorización (Keycloak)

Descripción del componente

Como el servidor cenral de la auteticacion/autorización el proyecto utiliza el servidor de identidad Keycloak. Keycloak is an opensource OpenID Connect 1.0 Identity Provider Server initially developed as a WildFly Enterprise Java Server subproject and currenly is a separate project supported by Linux Foundation. Althouth for more than ten years Keycloak was based on the WildFly, latest versions are implemented using Quarkus microservices platform. En IMPaCT-Data cada participante mantiene su propia instalacion del proveedor de las identidades compatible con OpenID Connect que funcionan como proveedores externos para el servidor central.

Agregaciones de GA4GH Passport Visas

IMPaCT-Data sugiere el uso de los «visados» de GA4GH Passport para la autorización de acceso a los datos sensibles. Dado que la autorización se otorga por cada participante que es el propietario de sus datos, el servidor central agrega los permisos de lo proveedores externos. Esa informacion no es usable para la autorización sino se puede usar para seleccionar los recursos accesibles para el usuario. Para el acceso al recurso protegido es necesario obtener el token del servidor autorizante. Actualmente Keycloak no soporta la agregacion de los scopes dinamica, por eso hemos desarrollado un plug-in que realiza esa funciolidad - external-idp-scopes-protocol-mapper.

Documentación técnica

Instalación de Keycloak

Aunque los socios de IMPaCT pueden instalar un servidor Keycloak desde el sitio oficial del proyecto o utilizar una instancia de Keycloak ya existente, proporcionamos una plantilla simple de docker compose que facilita la instalación y viene con una configuración de realms ya preconfigurada.

>git clone https://gitlab.bsc.es/impact-data/impd-keycloak-docker.git
>cd impd-keycloak-docker

DEBES cambiar la variable KEYCLOAK_ADMIN_PASSWORD en el fichero docker-compose.yaml por una contraseña segura, ya que esta contraseña concede acceso de administrador a toda la instalación de Keycloak!

>docker-compose up -d

Esto debería ejecutar una instancia preconfigurada del servidor Keycloak de IMPaCT-Data en el puerto 8686. Tenga en cuenta que el realm preconfigurado de IMPaCT-Data proporcionado no contiene secretos de cliente (se establecieron por defecto en “1234567890”), por lo que es necesario añadir seguridad a los clientes de IMPaCT-Data regenerando los secretos.

../../../../_images/kc-regenerate-secret.png — *Regenerating “galaxy.impact-data.bsc.es” secret key*

Las claves secretas deben ser regeneradas para todos los clientes de IMPaCT-Data:

galaxy.impact-data.bsc.es
impact-data-rest
impact-data-portal
bsc-impact-nextcloud

Las plantillas de configuración incluyen la configuración del proveedor externo de Life Science AAI, que también necesita un identificador de cliente y un secreto correctos. Estas credenciales son proporcionadas por el servidor LS Login a través del proceso de registro descrito aquí.

¿Cómo Agregar Proveedores Externos?

La idea principal detrás de la seguridad de IMPaCT-Data es que cada socio mantiene su propio servidor de identidad OIDC que se utiliza como un Proveedor de Identidad externo para IMPaCT-Data. La configuración general se describe en la documentación de Keycloak. Sin embargo, se requiere una configuración específica.

El servidor externo debe tener un cliente configurado para que el servidor de IMPaCT-Data se pede autenticar el usuario.

../../../../_images/kc-create-client.png — *Creando un cliente*

Cuando se está creando el cliente, “Client authentication” (habilita la seguridad del cliente) y “Standard Authentication flow” deben ser marcados. Los administradores de IMPaCT-Data proveeran el valor valido para el campo “Valid redirect URIs”. Si todavia no se conoce, se puede poner un asterisco.

Advertencia

Una vez creado el cliente, el nombre del cliente (“client_id”) y el codigo seguro del cliente (“client_secret”) deben ser pasados a los administradores de IMPaCT-Data.

../../../../_images/kc-client-credentials.png — *Credenciales del cliente*

Vamos a crear el proveedor «My Gorgeous Institution».

../../../../_images/kc-add-external-provider.png — *Adding External Identity Provider*

Elige el tipo de proveedor «OpenID Connect v1.0» y completa el formulario con los parámetros obligatorios:

Alias - el nombre corto para el proveedor (por ejemplo, «mgi»)
Client ID - el identificador del cliente IMPaCT-Data en el servidor de identidad de la institución.
Client Secret - el secreto del cliente IMPaCT-Data en el servidor de identidad de la institución.
Authorization URL - el endpoint de autorización de la institución.
Token URL - el token endpoint de la institución.
Si el servidor de identidad de la institución soporta OpenID Connect Discovery, se puede proporcionar el discovery endpoint (url que termina con «/.well-known/openid-configuration») en lugar de las últimas dos URLs.
En la parte «Avanzada» de la configuración, proporciona
Scopes - «offline_access ga4gh_passport_v1»
El scope «offline_access» solicita el token offline para que IMPaCT-Data pueda solicitar tokens «mgi» indefinidamente.
El scope «ga4gh_passport_v1» es necesario por razones de seguridad - no podremos solicitar un token de acceso con scopes no definidos en el refresh token.
Store tokens - «ON»
Stored tokens readable - «ON»

Añadiendo el nuevo Proveedor de Identidad Externa en la página de Inicio de Sesión

Keycloak permite la personalización de las páginas de usuario utilizando plantillas FreeMarker (doc). IMPaCT-Data utiliza un tema de inicio de sesión personalizado ubicado en /impd-keycloak-docker/keycloak/themes/impact-data/login/login.ftl.
Para agregar el nuevo botón de inicio de sesión, simplemente agrega otro caso:

<#case "ls-login">
  <span class="${properties.kcFormSocialAccountNameClass!}">
    <img src="${url.resourcesPath}/img/ls-login.svg" style="width:100px;display:block;margin:0 auto" alt="elixir"/>
  </span>
  <#break>
<#case "mgi">
  <span class="${properties.kcFormSocialAccountNameClass!}">
    MGI
  </span>
  <#break>

External Identity Provider debe ser accesible al IMPaCT Identity Provider y la conexión debe ser segura (https). Lo ultimo implica tener un certificado SSL y un dominio configurado para una dirección IP publica. Normalmente esta conexión se hace a través de una configuración del HTTP proxy (p.ej. nginx o apache).

Configuración del intercambio de tokens

Dado que cada socio de IMPaCT-Data gestiona su propio servidor de Proveedor de Identidad, los recursos protegidos solo reconocerían tokens emitidos por el IDP institucional. Por otro lado, los flujos de trabajo de IMPaCT-Data están provistos del token de IMPaCT-Data, por lo que para acceder a los recursos protegidos, el token de IMPaCT-Data debe ser intercambiado por el token de confianza del proveedor de datos. Para esta función de intercambio de tokens, se debe configurar RFC 8693 para el ámbito de IMPaCT-Data.

Para habilitar el Intercambio de Tokens para el IDP externo, se deben habilitar los permisos:

../../../../_images/kc-enable-token-exchange.png — *Enable Token Exchange permissions*

Luego, elija los permisos «token-exchange». En los detalles de los permisos, agregue «política de intercambio de tokens», marque «Afirmativo» y «Guardar».

../../../../_images/kc-token-exchange-policy.png — *Apply Token Exchange Policy*

Tenga en cuenta que la «política de intercambio de tokens» ya estaba preconfigurada para el cliente «impact-data-rest».

Ahora el token de IMPaCT-Data («subject_token=$KT») puede ser intercambiado por el externo («requested_issuer=mgi»):

curl -X POST -d "client_id=impact-data-rest" -d "requested_issuer=mgi" \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \ 
--data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
-d "subject_token=$KT" \
https://inb.bsc.es/auth/realms/impact-data/protocol/openid-connect/token

Agregación de Visas GA4GH

Antes de intentar acceder a los datos protegidos, es razonable saber qué datos son accesibles para el usuario. La distribución de Keycloak de IMPaCT-Data se ha ampliado con un mapeador de scope personalizado que consulta dinámicamente a proveedores externos para obtener scopes. La instalación ya incluye el scope «ga4gh_passport_v1» sin configurar para agregar Visas GA4GH de proveedores externos. Necesitamos mapear los scopes «ga4gh_passport_v1» de nuestros proveedores externos en el token de IMPaCT-Data:

../../../../_images/kc-configure-mapper.png — *Keycloak mapper configuration*

Elija External IDP Claim Mapper

../../../../_images/kc-external-mapper.png — *Keycloak external mapper*

Name - cualquier nombre razonable (por ejemplo, «mgi ga4gh_passport_v1 mapper»)
External IDP - Alias del IDP externo
External claim name - ga4gh_passport_v1 (nombre de la reclamación de Pasaporte GA4GH)
Token claim name - ga4gh_passport_v1 (nombre de la reclamación de Pasaporte GA4GH)

Autenticación con el servidor de identidad IMPaCT-Data

Debido a que el servidor de identidad IMPaCT-Data es un proveedor de identidad estándar OpenID Connect 1.0, se pueden utilizar cualquier cliente compatible con él. Se pueden encontrar algunas recetas en la documentación de Keycloak.

En la página referente a la configuración local de clientes para Keycloak aparecen diferentes ejemplos de autenticación con el servidor de identidad de IMPaCT-Data

Contacto

Para cualquier duda durante el periodo de uso y validación de los componentes de la Implementación de Referencia de IMPaCT-Data (Marzo, 2025), podéis poneros en contacto con: