Today’s system landscape consists of more and more “apps”. These apps can be small single-purpose applications like time tracking or chat, to big scale applications such as groupware applications or wikis.
However, in the age of “the cloud”, many applications are not hosted on your own premises but instead managed or provided by third-parties which means an integration into a local OpenLDAP or ActiveDirectory is not possible.
One possibility to bridge authentication in such scenarios is via so-called “social login” providers. These are the various login options that you see at popular web services that provide options like “Login with Facebook”, “Login with Google”, “Login with x”. Such providers may be convenient for private use, but what about usage in a business context?
Since the integration of services is an important factor in groupware and collaboration software, we decided to create Kopano Konnect to help in these scenarios. Konnect is an OpenID provider (OP) that directly integrates a web login and consent form. It brings support for both OpenID Connect (OIDC) and Open Authentication (OAuth 2.0). In addition to the easier integration with third-party applications, Kopano Konnect will also provide the authentication part for the Kopano RestAPI and clients consuming it.
Kopano Konnect was primarily designed to allow easy sign in with your Kopano account, but it is also able to validate users against an LDAP and a cookie-based backend. The architecture of Kopano Konnect favours a mostly stateless setup, where no session data is stored locally but rather encapsulated within the token (jwt) that is sent to the user. In fact, the only requirements that Konnect has apart from the user backend are an encryption secret, a private key to sign the user tokens and if services are running under a different hostname a yaml file that services as a client registry. If the encryption secret or private key are missing Konnect will generate a random key at startup (user sessions won’t survive a restart in this case).
Downloading and running Kopano Konnect
At the time of writing this blog there are three ways of getting Kopano Konnect:
- doing a clone of the source code and manually compiling it
- downloading an archive with the already compiled program
- or running Konnect in a Docker container build from the above archive.
The last two download options are automatically updated once there has been a new commit to the master branch of the git repository (and all stages of the included Jenkinsfile have succeeded).
For the 8.7 release of Kopano Groupware Core, we also want to provide Debian and RPM packaging of Kopano Konnect. Customers with a subscription will then also have access to manually QA’d and supported releases. For simplicity, the following steps are making use of the Kopano Konnect Docker image and use an already running Kopano setup for authentification. Kopano Konnect should be installed on a system where it has local access to a running kopano/server process.
Creating secrets and starting Kopano Konnect
As explained above Kopano Konnect needs access to some key files for secure session handling. In case these keys are not generated by the admin Konnect will generate a random key at startup itself, which will make user sessions not persistent between restarts of Konnect.
To generate these two files just issue the following two commands:
openssl rand -out /etc/kopano/konnectd-encryption.key 32 openssl genpkey -algorithm RSA -out /etc/kopano/konnectd-tokens-signing-key.pem -pkeyopt rsa_keygen_bits:4096
Kopano Konnect should be run as the Kopano user, so you should also change the owner of these two files to the kopano user to avoid file access problems:
chown kopano:kopano /etc/kopano/konnectd-tokens-signing-key.pem /etc/kopano/konnectd-encryption.key
Once the secrets have been created we can start Kopano Konnect for the first time. The following command will start the official Kopano Konnect Docker container in the foreground:
docker run -it --rm=true --name=kopano-konnect \ --read-only \ --volume /etc/kopano:/etc/kopano:ro \ --volume /etc/ssl/certs:/etc/ssl/certs:ro \ --volume /etc/kopano/konnectd-tokens-signing-key.pem:/run/secrets/konnectd_signing_private_key:ro \ --volume /etc/kopano/konnectd-encryption.key:/run/secrets/konnectd_encryption_secret:ro \ --env KOPANO_SERVER_DEFAULT_URI=file:///run/kopano/server.sock \ --volume /run/kopano:/run/kopano:rw \ --publish 127.0.0.1:8777:8777 \ --user kopano:kopano \ kopano/konnectd:latest \ serve \ --iss=https://$(hostname) \ kc
In the above command, the --iss line is very important in the context of OpenID, as it defines the URL that Konnect is reachable from by the outside world. To actually make Konnect accessible from this URL (and to provide https) a reverse proxy should be used. The git repository of Konnect provides example configuration file for Caddy, but other web servers like Apache or Nginx can be used as well.
Below is an example configuration for Apache, since most Kopano installations use Apache as their default web server:
# Kopano Konnect OIDC ProxyPass /.well-known/openid-configuration http://localhost:8777/.well-known/openid-configuration retry=0 ProxyPass /konnect/v1/jwks.json http://localhost:8777/konnect/v1/jwks.json retry=0 ProxyPassReverse /konnect/v1/jwks.json http://localhost:8777/konnect/v1/jwks.json ProxyPass /konnect/v1/token http://localhost:8777/konnect/v1/token retry=0 ProxyPassReverse /konnect/v1/token http://localhost:8777/konnect/v1/token ProxyPass /konnect/v1/userinfo http://localhost:8777/konnect/v1/userinfo retry=0 ProxyPassReverse /konnect/v1/userinfo http://localhost:8777/konnect/v1/userinfo ProxyPass /konnect/v1/static http://localhost:8777/konnect/v1/static retry=0 ProxyPassReverse /konnect/v1/static http://localhost:8777/konnect/v1/static # Kopano Konnect login area ProxyPass /signin/ http://localhost:8777/signin/ retry=0 ProxyPassReverse /signin/ http://localhost:8777/signin/
Once the web server has been configured you can navigate to https://$(hostname)/signin and will be greeted by the login screen of Kopano Konnect.
Configuring third-party applications to use Kopano Konnect
An important resource for configuring third-party clients for the use of Kopano Konnect is the so-called “discovery document”. When running the above proxy server configuration the discovery document will be available from https://$(hostname)/.well-known/openid-configuration. Some client applications are able to autoconfigure themselves from this url and for applications that do not support this, you will still be able to find a listing of all relevant url endpoints of Konnect and the supported claims and scopes.
Most claims and scopes supported by Konnect are defined by the OpenID Connect standard, but there are also some additional scopes defined by us that I want to quickly introduce.
konnect/id→ will change the return value for the user id to a numerical value.konnect/hashed_sub(introduced in 0.8.0) → the subject is normally equal to the unique user id in Kopano, but this value can include characters that are not allowed on the client side (like the plus sign for example), we, therefore, have introduced an additional claim that will convert the subject to an url safe value for these applications.kopano/gc(introduced in 0.9.0) → a scope that will be used by the by the Kopano Rest API to determine the unique user id, ifkonnect/hashed_subis used.
In case an application is running on the same domain name as Konnect it will be automatically trusted. In case the application uses a different hostname, then the application needs to be “registered” before it can actually be used. For this registration, the file identifier-registration.yaml is used (please check the git repository for an example file).
Using Kopano Konnect to sign into Nextcloud
With this knowledge, we can now configure Nextcloud so that users will be able to sign into Nextcloud from Kopano Konnect. The below steps require the use of Kopano Konnect >=0.8.0 and have been tested with the Nextcloud 13.0.4 and the Nextcloud “Social Login” app in version 1.9.2 and 1.9.4.
The ability to sign into Nextcloud via OpenID Connect is unfortunately not a core component of Nextcloud, but instead needs to be achieved via the installation of a third party plugin (through the Nextcloud App Market). After the plugin has been installed administrators will see a new menu option called “Social Login” in the Nextcloud settings. From there a new “Custom OpenID Connect” can be configured.
The following values need to be filled in:
- Internal name → internal identifier can, for example, be set to “Kopano”
- Title → this is what will be displayed to the user on the Nextcloud login screen. Should be named “Kopano Konnect” or something else that the user can easily identify.
- Authorize url → this setting is named “authorization_endpoint” in the discovery document. value is for example https://$(hostname)/signin/v1/identifier/_/authorize
- Token url → this setting is named “token_endpoint” in the discovery document. Value is for example https://$(hostname)/konnect/v1/token
- User info URL (optional) → this setting is named “userinfo_endpoint” in the discovery document. Value is for example https://$(hostname)/konnect/v1/userinfo
- Client Id → self-defined value used to identify if the client registry is used (more below)
- Client Secret → self-defined value, does not get evaluated at the moment
- Scope → the list of required scopes, here openid profile email konnect/hashed_sub need to be entered.
In case Nextcloud is running on a different host or just on a different domain name, we also need to add an entry for it to the client registry. For this the following values need to be added to the end of the example file:
- id: nextcloud # same id as before name: Nextcloud # self-defined value application_type: web redirect_uris: - https://nextcloud.$(hostname)/index.php/apps/sociallogin/custom_oidc/Kopano
In the redirect_uris section the last part of the url (“Kopano”) needs to be the same value as the “internal name” in the Social Login configuration.
Once these settings are set there is a new button on the Nextcloud login page (with the text “Kopano Konnect”) that users can use to sign into Nextcloud.
In case the Kopano users already exist inside of Nextcloud (since both systems use a common ldap tree for example) it is recommended to check the options “disable auto create new users” and “allow users to connect social logins with their account” inside of the Social Login settings to prevent users from accidentally creating new user accounts when trying to login.
Once this is done the user can then link his existing Nextcloud user to the OpenID Connect user in his personal settings below the item “additional settings”.
Where to go from here?
If you have any further questions make sure to study the readme file of Kopano Konnect.
We are looking forward to your feedback on this version, let us know what you think by sending an email to , or posting over at the Kopano Forum.
