Come connettere Keycloak e Liferay via OpenID Connect

In questi ultimi anni si sta affermando sempre di più il protocollo di autenticazione OpenID Connect (OIDC), basato su OAuth2, per offrire l'accesso in modo sicuro a applicazioni e API (Application Programming Interface).

In questo articolo vedremo come intraprendere una corretta configurazione di Keycloak e Liferay al fine di abilitare il processo di autenticazione degli utenti sfruttando il protocollo OpenID Connect. Desidero sottolineare il fatto che l'articolo non è una guida all'installazione di Liferay e Keycloak.

Per la comprensione di quanto descritto nel corso dell'articolo è richiesta una buona conoscenza degli aspetti amministrativi sia di Liferay sia di Keycloak, oltre a una conoscenza di base dei sistemi di SSO (Single Sign-On).

Come di consueto lascerò il bonus di fine articolo, ovvero, il riferimento GitHub del progetto che consentirà a voi di ricreare lo scenario che andremo a descrivere.

1 - Requisiti

Le versioni di riferimento di Liferay e Keycloak che prenderemo in considerazione sono rispettivamente la 7.3 GA6 e 15.0.2 (rilasciata il 20 agosto 2021).

Affinché sia possibile portare a termine con successo la configurazione dell'integrazione tra Keycloak e Liferay, occorre che siano disponibili un'istanza di Liferay e un'istanza di Keycloak.

Per le attività di configurazione di Liferay e Keycloak è necessario disporre delle credenziali di accesso e che queste abbiano un ruolo di amministratore per entrambe i sistemi.

Il diagramma della figura a seguire mostra ad alto livello lo scenario d'integrazione che andremo a realizzare e quali sono i protocolli utilizzati. Il componente LDAP è stato inserito ma è del tutto opzionale, lo troverete però all'interno del bonus.

Gli FQDN (Fully Qualified Domain Name) riportati sui componenti dello scenario d'integrazione sono a titolo esemplificativo.

È importante ricordare che affinché la configurazione vada a buon fine è indispensabile che i sistemi coinvolti possano comunicare tra loro attraverso i protocolli richiesti (https e ldaps), inoltre, in ambienti SSL/TLS devono essere correttamente impostati i TrustStore. Tale precisazione serve a evitare di incorrere in fastidiosi errori (es. validazione della catena di certificazione X509).

2 - Configurazione di Keycloak

La prima attività da compiere è quella di configurazione dell’istanza di Keycloak. Quest’operazione richiede diversi step che sono indicati a seguire.

1. Creazione di un Realm specifico
2. Creazione di un client OpenID Connect
3. Creazione di un Identity Provider (o IdP) OpenID Connect
4. Creazione utente demo (opzionale nel caso abbiate configurato un servizio LDAP)

Assumiamo quindi che l’istanza Keycloak sia operativa e accediamo al pannello di amministrazione utilizzando le credenziali di amministrazione. Per questo scenario ipotizziamo che l’istanza di Keycloak sia disponibile all’indirizzo https://iam.smc.lab.local/ (vedi figura a seguire).

Per ogni dubbio e/o approfondimento riguardo l'installazione e configurazione di Keycloak, fare riferimento alla documentazione ufficiale disponibile all’indirizzo https://www.keycloak.org/archive/documentation-15.0.html

2.1 - Creazione del Realm

Un Realm in Keycloak è l'equivalente di un tenant (gruppo di utenti che condividono un accesso comune a un sistema software multi-tenant). Consente di creare gruppi isolati di applicazioni e utenti. Per impostazione predefinita c'è un singolo realm in Keycloak chiamato master, questo è dedicato alla gestione di Keycloak e non dovrebbe essere utilizzato per il resto delle applicazioni.

Il primo step richiede la creazione di un nuovo Realm che potremmo per esempio chiamare smc-lab-local-relam.

La figura precedente evidenzia l’endpoint della configurazione di OpenID Connect. Questo endpoint contiene tutti i metadati di configurazione che riguardano il protocollo, come per esempio: Token URL, Authorization URL, Issuer, etc. Queste informazioni saranno utili per le attività di configurazione successive, sia su Keycloak sia su Liferay.

