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.php on 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

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

Client Secret
  • Server / Web: As specified in config.php

  • Desktop: UBntmLjC2yYCeHwsyj73Uwo9TAaecAetRwMw0xYcvNL9yRdLSUi0hUAHfvCHFeFh

  • Android: dInFYGV33xKzhbRmpqQltYNdfLdJIfJ9L5ISoKhNoT9qZftpdWSP71VrpGR9pmoD

  • iOS: KFeFWWEZO9TkisIQzR3fo7hfiMXlOpaqP8CFuTbSHzV1TUuGECglPxpiVKJfOXIx

Redirect URIs
  • Android: oc://android.owncloud.com

  • iOS: oc://ios.owncloud.com and oc.ios://ios.owncloud.com

Configure ownCloud Server

To set up ownCloud Server to work with OpenID Connect, you have to

  1. Install the OpenID Connect App

  2. Configure config.php

  3. 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

provider-url

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)

client-id

the client ID for the ownCloud Web interface as specified in the Identity Provider client registration

client-secret

the client secret for the ownCloud Web interface as specified in the Identity Provider client registration

mode

the mode to search for users in ownCloud - possible values are userid or email

search-attribute

the attribute which is taken from the access token JWT or user info endpoint to identify a user

loginButtonName

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.

autoRedirectOnLoginPage

if set to true, the ownCloud login page will redirect directly to the Identity Provider login without requiring the user to click a button.

redirect-url

the full URL under which the ownCloud OpenID Connect redirect url is reachable (only needed in special setups)

insecure

if set to true, no ssl verification will take place when connecting to the Identity Provider (DON’T use this in production)

scopes

depending on the setup and needs of the Identity Provider, the list of required scopes is entered here

provider-params

additional configuration depending on the Identity Provider can be entered here (usually only necessary if the Identity Provider does not support service discovery)

auth-params

additional parameters which are sent to the Identity Provider during the auth requests

use-token-introspection-endpoint

if set to true, the token introspection endpoint is used to verify a given access token (only needed if the access token is not a JWT)

token-introspection-endpoint-client-id

the client id to be used with the token introspection endpoint

token-introspection-endpoint-client-secret

the client secret to be used with the token introspection endpoint

post_logout_redirect_uri

a given URL where the Identity Provider should redirect to after logout

allowed-user-backends

use this parameter to limit the users which are allowed to login to a specific user backend like LDAP ('allowed-user-backends' ⇒ ['LDAP'])

use-access-token-payload-for-user-info

if set to true, any user information will be read from the access token. If set to false, the userinfo endpoint is used (requires version >= 1.1.0)

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.

Which client versions support OIDC?

  • Desktop >= 2.7.0

  • Android >= 2.15

  • iOS >= 1.2

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:

  1. Make sure you have a working OIDC configuration based on the above sections

  2. Enable the OpenID Connect App

  3. 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:

  1. Make sure you have a working configuration based on the above sections

  2. Enable the OpenID Connect App (while having the OAuth2 App still enabled)

  3. 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.

Migrate web login (and client login) from SAML to OIDC

If you are using SAML/SSO, a migration to OIDC depends on your Identity Provider and is not straight forward. Please get in touch with ownCloud Consulting to plan the migration.