OpenID Connect (OIDC)
Introduction
OpenID Connect is an open standard for single sign-on and identity and access management. With ownCloud it can be used for user authentication and client authorization against an external Identity Provider.
Benefits of using ownCloud with OpenID Connect
-
Increased security by shifting user authentication to an external Identity Provider
-
Seamless integration into single sign-on (SSO) environments as well as with third party products
-
Centralized client management within the Identity Provider
-
Enterprise-grade security through the use of authentication security features (e.g., multi-factor authentication) and policies (e.g., automatic token expiration on certain conditions) provided by Identity Providers
Prerequisites
-
OpenID Connect requires an external Identity Provider
-
A distributed memcache setup is required to operate this app - such as Redis or Memcached. Please follow the documentation on how to set up caching.
Setup and configuration
Setting up ownCloud Server to work with OpenID Connect requires a couple of components to work together:
-
An external Identity Provider configured to work with the ownCloud components
-
The OpenID Connect App installed on ownCloud Server
-
Configuration for the OpenID Connect App in
config.phpon ownCloud Server -
Service discovery for the ownCloud Clients
The sections below will explain these areas and provide configuration examples using Kopano Konnect as the external Identity Provider.
For the configuration examples, let’s assume we have
-
ownCloud Server available as
https://cloud.example.com -
Kopano Konnect available as
https://idp.example.com
Set up and configure the Identity Provider
In order to get your Identity Provider running and ready to be used with ownCloud, you have to obtain Kopano Konnect and run it with a set of configuration values which can be provided as environment variables. See the Kopano Konnect documentation for details.
Specifically, you have to
-
provide basic configuration
-
set up a reverse proxy to expose the routes required to connect to Kopano Konnect. You’ll find instructions in the Kopano Konnect documentation.
-
register the ownCloud Clients
Kopano Konnect can be set up via Docker. Images are available on Docker Hub (kopano/konnectd).
|
Register ownCloud Clients
To allow the ownCloud Clients (Web/Desktop/Android/iOS) to interact with the Identity Provider, you have to register them as clients. In the case of Kopano Konnect you can do this using Konnect’s identifier-registration.yaml.
Below you find the default values for the regular ownCloud Clients. Other environments might require a different set of values.
When registering ownCloud as an OpenID Client, use https://cloud.example.net/index.php/apps/openidconnect/redirect as the redirect URL. If OpenID Connect Front-Channel Logout 1.0 is supported, please enter https://cloud.example.net/index.php/apps/openidconnect/logout as the logout URL within the client registration of the OpenID Provider.
|
Client ID
-
Server / Web: As specified in
config.php -
Desktop:
xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69 -
Android:
e4rAsNUSIUs0lF4nbv9FmCeUkTlV9GdgTLDH1b5uie7syb90SzEVrbN7HIpmWJeD -
iOS:
mxd5OQDk6es5LzOzRvidJNfXLUZS2oN3oUFeXPP8LpPrhx3UroJFduGEYIBOxkY1
Configure ownCloud Server
To set up ownCloud Server to work with OpenID Connect, you have to
-
Install the OpenID Connect App
-
Configure config.php
-
Set up service discovery
| It is recommended to first figure out all configuration on a test system and to bring it to the production system once it’s proven to work. Enabling the OpenID Connect App on the production system should be the last step in this process as it will then advertise OpenID Connect to all clients. |
List of OpenID Connect config.php parameters
These are the config.php parameters available to configure OpenID Connect on ownCloud Server:
| Parameters | Description |
|---|---|
|
the URL of the Identity Provider (for some Identity Providers like Keycloak or Azure AD this parameter holds more than just a domain but also a path) |
|
the client ID for the ownCloud Web interface as specified in the Identity Provider client registration |
|
the client secret for the ownCloud Web interface as specified in the Identity Provider client registration |
|
the mode to search for users in ownCloud - possible values are |
|
the attribute which is taken from the access token JWT or user info endpoint to identify a user |
|
by default the OpenID Connect App will add a button on the login page that will redirect the user to the Identity Provider and allow authentication via OIDC. This parameter allows to modify the button text. |
|
if set to |
|
the full URL under which the ownCloud OpenID Connect redirect url is reachable (only needed in special setups) |
|
if set to |
|
depending on the setup and needs of the Identity Provider, the list of required scopes is entered here |
|
additional configuration depending on the Identity Provider can be entered here (usually only necessary if the Identity Provider does not support service discovery) |
|
additional parameters which are sent to the Identity Provider during the auth requests |
|
if set to |
|
the client id to be used with the token introspection endpoint |
|
the client secret to be used with the token introspection endpoint |
|
a given URL where the Identity Provider should redirect to after logout |
|
use this parameter to limit the users which are allowed to login to a specific user backend like LDAP ( |
|
if set to |
Example configuration for Kopano Konnect
An example snippet that can be added to config.php is shown below. It is based on the configuration of the Identity Provider (Kopano Konnect). Other environments might require a different set of parameters and values.
'openid-connect' =>
array (
'provider-url' => 'https://idp.example.com',
'client-id' => '<owncloud-server-client-id>',
'client-secret' => '<owncloud-server-client-secret>',
'loginButtonName' => 'Kopano',
'autoRedirectOnLoginPage' => false,
'mode' => 'userid', // change this to 'email' if necessary (see Identity Provider configuration)
'search-attribute' => 'preferred_username', // change this to suit your environment (see Identity Provider configuration)
),Set up service discovery
In order to allow the ownCloud Clients (Desktop/Android/iOS) to make use of OpenID Connect, ownCloud Server needs to provide service discovery information under the static path https://cloud.example.com/.well-known/openid-configuration.
When enabled, the OpenID Connect App provides the service discovery information on the endpoint https://cloud.example.com/index.php/apps/openidconnect/config.
To make the endpoint available under the static service discovery path, it is recommended to put a RewriteRule in place using .htaccess (the Apache modules proxy and proxy_http have to be enabled):
RewriteRule ^\.well-known/openid-configuration /index.php/apps/openidconnect/config [P]
| Depending on the respective infrastructure setup there can be other ways to solve this. In any case, please make sure not to use redirect rules as this will violate the OpenID Connect specification. |
| Once service discovery is available as described above, the ownCloud Clients will attempt to connect via OpenID Connect. |
Supported Identity Providers
ownCloud Server can work with Identity Providers that support OpenID Connect. There are many Identity Providers available and the OpenID Connect implementations vary a lot in terms of supported features as well as configuration needs. Please get in touch with ownCloud Consulting if you need help with a specific Identity Provider.
ownCloud desktop and mobile clients
ownCloud desktop and mobile clients detect if OIDC is available (service discovery), and use this login method when a new account is created.
Migrate clients from basic authentication to OIDC
If your users are logged in to their desktop and mobile clients via basic authentication (username/password) against ownCloud Server and you are not using OAuth2 to authorize the ownCloud clients, a migration to OIDC can be conducted as follows:
-
Make sure you have a working OIDC configuration based on the above sections
-
Enable the OpenID Connect App
-
Enable token only authentication
Once the OpenID Connect App is enabled, token only authentication is enforced, and service discovery is properly set up, the ownCloud Clients will ask the users to re-authenticate. After a successful re-authentication, the migration is done.
To connect legacy clients, users have to generate special app passwords (tokens).
Migrate clients from OAuth2 to OIDC
If you use OAuth2 for client authorization, a migration to OIDC can be conducted as follows:
-
Make sure you have a working configuration based on the above sections
-
Enable the OpenID Connect App (while having the OAuth2 App still enabled)
-
Disable the OAuth2 App
Once the OAuth2 App is disabled (and service discovery is properly set up), the ownCloud Clients will ask the users to re-authenticate. After a successful re-authentication, the migration is done.