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.

1 Nginx Configuration
- 1.1 Legacy (Rancher 1.6)
- 1.2 Kubernetes (Rancher 2.6+)
  - 1.2.1 Creation of the secret with the CAs
  - 1.2.2 Configuring the Ingress Controller
  - 1.2.3 Configuring the Config Map loadbalancer
2 Keycloak Configuration
- 2.1 Authentication flow
- 2.2 Execution configuration
- 2.3 Truststore
3 Connect front/back to the authentication system

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:

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

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:

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"

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:

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: leave it marked so that it imports users after the first authentication.

User Identity Source: leave it at Match SubjectDN using RegEx, since you 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. 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: mark 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: default role for importing users.

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

The 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.

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

The keycloak’s keystore is located at /opt/jboss/keycloak/standalone/configuration/keystore.jks and 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:

platform-doc-en

Certificate Authentication