WEBCON BPS integration with Keycloak

Applies to version: 2021.1.x and above; author: Michał Bednarz

This article describes the process of integration WEBCON BPS with Keycloak. Keycloak is an open source software that enables single sign-on using identity and access management in modern applications and services.

Requirements

1. WEBCON BPS StandAlone (version 2021) – the portal available with the use of SSL by the address in the FQDN format.
2. Keycloak Server (the article uses version 12.0.3) - the site available with the use of SSL by the address in the FQDN format.

In this case, all software is installed on one server, and nginx server is used as the reverse proxy.

Important: Keycloak server in StandAlone mode was used. This mode is not recommended for use in a production environment that requires high availability.

Keycloak server installation -> https://www.keycloak.org/docs/latest/getting_started/index.html#installing-the-server

Nginx server installation -> https://community.webcon.com/posts/post/ssl-offloading-vs-webcon-bps-portal/161

Below is the nginx server configuration (to be published as the nginx code):

worker_processes  1;

events {
    worker_connections 1024 ;
}

http {

    include mime.types ;
    default_type  application/octet-stream;
    sendfile on ;
    keepalive_timeout  65;
    proxy_busy_buffers_size 512k ;
    proxy_buffers 4 512k ;
    proxy_buffer_size 256k ;
    large_client_header_buffers 4 32k ;

    server {
        listen 443 default ssl;
        server_name at14.webcon.pl www.at14.webcon.pl;
        ssl_certificate C:/nginx/cert/webcon.crt;
        ssl_certificate_key C:/nginx/cert/webcon.rsa;
        add_header Strict-Transport-Security max-age=2592000;

        location / {
            proxy_pass http://at14.webcon.pl:80;
            proxy_set_header Host $ host ;
            proxy_set_header X-Real-IP $ remote_addr ;
            proxy_set_header X-Scheme $ scheme ;
            proxy_connect_timeout 1;
            proxy_send_timeout 30 ;
            proxy_read_timeout 30 ;
        }
    }

    server {
        listen 443 ssl http2 ;
        server_name keycloak.webcon.pl www.keycloak.webcon.pl;
        ssl_certificate C:/nginx/cert/webcon.crt;
        ssl_certificate_key C:/nginx/cert/webcon.rsa;
        add_header Strict-Transport-Security max-age=2592000;

        location / {
            proxy_pass http://localhost:8080;    
            proxy_read_timeout 90 ;
            proxy_set_header X-Real-IP $ remote_addr ;
            proxy_set_header X-Forwarded-For $ proxy_add_x_forwarded_for ;
            proxy_set_header X-Scheme $ scheme ;
            proxy_set_header X-Forwarded-Proto $ scheme ;
            proxy_set_header Host $ host ;
            proxy_http_version 1.1;
        }
    }
}

Realm configuration and application registration in Keycloak Server

Log in to the Keycloak administration console, create a new realm and user based on the product documentation -> https://www.keycloak.org/docs/latest/getting_started/index.html#creating-a-realm-and-a-user.

Next, register the application client. Go to the Clients tab -> Create, and in the “Client protocol” field enter openid-connect.

After saving, complete the remaining configuration fields:

• In the Access Type field, select confidential.
• In the Root URL field, enter the address of the BPS Portal website.
• In the Valid Redirect URL field, enter the Portal Redirect URL. It will be the address in the https: // < portal fqdn> / signin- <openid application schema in BPS configuration> format.

Save the changes and go to the Credentials tab. In the Client Authenticator field, select Client ID and Secret. Then copy the value of the Secret field.

Configuration on the WEBCON BPS side

Go to system configuration and in Authentication providers add a new provider – OpenID Connect. You need to complete the following fields:

• Scheme - scheme name that can be compatible with the configuration on the Keycloak side

• Authority and Claims Issuer – these fields should be completed with the address created in Keycloak Realm

• Client id – name of the application registered in Keycloak
• Client Secret – secret value copied from Keycloak

Save the changes and restart the portal application pool.

To log in to the Portal with a Keycloak user, add them to the BPS users list. Please note that the email address is used as the user's identity. You must also grant application or administrative privileges for a new user.

Testing

When you go to the portal website, the new provider is displayed on the list of available providers:

Select the new provider – you will be redirected to the Keycloak Server authentication page of the new application:

You must log in using the previously created user, after successful login you will be redirected to the Portal page: