Info

...

From version 4.1.0-outlaw

...

A continuación vamos a detallar como activar la autenticación por certificados en el IM avanzado de plataforma.

Esta funcionalidad permite a los usuarios iniciar sesión en la plataforma y aplicación desarrolladas sobre la misma mediante certificados de cliente X509, con la ventaja de poder seguir utilizando Oauth2 como estándar de seguridad en las comunicaciones.

Table of Contents

Configuración de Nginx

Como el nginx termina la conexión SSL, necesitamos configurar el forwarding del certificado a Keycloak primero.

...

onward, you will be able to activate certificate authentication in our advanced Identity Manager.

Next we will detail how to activate certificate authentication in the advanced platform IM.

This functionality allows users to log in to the platform and applications developed on it using X509 client certificates, with the advantage of being able to continue using Oauth2 as a communications security standard.

Table of Contents

Nginx Configuration

Legacy (Rancher 1.6)

Since nginx terminates the SSL connection, you need to configure the certificate forwarding to Keycloak first.

At the server level, add:

Code Block

#x509
ssl_verify_client optional_no_ca;
#se puede poner a optional y checkear la cadena de confianza con el siguiente parámetro
#CA.pem deberá contener todos los certificados concatenados de los issuers 
#de certificados que vaya a aceptar nuestro sistema
#ssl_client_certificate /etc/nginx/ssl/CA.pem;
ssl_verify_depth 2;

A nivel de location añadirAt the location level, add:

Code Block
location /auth { proxy_set_header X509-Cert $ssl_client_escaped_cert; .... }

Configuración Keycloak

Flujo de autenticación

Lo primero será modificar el flujo principal de autenticación, ‘Multitenant-browser-flow’:

...

Añadimos una execution, ‘X509 Onesait Platform’

...

La marcamos como alternativa en el flujo de autenticación, y la ponemos en el tercer nivel:

...

Configuración de la execution

Ahora tenemos que configurar la execution para el mapeo de certificado - usuario.

Hacemos click en actions → config

...

En este ejemplo vamos a configurarlo para aceptar DNIe como fuente de certificado electrónico.

...

Kubernetes (Rancher 2.6+)

As a requirement to set up an environment with kubernetes, you need to have k8s version 1.21+ for the Ingress Controller to support networking.k8s.io/v1 annotations.

Creation of the secret with the CAs

Firstly, you must create the secret that will contain the concatenated certificates of the CAs needed to validate the client certificates that you want to authenticate.

Create a secret called platform-ca in the onesaitplatform namespace, for example, and about the secret key, call it ca.crt , leaving the certificate chain as the value.

...

Configuring the Ingress Controller

In the Ingress Controller, you must write the following annotations:

Code Block

nginx.ingress.kubernetes.io/auth-tls-pass-certificate-to-upstream: "true"
nginx.ingress.kubernetes.io/auth-tls-secret: onesaitplatform/platform-ca
nginx.ingress.kubernetes.io/auth-tls-verify-client: optional
nginx.ingress.kubernetes.io/auth-tls-verify-depth: "2"

Image Added

Configuring the Config Map loadbalancer

Finally, you must add the following directive to the config map of your balancer, in order to propagate the HTTP header that the Ingress Controller injects with the certificate:

Code Block
proxy_set_header X509-Cert $http_ssl_client_cert;

...

Keycloak Configuration

Authentication flow

The first thing will be to modify the main authentication flow, 'Multitenant-browser-flow':

...

Add an execution, ‘X509 Onesait Platform’:

...

Mark it as an alternative in the authentication flow, and put it in the third level:

...

Execution configuration

Now you have to configure the execution for the certificate - user mapping.

Click on actions → config:

...

In this example, you are going to configure it to accept DNIe as a source of electronic certificate.

You must configure the following fields:

...

Import User after first log in: lo dejaremos marcado para que importe a los usuarios después de la primera autenticaciónleave it marked so that it imports users after the first authentication.

User Identity Source: lo dejaremos a leave it at Match SubjectDN using RegEx, ya que extraeremos de ahí el ID de usuariosince you will extract the user ID from there.

User ID: expresión regular para extraer el ID único de usuario, en el caso del DNIe se extrae del campo SERIALNUMBER del DN del certificadoa regular expression to extract the unique user ID. In the case of the DNIe, it is extracted from the SERIALNUMBER field of the certificate’s DN.

Email: expresión regular para extraer el correo, en el caso del DNIe no aplica, se deja vacío ya que no aparece este campo. Email suffix: sufijo del correo que se usará en caso de que no exista un RegEx para extraer el correo. El correo se compondrá de ID Usuario a regular expression to extract the mail. In the case of the DNIe it does not apply. Leave it empty since this field does not appear.

Email suffix: email suffix that will be used in case there is no RegEx to extract the email. The email will consist of User ID + @ + email suffix.