La URL di configurazione è in questo caso: https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/.well-known/openid-configuration.

Nota: Questa è la URL che utilizzerà Liferay per ottenere i metadati di configurazione, per questo motivo è importante che questo indirizzo sia raggiungibile e che la configurazione dei certificati SSL/TLS sia corretta.

Puntando il proprio browser verso l'indirizzo dei metadati di configurazione, si otterrà un documento JSON come quello mostrato a seguire.

{
	"issuer": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm",
	"authorization_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth",
	"token_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token",
	"introspection_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/token/introspect",
	"userinfo_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/userinfo",
	"end_session_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/logout",
	"jwks_uri": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/certs",
	"check_session_iframe": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/login-status-iframe.html",
	"grant_types_supported": ["authorization_code", "implicit", "refresh_token", "password", "client_credentials", "urn:ietf:params:oauth:grant-type:device_code", "urn:openid:params:grant-type:ciba"],
	"response_types_supported": ["code", "none", "id_token", "token", "id_token token", "code id_token", "code token", "code id_token token"],
	"subject_types_supported": ["public", "pairwise"],
	"id_token_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"id_token_encryption_alg_values_supported": ["RSA-OAEP", "RSA-OAEP-256", "RSA1_5"],
	"id_token_encryption_enc_values_supported": ["A256GCM", "A192GCM", "A128GCM", "A128CBC-HS256", "A192CBC-HS384", "A256CBC-HS512"],
	"userinfo_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512", "none"],
	"request_object_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512", "none"],
	"response_modes_supported": ["query", "fragment", "form_post"],
	"registration_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/clients-registrations/openid-connect",
	"token_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"token_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"introspection_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"introspection_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"claims_supported": ["aud", "sub", "iss", "auth_time", "name", "given_name", "family_name", "preferred_username", "email", "acr"],
	"claim_types_supported": ["normal"],
	"claims_parameter_supported": true,
	"scopes_supported": ["openid", "offline_access", "web-origins", "phone", "roles", "email", "address", "profile", "microprofile-jwt"],
	"request_parameter_supported": true,
	"request_uri_parameter_supported": true,
	"require_request_uri_registration": true,
	"code_challenge_methods_supported": ["plain", "S256"],
	"tls_client_certificate_bound_access_tokens": true,
	"revocation_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/revoke",
	"revocation_endpoint_auth_methods_supported": ["private_key_jwt", "client_secret_basic", "client_secret_post", "tls_client_auth", "client_secret_jwt"],
	"revocation_endpoint_auth_signing_alg_values_supported": ["PS384", "ES384", "RS384", "HS256", "HS512", "ES256", "RS256", "HS384", "ES512", "PS256", "PS512", "RS512"],
	"backchannel_logout_supported": true,
	"backchannel_logout_session_supported": true,
	"device_authorization_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/auth/device",
	"backchannel_token_delivery_modes_supported": ["poll"],
	"backchannel_authentication_endpoint": "https://iam.smc.lab.local/auth/realms/smc-lab-local-realm/protocol/openid-connect/ext/ciba/auth"
}

Ricorda che: i metadati di configurazione sono importanti per la successiva configurazione del componente OpenID Connect di Liferay. Tieni quindi da parte questi dati.

2.2 - Creazione del client OpenID Connect

Il secondo step richiede la creazione di un nuovo client OpenID Connect. I dati essenziali per poter creare il client sono indicati a seguire.

1. Client ID: identificativo univoco del client.
2. Name: descrizione del client.
3. Access Type: tipo di accesso che in questo caso deve essere impostato a confidentials.
4. Valid Redirect URIs: lista delle URI di redirect che devono essere considerate valide da Keycloak.

Per avviare la creazione del nuovo client, dalla sezione Configure del Realm, selezionare la voce Clients e successivamente cliccare sul pulsante Create. Le figure a seguire mostrano le maschere di creazione del nuovo client.

