OpenID Connect (OIDC)

Introduction

OpenID Connect is an open standard for single sign-on, identity and access management. With ownCloud it can be used for user authentication and client authorization against an external identity provider(IdP).

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.

ownCloud only supports one configured identity provider which is then valid for all requests.

Click on the OAuth code flow sequence diagram link to get more details on the flow sequence.

Supported Identity Providers

ownCloud Server can work with identity providers (IdP) 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.

The currently supported products are

(1) …​ Note that ADFS does not support client-secrets that contain an _ (underscore).

Please get in touch with ownCloud Consulting if you need help with a specific identity provider product.

Prerequisites

Setting up ownCloud Server to work with OpenID Connect requires a couple of components to work together:

Save Settings in the Database

If you run a clustered setup, the following method configuring the OpenID Connect app is preferred, because it is stateless. The app checks for settings in the database first. If none are found, it falls back to the settings stored in config.php. The settings are stored as a JSON formatted string with the following keys and values:

Key Value

appid

'openidconnect'

configkey

'openid-connect'

configvalue

JSON-String

If a malformed JSON string is found, an error is logged. The key→value pairs are the same as when storing them to the config.php file. This task has to be done by invoking an occ command, see the following example. Use the occ commands config:app:get to view the current setting or config:app:delete to delete it. See the Config Command Set for more details.

sudo -u www-data ./occ config:app:set \
    openidconnect \
    openid-connect \
    --value='{"provider-url":"https:\/\/idp.example.net","client-id":"fc9b5c78-ec73-47bf-befc-59d4fe780f6f","client-secret":"e3e5b04a-3c3c-4f4d-b16c-2a6e9fdd3cd1","loginButtonName":"Login via OpenId Connect"}'
Only set either the database or the config.php keys but not both for the OpenID Connect app.

Set Up Service Discovery

  1. Webserver Service Discovery Information

    In order to allow the ownCloud Clients (Desktop/Android/iOS) to make use of OpenID Connect, the webserver serving ownCloud Server needs to provide service discovery information under the following static path:

    https://cloud.example.com/.well-known/openid-configuration

  2. App Service Discovery Information

    When enabled, the OpenID Connect App provides the service discovery information on the endpoint:

    https://cloud.example.com/index.php/apps/openidconnect/config

  3. Webserver Rewrite Rule

    To make the endpoint available under the static service discovery path, it is recommended to put a RewriteRule in place using in the VirtualHost section. The Apache module rewrite must be enabled, and if SSL is used, also the modules proxy, proxy_http and proxy_connect:

    RewriteEngine on
RewriteRule "^/.well-known/openid-configuration" "/index.php/apps/openidconnect/config" [P]
SSLProxyEngine On #This can be omitted if no SSL is used
    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.
    If you use the .htaccess file in the ownCloud web root, you have to manually add that rewrite rule again after any ownCloud upgrade.

  4. Once service discovery is available as described above, the ownCloud clients will attempt to connect via OpenID Connect.

General Example Setup

All IdPs have their own setup, but often share common ways of configuring things. Although not identical, the Kopano Konnect example may be a good starting point for the specific configuration of your setup. As Microsoft with Azure AD is different, it has its own example section.

Example Setup Using Kopano Konnect

Follow this link to see Example Setup Using Kopano Konnect.

Example Setup Using Microsoft Azure AD

Follow this link to see Example Setup Using Microsoft Azure AD.

Example Setup Using OneLogin

Follow this link to see Example Setup Using OneLogin.

ownCloud Desktop and Mobile Clients

ownCloud desktop and mobile clients detect whether OIDC is available (service discovery) and use this login method when a new account is created.

The desktop and mobile apps (clients) have a default client ID and secret hard-coded, which are used for ownCloud’s oauth2 app. When using Kopano as IdP, it does not pre-define a client ID and secret. You can use the default ones of the client to configure Kopano properly. With some IdPs like MS-Azure, these and other required parameters come from the IdP and must be coded into the client. Note that each IdP has different requirements. Get in touch with ownCloud for a branding subscription to customize the clients according to your needs.

Client Support for OIDC

Following owncloud clients support OIDC
ownCloud Client Release with OIDC support

Desktop

>= 2.7.0

Android

>= 2.15

iOS

>= 1.2

Client IDs, Secrets and Redirect URIs

All IdPs can use ownCloud’s default client IDs, secrets and redirect URIs with the exception of Microsoft Azure AD, which uses a different approach. Here is the data necessary for the configuration.

Client ID

Source Key

Server/Web

as specified in config.php

Desktop

xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69

Android

e4rAsNUSIUs0lF4nbv9FmCeUkTlV9GdgTLDH1b5uie7syb90SzEVrbN7HIpmWJeD

iOS

mxd5OQDk6es5LzOzRvidJNfXLUZS2oN3oUFeXPP8LpPrhx3UroJFduGEYIBOxkY1

Client Secret

Source Key

Server/Web

as specified in config.php

Desktop

UBntmLjC2yYCeHwsyj73Uwo9TAaecAetRwMw0xYcvNL9yRdLSUi0hUAHfvCHFeFh

Android

dInFYGV33xKzhbRmpqQltYNdfLdJIfJ9L5ISoKhNoT9qZftpdWSP71VrpGR9pmoD

iOS

KFeFWWEZO9TkisIQzR3fo7hfiMXlOpaqP8CFuTbSHzV1TUuGECglPxpiVKJfOXIx

Redirect URIs

Source Redirect URI 1

Desktop ≤ 2.8

http://localhost

Desktop ≥ 2.9

http://127.0.0.1

Android

oc://android.owncloud.com

iOS

oc://ios.owncloud.com

(1) See the following note when using Microsoft Azure AD and 127.0.0.1 as redirect URI.

Default Scope and Prompt Parameters

ownCloud desktop and mobile apps come with default scope and prompt parameters. These parameters can be modified in custom branded builds. See the OIDC Authentication Request specs for more details about the parameters.

Parameter Default value

scope

openid offline_access email profile

prompt

select_account consent
(for Android you need app version 4.0+)

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.