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 

  • 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.
  • 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_format = plain

  • The proper OpenIdConnect plugin for the client adapter must be stored in the PlantaClientAdapter.exe.config . Furthermore there are other setting options which are documented in the file itself.
  • The PLANTA Server must be configured for proxy authentication.
  • Further information on general settings for PLANTA secure can be found here.
  • The following parameters must be adjusted in the WEB-INF\classes\config.properties file on the server adapter:

reverse_proxy.auth = true 

reverse_proxy.user_header = x-forwarded-user

reverse_proxy.user_format = plain

  • The proper OpenIdConnect plugin for the client adapter must be stored in the PlantaClientAdapter.exe.config . Furthermore there are other setting options which are documented in the file itself.
  • 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 guarantee 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 under services.traefik.ports:

  •  "[custom https port]:443"

OIDC settings 

The following environment variables must be configured for successful communication to IDP in docker-compose.yml 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 an 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 are to be named cert.pem and privkey.pem or to be 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