I parametri e valori indicati nella tabella a seguire sono quelli che devono essere impostati sulla maschera di modifica della configurazione del client (vedi la figura a seguire). Una buona regola è quella di assegnare un valore “parlante” o auto esplicativo al parametro Client ID.

Dopo aver salvato la configurazione del client occorre spostarsi sul tab Credentials cliccando successivamente sul pulsante Regenerate Secret, prendendo nota del Secret appena generato, questo valore sarà utile nella successiva configurazione dell’Identity Provider.

Adesso tra la lista dei client registrati su Keycloak è disponibile quello appena creato per l’integrazione con il portale Liferay (vedi figura a seguire).

2.3 - Configurazione Identity Provider

Il terzo step richiede la configurazione dell’Identity Provider OpenID Connect. I dati essenziali per poter creare il client sono indicati a seguire.

1. Alias univoco da assegnare all’Identity Provider
2. Authorization URL
3. Token URL
4. Logout URL
5. Client Authentication
6. Client ID
7. Secret

I valori che riguardano Authorization, Token e Logout URL, possono essere estratti dall’OpenID Connect Endpoint (metadati di configurazione) mostrato in precedenza.

I valori che riguardano Client ID e Secret sono quelli impostati in precedenza durante la creazione del client.

Per avviare la creazione dell’Identity Provider, dalla sezione Configure del Realm selezionare la voce Identity Providers e successivamente selezionare dalla lista l'elemento Keycloak OpenID Connect. Le figure a seguire mostrano le maschere di creazione del nuovo client.

La tabella a seguire mostra i parametri e rispettivi valori che devono essere impostati sulla maschera di creazione del nuovo Identity Provider.

Le due figure a seguire mostrano le configurazioni che sono state applicate al nuovo Identity Provider OpenID Connect con i valori indicati dalla precedente tabella.

2.4 - Configurazione delle utenze

Affinché sia possibile fare accedere degli utenti, è necessario che questi siano configurati su Keycloak. Per fare quest’operazione è possibile per esempio configurare un servizio di directory LDAP o inserire manualmente qualche utente a puro scopo di test.

Per quest’operazione si rimanda alla documentazione ufficiale di Keycloak dove è possibile recuperare tutte le informazioni necessarie su User Management e User Storage Federation, funzionalità utili per la gestione degli utenti e meccanismi di storage.

3 - Configurazione di Liferay

Una volta conclusa la configurazione dell’istanza Keycloak per quel che riguarda OpenID Connect, occorre configurare Liferay in modo che sia in grado di supportare l’autenticazione tramite OpenID Connect.

Liferay offre built-in il supporto per i sistemi SSO e OpenID Connect rientra tra questi. È possibile aggiungere più configurazioni di OpenID Connection Provider.

Assumiamo quindi che l’istanza del portale Liferay sia operativa e accediamo al pannello di amministrazione utilizzando le credenziali di amministrazione. Ipotizziamo che l’istanza di Liferay sia disponibile all’indirizzo https://portal.smc.lab.local

Per eventuali approfondimenti circa la configurazione di OpenID Connect su Liferay (sia CE sia DXP), fare riferimento alla documentazione ufficiale Authenticating with OpenID Connect.

3.1 - Configurazione di OpenID Connect

Il primo step di configurazione riguarda l’abilitazione di OpenID Connect, il secondo step riguarda invece la configurazione di OpenID Connect e in particolare del Provider.

Per abilitare OpenID Connect, è sufficiente andare su Control Panel => System Settings => SSO => OpenID Connect, mettere la spunta su Enabled e salvare la configurazione (vedi le due figure a seguire).

A questo punto occorre spostarsi sul tab OpenID Connect Provider per inserire tutti i parametri di configurazione che riguardano il servizio dell’Identity Provider (OpenID Connect) configurato in precedenza su Keycloak.

Le due figure a seguire (15 A e 16 B) mostrano la maschera di configurazione dell’OpenID Connect Provider che riporta i parametri di configurazione così come indicati nella tabella precedente.