Full user name: RegEx para extraer el nombre de usuario completo, se pueden usar múltiples RegEx separadas por ‘;;’ como en el ejemplo, ya que en el DNIe el nombre de pila y el apellido vienen separados. El nombre completo será una concatenación de los valores obtenidos por las expresiones regularesto extract the full user name. Multiple RegEx separated by ';;' can be used as in the example, since in the DNIe, the first name and the last name are separated. The full name will be a concatenation of the values obtained by the regular expressions.

Import DN as extrafields: lo marcaremos si queremos almacenar en el campo extra fields de los usuarios de plataforma el DN completo extraído del certificado.Administrators whitelist: lista de ID de usuario separados por comas que se les va a dar rol administradormark it if you want to store the full DN extracted from the certificate in the “extra fields” of the platform users.

Administrators whitelist: comma-separated list of user IDs that will be given the administrator role.

Default import Role: rol por defecto de importación de usuariosdefault role for importing users.

User mapping method: lo dejaremos a will leave it as either Username or Email.

El resto de opciones no hace falta configurarlas.

Truststore

Por último habrá que añadir los certificados de los issuers de los certificados electrónicos que vaya a aceptar nuestro sistema, en el caso del DNIe, tenemos que añadir el de la Policia NacionalThe rest of the options do not need to be configured.

Truststore

Lastly, you will have to add the certificates of the issuers of the electronic certificates that our system will accept. In the case of the DNIe, you have to add that of the Spanish National Police.

Code Block

...

Para añadirlo, solicitarlo a través de soporte de plataforma

To add it, request it through the platform’s support.

Code Block
keytool -importcert -keystore "KEYSTORE_FILE" -storepass "KEYSTORE_PASSWORD" -file "CERTIFICATE_FILE" -alias "CERTIFICATE_ALIAS"

El keystore de keycloak esta ubicado en The keycloak’s keystore is located at /opt/jboss/keycloak/standalone/configuration/keystore.jks , la contraseña es la misma que el JKS de la JVM.

Conectar front/back al sistema de autenticación

Como se comentaba al principio del post, para integrar una aplicación con este sistema de autenticación, se seguirá usando Oauth2, con el flujo de código de autorización, de tal forma que la aplicación redireccionará al IM, este leerá el certificado del cliente si lo tiene configurado, y devolverá a la aplicación original un token JWT.

Existen librerías para configurar este tipo de flujo tanto para Spring Boot como para Vue JS, y habrá que configurar una serie de parámetros del estilo deand the password is the same as the JVM JKS.

The keystore.jks with the most common CAs requested by clients is in the /onesait-cloud-platform/tools/keycloak/server directory. You can always add more and regenerate the keycloak server image.

Connect front/back to the authentication system

As mentioned at the beginning of the post, to integrate an application with this authentication system, Oauth2 will continue to be used, with the authorization code flow, so that the application will redirect to the IM, which will then read the client certificate if it has one configured, and will return a JWT token to the original application.

There are libraries to configure this type of flow for both Spring Boot and Vue JS, and you will need to configure a series of parameters such as:

Code Block

oauth2.client.clientId = onesaitplatform
oauth2.client.clientSecret = onesaitplatform
oauth2.client.accessTokenUri = https://${SERVER_NAME}/auth/realms/onesaitplatform/protocol/openid-connect/token
oauth2.client.userAuthorizationUri = https://${SERVER_NAME}/auth/realms/onesaitplatform/protocol/openid-connect/auth?scope=openid
oauth2.client.checkTokenEndpointUrl = https://${SERVER_NAME}/auth/realms/onesaitplatform/protocol/openid-connect/token/introspect
oauth2.client.logoutUrl=https://${SERVER_NAME}/auth/realms/onesaitplatform/protocol/openid-connect/logout?redirect_uri=https://${SERVER_NAME}/controlpanel/login
oauth2.resource.userInfoUri = https://${SERVER_NAME}/auth/realms/onesaitplatform/protocol/openid-connect/userinfo
oauth2.client.useCurrentUri: false
oauth2.client.preEstablishedRedirectUri: https://${SERVER_NAME}/controlpanel/login

...

Versions Compared

Old Version 1

New Version Current

Key

Configuración de Nginx

Nginx Configuration

Legacy (Rancher 1.6)

Configuración Keycloak

Flujo de autenticación

Configuración de la execution

Kubernetes (Rancher 2.6+)

Creation of the secret with the CAs

Configuring the Ingress Controller

Configuring the Config Map loadbalancer

Keycloak Configuration

Authentication flow

Execution configuration

Truststore

Truststore

Conectar front/back al sistema de autenticación

Connect front/back to the authentication system

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Configuración de Nginx

Nginx Configuration

Legacy (Rancher 1.6)

Configuración Keycloak

Flujo de autenticación

Configuración de la execution

Kubernetes (Rancher 2.6+)

Creation of the secret with the CAs

Configuring the Ingress Controller

Configuring the Config Map loadbalancer

Keycloak Configuration

Authentication flow

Execution configuration

Truststore

Truststore

Conectar front/back al sistema de autenticación

Connect front/back to the authentication system