OIDC with PLANTA secure

General

Information

PLANTA project provides an enhanced security standard via the PLANTA secure component, e.g. by means of a two factor authentication (2FA). This function will be extended by authentication via OpenID Connect. This approach works via communication between the following components:

PLANTA Client
PLANTA Server
PLANTA Client Adapter (CA) (from C 39.5.31 integrated in PLANTA Client)
PLANTA Server Adapter (SA)
Reverse Proxy (OIDC Client)
Identity Provider (IDP)

With Server release S39.5.31, PLANTA secure was integrated in the server. This means that additional components like Tomcat Server or PLANTA Server Adapter are no longer required.

Operation Principle

In order to enable authentication, all requests will initially be sent to the reverse proxy (1).
There it will be checked whether it is an already authenticated request. If this is the case, a connection to IDP will be established via OIDC client (2) and the usual provider login will take place (e.g. login to Azure) (3 - 5).
After login, the IDP answers with an access-token (or ID token in some cases) (6).
It will then be processed by the reverse proxy (7). More precisely, authResponseHeaders will, e.g., be used for user name (X forwarded user) and a cookie will be allocated which confirms successful authentication.
Subsequently, another attempt to send the initial query will take place, which will be forwarded to the server adapter this time thanks to the valid cookie (8).
Further requests will then usually be forwarded regularly as long as the cookie remains valid (9).

Configure PLANTA secure

From S 39.5.32 and C 39.5.31

On the server you have to adjust the following parameters in the secure.conf file:

reverse_proxy.auth = true

reverse_proxy.user_header = x-forwarded-user

reverse_proxy.user_token = x-forwarded-token

reverse_proxy.user_format = plain

You have to store the correct OpenIdConnect plugin for the Client adapter in the planta.ini. Here, you furthermore have additional setting options which are documented here.
The user token is optional and must remain empty if it is not used.
The PLANTA Server must be configured for proxy authentication.
Further information on general settings for PLANTA secure can be found here.

Requirements to the IDP application

The following scopes must be approved: openid, profile, email
- Depending on which identity provider (e.g. ADFS) is used, the allatclaims scope must be approved in addition.
In order to be able to ensure user-mapping between the authenticating users and the users of the PLANTA project system, the e-mail address assigned to each user must be the same as that specified in the PLANTA project system.

Deployment

As deployment procedure, an environment for the creation of docker containers is required in addition to the setup of PLANTA secure.

Requirements

docker (min. v19.03.10)
docker-compose (min. v1.27.4)

Supply Packet

./docker-compose.yml

contains container configuration

./traefik

./traefik/traefik.toml

contains reverse proxy configuration

Configuration Adjustment

Port mapping

The port for incoming HTTPS queries can be adjusted in the docker-compose.yml file under services.traefik.ports:

"[custom https port]:443"

OIDC settings

The following environment variables must be configured for successful communication to IDP in the docker-compose.yml file under services.traefik-forward-auth.environment:

PROVIDERS_OIDC_ISSUER_URL
PROVIDERS_OIDC_CLIENT_ID
PROVIDERS_OIDC_CLIENT_SECRET
SECRET (secret which is used to sign the cookie)

Optional resource indicator:

PROVIDERS_OIDC_RESOURCE

If it is necessary to adjust the redirect URL, the base URL path can be configured:

URL_PATH (Default: /PlantaServerAdapter/_oauth)

In order to ensure routing to the SA, the URL_PATH must start with the /PlantaServerAdapter/ prefix.

Store SA end point

In the traefik.toml, the URL of the SA must be stored under Dynamic Configuration > http.services.plsa.loadBalancer.servers. It is specified in the following format without path:

^{url = "http://[host]:[port]"}

Certificates

For a certificate you can either activate the automatic generation of a Let’s Encrypt certificate:

For this purpose, uncomment the line under Dynamic Configuration > http.routers.oidc.tls
in the traefik.toml file:
^{certResolver = "tls"}
Furthermore the host with configured port must be externally accessible

OR must alternatively have its own certificate:

For this purpose, uncomment the entire tls block under Dynamic Configuration > tls in the traefik.toml file
Store the certificate and the corresponding key as base64-coded files under ./traefik/certs.
By default, the files must be named cert.pem and privkey.pem or changed in the configuration in the traefik.toml file under Dynamic Configuration > tls.stores.default.defaultCertificate and Dynamic Configuration > tls.certificates.

`docker-compose` commands

After adjustment of the configuration, start the container:

docker-compose up –d

Status of the containers:

docker-compose ps

Consult logs:

docker-compose logs