A questo punto la configurazione di OpenID Connect su Liferay è conclusa. È possibile quindi procedere con un test di accesso.

4 - Accesso a Liferay

Adesso è possibile accedere al portale Liferay utilizzando il protocollo OpenID Connect e testare in questo modo la corretta configurazione.

Dal momento che si attiva l’OpenID Connect, la portlet di Login standard di Liferay mostra il link di accesso via OpenID Connect, così come mostrato dalla figura a seguire.

Nel momento in cui l’utente clicca sul link OpenID Connect, questo è rediretto alla pagina da dove l’utente può selezionare il Provider di autenticazione (vedi figura a seguire). È possibile avere più provider di autenticazione, ecco il motivo per cui è data la possibilità della scelta. Nel nostro caso abbiamo un solo provider che si chiama iam-keycloak-oidc, il nome assegnato in fase di configurazione.

Una volta selezionato il provider e cliccato sul pulsante Sign In, Liferay provvede a rimandare l’utente alla pagina di Login di Keycloak (e in particolare del Realm creato in precedenza).

Sulla pagina di login inserire delle credenziali di accesso valide (per esempio di un utente definito su LDAP o localmente a Keycloak). Se le credenziali inserite sono corrette, allora l’utente sarà rediretto sulla home page del portale Liferay. Qualora l’utente non fosse presente su Liferay, questo sarà creato utilizzando le informazioni ottenute dall'Identity Provider (Keycloak).

Le figure a seguire mostrano il portale Liferay con l’utente appena loggato e le sessioni attive su Keycloak per il client OpenID Connect dedicato a Liferay.

5 - Implementazione del Single Logout (SLO)

L’implementazione built-in di OpenID Connect sulla versione 7.3 di Liferay non supporta la funzionalità di SLO o Single Logout, questo significa che quando un utente viene disconnesso da Liferay (operazione di logout o sessione scaduta), questo non viene automaticamente disconnesso da Keycloak, con la conseguenza che un nuovo accesso non richiederà l’inserimento delle credenziali utenti su Keycloak (se attiva ancora la sessione).

Questa situazione è riportata chiaramente sulla Knowledge Base sotto il nome di Liferay's OpenID Connect implementation and Single Logout (vedi estratto nella figura a seguire). Tuttavia, lo SLO può essere implementato con un'azione di post logout personalizzata.

6 - Il bonus

Immagino che avere la disponibilità un Docker Compose con tutti i servizi configurati che implementi lo scenario descritto, sia un bel bonus; siete della stessa idea?

Il progetto keycloak-openid-connect-liferay pubblicato sul repository GitHub di SMC, contiene il Docker Compose e tutte le configurazioni che abbiamo visto nel corso di questo articolo.

A seguire sono riportati i servizi che compongono lo stack.

