Connecting an Identity Provider

enaio® • 10.10 »

Identity providers such as Keycloak can be connected to enaio® gateway for authentication for enaio® webclient and enaio® webclient as a desktop application using Connect/OAuth2 via a reverse proxy, such as OpenResty.

The installation and configuration of OpenResty with Keycloak for this type of scenario are broadly described here.

Installing OpenResty

OpenResty can be integrated into a docker environment or installed directly in Windows.

OpenResty as a Docker Service

The installation takes place in the following steps:

  • Create a directory for the OpenResty configuration file.

    The path may not contain spaces. For example: C:\openresty

  • Execute the following docker commands via the command prompt:

    • Create the OpenResty container:

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

      Both port entries must be identical and match the port for OpenResty in the openresty.conf file.

      For configuration, copy the modified openresty.conf file into the container.

    • Start the OpenResty container:

      docker start openresty

    • Check the container:

      docker container list -a

      The container must display the Up status.

OpenResty in Windows

The installation takes place in the following steps:

Configuring OpenResty

Configuration takes place via the openresty.conf file, which is available for download. The file must be modified and then copied into the corresponding directories: into the container for OpenResty as a docker service or into the \conf\ directory of the Windows installation.

In addition to placeholders, which must be replaced, the file contains other parameters that can be optionally modified or extended. Refer to the documentation of Nginx and OpenResty for more information.

Placeholders and parameters in the configuration file
Placeholders Function
listen ${port};

The port through which OpenResty accepts requests.

By default, OpenResty expects that port 80 is available, even if changed.
proxy_pass ${gateway‑url}; Root URL of enaio® gateway. All incoming requests from OpenResty are forwarded to this address.
${header-name}

Header name that must match the corresponding HTTP header configuration for enaio® gateway.

 
${discovery-url} The URL via which OpenResty accesses the identity provider’s configuration.
${client-id}

${client-secret}

Client ID and secret from the identity provider’s client configuration
${user-field}

User name parameter, the value of which is transmitted to enaio® gateway for login.

A user account with a unique name must be created in the enaio® 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 for which bearer tokens remain in the cache for authentication.

Configuring enaio® gateway

enaio® gateway must be configured for authentication via HTTP Header.

Additionally, the enaio® gateway application-prod.yml configuration file must be extended in order to redirect the logout to OpenResty’s logout.

proxy:
defaultLogoutRedirect: '/logout'

enaio® gateway is installed with port 80 by default. If OpenResty is installed on the same host, as is recommended, then a free port must be configured for enaio® gateway. If OpenResty is running on another host, then logins – for example to enaio® webclient – must be made via this host.

Connecting to an Azure Active Directory

The configuration of OpenResty must be individually adapted to each identity provider, since the OpenID Connect protocol provides some leeway for manufacturers.

The files openresty-azure-username.conf and openresty-azure-oid.conf contain preconfigured examples for Azure AD where just a few specific parameters need to be modified. They are set for SSL and integrate certificate files. The openresty-azure-username.conf file is used to send fully qualified user names such as mustermann@example.onmicrosoft.com to enaio® gateway, and the openresty-azure-oid.conf file is used to pass Azure object IDs to enaio® gateway.

The following parameters must be specified:

set $tenant_id

set $client_id

set $client_secret

 Specify tenant ID, client ID, and client secret
ssl_certificate Path and file name of the certificate file
ssl_certificate_key Path and file name of the key file
proxy_pass Address of enaio® gateway with port.

By default, the file is stored in the configuration directory ...\etc\nginx\conf.d\.

Testing the connection to Azure Active Directory using curl

The system configuration can be tested with curl as described below. An access token, which OpenResty needs for the login, is requested for this purpose. The token requests contain entries in JSON format from which the value to the 'access_token' is inserted into theenaio® user information request.

By default, Azure AD access tokens expire after one hour. Access tokens can be requested for both user and service accounts.

  • Request access token for a user account:

    curl -s -k \
    --url "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
    -d "client_id=<client-id>" \
    -d "client_secret=<client-secret>" \
    -d "username=<user-name>@<tenant-name>.onmicrosoft.com" \
    -d "password=<user-password>" \
    -d "grant_type=password" \
    -d "scope=openid <client-id>/.default"
  • Request access token for the service account of the OpenResty client:

    • curl -s -k \
    --url "https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token" \
    -d "client_id=<client-id>" \
    -d "client_secret=<client-secret>" \
    -d "grant_type=client_credentials" \
    -d "scope=openid <client-id>/.default"

  • Log in to OpenResty with an access token and request the enaio® credentials:

    • curl -s -k \
    --url "https://openresty.example-ag.org/osrest/api/session" \
    -H "Authorization: Bearer <'access_token'-value>"