Integrating an Identity Provider

For authentication purposes, identity providers like Keycloak can be integrated into yuuvis® RAD gateway using OpenID Connect/OAuth2 by way of a reverse proxy such as OpenResty.

The basic steps required to install and configure Keycloak for a scenario like the one shown above are described here.

Installing OpenResty

OpenResty can be integrated into a Docker environment as a service or installed directly in Windows.

OpenResty as a Docker Service

Steps to install the service:

• Create a directory for the OpenResty configuration file.

  The path may not contain any spaces. Example: C:\openresty

• Run the following Docker commands via the command prompt:

  • Create OpenResty container:

    docker create --name openresty -p 80:80
    -v C:\openresty:/etc/nginx/conf.d docker.yuuvis.org/library/openresty

    The port you enter must be the same in both cases and match the port for OpenResty from the openresty.conf file.

    Copy the modified openresty.conf file for the configuration in the container.

  • Start OpenResty container:

    docker start openresty

  • Check container:

    docker container list -a

    The container must have the status Up.

Running OpenResty in Windows

Steps to install the service:

• Download OpenResty for Windows and unzip the archive on the C: partition.

  Recommendation: Install OpenResty on the yuuvis® RAD gateway host.

• Download the following lua packages and save them in the OpenResty directory \lualib\resty\:

  • https://github.com/cdbattags/lua-resty-jwt/tree/master/lib/resty

  • https://github.com/ledgetech/lua-resty-http/tree/master/lib/resty

  • https://github.com/bungle/lua-resty-session/tree/master/lib/resty

  • https://github.com/jkeys089/lua-resty-hmac/tree/master/lib/resty

  • https://github.com/zmartzone/lua-resty-openidc/tree/master/lib/resty

  • https://github.com/fffonion/lua-resty-openssl/tree/master/lib/resty

• Modify the nginx.conf configuration file from the OpenResty directory \conf\:

  • Delete the <server> section and replace it with the following entry:

    include C:\<OpenResty-Installation>\conf\openresty.conf;

    The openresty.conf configuration file is copied to this directory after changes are made.

• Launch OpenResty from the installation directory via the command line:
  start nginx

• Check whether OpenResty is running via Task Manager or via the command line:
  tasklist -fi "imagename eq nginx.exe"

Configuring OpenResty

OpenResty is configured via the openresty.conf file which is available for download. Changes must be made to the file which then needs to be saved in the corresponding directory, either in the container for OpenResty as a Docker service or in the \conf\ directory of the Windows installation.

Aside from placeholders that need to be replaced, the file also contains additional parameters that can optionally be changed or extended. For more information please refer to the Nginx and OpenResty documentation.

Placeholders and Parameters in the Configuration File

Placeholders	Function
listen ${port};	Port used by OpenResty to import calls. By default, OpenResty expects port 80 to be available when changes are made.
proxy_pass ${gateway‑url};	Root URL of yuuvis® RAD gateway. All incoming calls from OpenResty are forwarded to this address.
${header-name}	Header name according to the HTTP header configuration for yuuvis® RAD gateway.
${discovery-url}	URL used by OpenResty to access the configuration of the identity provider.
${client-id} ${client-secret}	Client ID and secret from the client configuration of the identity provider.
${user-field}	Parameter of the user name whose value is transferred for purposes of logging in on yuuvis® RAD gateway. A user account with the corresponding name must be created in the yuuvis® RAD user administration. Example: preferred_username The placeholder must be replaced at two places in the configuration file.
lua_shared_dict introspection 10m;	Optional: Time period in minutes that the bearer tokens for authentication remain in the cache.

Configuring yuuvis® RAD gateway

yuuvis® RAD gateway must be configured for authentication for each HTTP header.

Configuration for yuuvis® RAD agent

If yuuvis® RAD agent is used in environments with Identity Provider and OpenID Connect/OAuth2, installation requires that you make a corresponding entry in the connections.json configuration file and set up an additional configuration file that provides connection data to the Identity Provider.