1. Keycloak
2. OpenLDAP (implementazione del servizio LDAP per lo store degli utenti)
3. PHP LDAP Admin (interfaccia di amministrazione di LDAP)
4. PostgreSQL (database per Keycloak e Liferay)
5. Liferay
6. fakeSMTP (servizio per l'invio email)
7. Traefik (Load Balancer)

I servizi essenziali sono: Traefik, Keycloak, OpenLDAP, PostgreSQL e Liferay. La figura a seguire mostra il diagramma che riassume lo stack completo.

I servizi di Keycloak e del portale Liferay sono configurati per essere accessibili attraverso Traefik su porta https e sui rispettivi FQDN indicati a seguire:

1. iam.smc.lab.local
2. portal.smc.lab.lacal

Gli step necessari per eseguire l'intero stack sono:

1. Verifica della versione di Docker (Docker Engine 20.10.x, Docker Compose 2.0.x)
2. Clone del repository keycloak-openid-connect-liferay
3. Aggiornamento del file di hosts (della macchina host) con le entry per Keycloak e Liferay
4. Avvio dello stack via Docker Compose

Riguardo la versione di Docker, per questo articolo è stato fatto uso di Docker Desktop per macOS versione 4.1.0 (che include Docker Engine 20.10.8 e Docker Compose 2.0.0).

Ho comunque eseguito un test usando Docker su Linux. Stessa versione di Docker usata su macOS ma con una versione di Docker Compose inferiore, ovvero, la 1.28.6. Non ho riscontrato alcun problema, lo stack dei servizi è stato correttamente tirato su.

Non ho potuto fare test su Windows; lascio a qualcuno di voi la conduzione di questa prova.

# Step 1 - Check Docker version
$ docker version
$ docker-compose version

# Step 2 - Clone the project git repository
$ git clone https://github.com/smclab/keycloak-openid-connect-liferay.git

# Step 3 - Update the /etc/hosts with this content
127.0.0.1   iam.smc.lab.local
127.0.0.1   portal.smc.lab.local

# Step 4 - Start the Docker Compose stack services
$ docker-compose --env-file env/development.env up

Il tempo necessario affinché i servizi siano tutti operativi è variabile e dipende in gran parte dalla disponibilità delle risorse della macchina sui cui è in esecuzione Docker e quante di queste siano state assegnate a Docker stesso.

In questo specifico caso ho assegnato a Docker le seguenti risorse: CPUx2, 8GByte di memoria RAM, 1GByte di Swap e 10GByte di storage. Queste sono le risorse minime per avere un ambiente "usabile". Ho eseguito un test con 6GByte di memoria RAM, lo stack "regge" anche se funziona con fatica.

Per darvi un'idea dei tempi di star-up (escludendo i tempi di pull delle immagini), sul mio MacBook Pro 2,5 GHz Intel Core i7 dual-core, 16 GB 2133 MHz LPDDR3, il tempo di star-up è di circa sei minuti, per il primo start, tempo che scende a circa 3,5 minuti dal secondo start.

I tempi di start-up sulla mia Workstation Linux sono decisamente inferiori. Il primo start 1,15 minuti, dal secondo start in poi 1,02 minuti.

Una volta che i servizi sono tutti su, l'ambiente è pronto per essere configurato così come abbiamo visto nel corso di questo articolo. Un modo veloce per controllare che i servizi di nostro interesse siano su, è quello di connettersi alla console di Traefik all'indirizzo http://localhost:9080/dashboard. La figura a seguire mostra lo stato dei servizi di Keycloak e Liferay.

Le credenziali di accesso per i vari servizi sono indicate a seguire:

1. Keycloak (credenziali di accesso alla console di amministrazione): admin/Pa55w0rd
2. Liferay (credenziali di accesso come amministratore): test/test
3. LDAP (credenziali di accesso come amministratore): cn=admin,dc=smc,dc=local/admin
4. LDAP (credenziali di accesso in sola lettura): cn=readonly,dc=smc,dc=local/readonly

Il file LDAP Data Interchange Format config/ldap/bootstrap.ldif (disponibile sul repository) contiene tutta la struttura di directory del servizio LDAP. La password per tutti gli utenti è: test.

Tips configurazione Liferay: dovreste notare che il portale Liferay risulta già configurato per la parte di OpenID Connect, l'unica cosa da revisionare è il client secret (generato su Keycloak) che dovreste aggiornare.

Tips configurazione Keycloak: Keycloak non risulta essere configurato, dovreste provvedere voi a farlo secondo quanto descritto nel corso dell'articolo, oppure, potreste caricare la configurazione dal file json realm-export-smc-lab-local-realm.json disponibile all'interno del repository (directory config/keycloak/export). Nel caso della seconda opzione, ricordo che dovreste poi rigenerare il client secret e rimettere la password di accesso per il servizio LDAP.

7 - Conclusioni

Ben arrivati alla fine! Per esseri giunti fino in fondo alla lettura di questo articolo, sono abbastanza sicuro che vi siate trovati nella situazione appena descritta o che siate in procinto di dover affrontare quest'attività.

Mi son trovato più volte in questa situazione, e la strada che ho voluto indicare con questo articolo è quella che ritengo più vantaggiosa, soprattutto in termini di sforzo.

Voi come avete affrontato questo tema? Discutiamone insieme.