From version 4.1.0-outlaw 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.

Nginx Configuration

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

At the server level, add:

#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;

At the location level, add:

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

Keycloak Configuration

Authentication flow

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

We add an execution, ‘X509 Onesait Platform’:

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

Execution configuration

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

We click on actions → config:

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

We have to configure the following fields:

Import User after first log in: we will leave it marked so that it imports users after the first authentication.

User Identity Source: we will leave it at Match SubjectDN using RegEx, since we will extract the user ID from there.

User ID: a 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: a regular expression to extract the mail. In the case of the DNIe it does not apply. We 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 to 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: we will mark it if we 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: default role for importing users.

User mapping method: we will leave it as either Username or Email.

The rest of the options do not need to be configured.

Truststore

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

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

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

The keycloak’s keystore is located at /opt/jboss/keycloak/standalone/configuration/keystore.jks and the password is the same as the JVM JKS.

Connect front/back to the authentication system

As commented 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 it will be necessary to configure a series of parameters such as:

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

Certificate Authentication