openCloud

This integration guide is community supported. It's not guaranteed to be complete, accurate, or up-to-date. It's likely that if this integration guide does not work for you that changes occurred with a third-party application.

Important Note: This documentation is version specific. Make sure you check the section outlining the tested versions.

Important Note: We always recommend users read the third-party documentation as part of the integration process to ensure configuration elements matches their needs. As such the See Also section is likely to have important links.

Important Note: If you find an error in this documentation please make a Pull Request, start a Discussion, or contact us on a Chat Room.

Tested Versions

Before You Begin

Important Reading

This section contains important elements that you should carefully consider before configuration of an OpenID Connect 1.0 Registered Client.

Common Notes

The OpenID Connect 1.0 client_id parameter:
1. This must be a unique value for every client.
2. The value used in this guide is merely for readability and demonstration purposes and you should not use this value in production and should instead utilize the How do I generate a client identifier or client secret? FAQ. We recommend 64 random characters but you can use any arbitrary value that meets the other criteria.
3. This must only contain RFC3986 Unreserved Characters.
4. This must be no more than 100 characters in length.
The OpenID Connect 1.0 client_secret parameter:
1. The value used in this guide is merely for demonstration purposes and you should absolutely not use this value in production and should instead utilize the How do I generate a client identifier or client secret? FAQ.
2. This string may be stored as plaintext in the Authelia configuration but this behavior is deprecated and is not guaranteed to be supported in the future. See the Plaintext guide for more information.
3. When the secret is stored in hashed form in the Authelia configuration (heavily recommended), the cost of hashing can, if too great, cause timeouts for clients. See the Tuning the work factors guide for more information.
The configuration example for Authelia:
1. Only contains an example configuration for the client registration and you MUST also configure the required elements from the OpenID Connect 1.0 Provider Configuration guide.
2. Only contains a small portion of all of the available options for a registered client and users may wish to configure portions that are not part of this guide or configure them differently, as such it’s important to both familiarize yourself with the other options available and the effect of each of the options configured in this section by looking at the OpenID Connect 1.0 Clients Configuration guide.

Assumptions

This example makes the following assumptions:

Application Root URL: https://opencloud.example.com
Authelia Root URL: https://auth.example.com
Client ID:
- Web Application: opencloud
- Android App: opencloud-android
- iOS App: opencloud-ios
- Desktop client: opencloud-desktop

Some of the values presented in this guide can automatically be replaced with documentation variables.

Configuration

Authelia

The following YAML configuration is an example Authelia client configuration for use with openCloud which will operate with the application example:

identity_providers:
  oidc:
    clients:
      - client_id: 'opencloud'
        client_name: 'openCloud'
        public: true
        authorization_policy: 'two_factor'
        require_pkce: true
        pkce_challenge_method: 'S256'
        scopes:
          - 'openid'
          - 'offline_access'
          - 'groups'
          - 'profile'
          - 'email'
        redirect_uris:
          - 'https://opencloud.example.com/'
          - 'https://opencloud.example.com/oidc-callback.html'
          - 'https://opencloud.example.com/oidc-silent-redirect.html'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
          - 'refresh_token'
        access_token_signed_response_alg: 'RS256'
        userinfo_signed_response_alg: 'none'
        token_endpoint_auth_method: 'none'
      - client_id: 'opencloud-android'
        client_name: 'openCloud'
        public: true
        authorization_policy: 'two_factor'
        require_pkce: true
        pkce_challenge_method: 'S256'
        redirect_uris:
          - 'oc://android.opencloud.eu'
        scopes:
          - 'openid'
          - 'offline_access'
          - 'groups'
          - 'profile'
          - 'email'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
          - 'refresh_token'
        access_token_signed_response_alg: 'RS256'
        userinfo_signed_response_alg: 'none'
        token_endpoint_auth_method: 'none'
      - client_id: 'opencloud-desktop'
        client_name: 'openCloud'
        public: true
        authorization_policy: 'two_factor'
        require_pkce: true
        pkce_challenge_method: 'S256'
        scopes:
          - 'openid'
          - 'offline_access'
          - 'groups'
          - 'profile'
          - 'email'
        redirect_uris:
          - 'http://127.0.0.1'
          - 'http://localhost'
        response_types:
          - 'code'
        grant_types:
          - 'authorization_code'
          - 'refresh_token'
        access_token_signed_response_alg: 'RS256'
        userinfo_signed_response_alg: 'none'
        token_endpoint_auth_method: 'none'
      - client_id: 'opencloud-ios'
        client_name: 'openCloud'
        public: true
        authorization_policy: 'two_factor'
        require_pkce: true
        pkce_challenge_method: 'S256'
        redirect_uris:
          - 'oc://ios.opencloud.eu'
          - 'oc.ios://ios.opencloud.eu'
        scopes:
          - 'openid'
          - 'offline_access'
          - 'groups'
          - 'profile'
          - 'email'
        grant_types:
          - 'authorization_code'
          - 'refresh_token'
        access_token_signed_response_alg: 'RS256'
        userinfo_signed_response_alg: 'none'
        token_endpoint_auth_method: 'none'

Application

To configure openCloud there is one method, using the Environment Variables.

Limitations

Important Note

All limitations are limitations due to the development lifecycle of the application and are not related to Authelia.

Important Note

The desktop client integration is currently not production ready.

The current implementation is intended for one-time use cases, such as migrating files. It should not be considered a stable long-term desktop client setup until the WebFinger integration is completed.

The desktop client WebFinger integration is currently incomplete (pull request https://github.com/opencloud-eu/desktop/pull/847).
Some additional customizations may be needed as noted below.

The groups scope must be manually added to the authorization link when setting up the desktop client.

Example:

https://auth.example.com/api/oidc/authorization?response_type=code&client_id=<client_id>&redirect_uri=<redirect_uri>&code_challenge=<code_challenge>&code_challenge_method=S256&scope=<scope>&prompt=<prompt>&state=<state>

The default scope is:

scope=openid%20offline_access%20email%20profile

Add groups%20 manually at the beginning of the scope:

scope=groups%20openid%20offline_access%20email%20profile

Environment Variables

To configure openCloud to utilize Authelia as an OpenID Connect 1.0 Provider, use the following environment variables:

Standard

OC_OIDC_ISSUER="https://auth.example.com"
PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD="jwt"
PROXY_OIDC_REWRITE_WELLKNOWN="true"
PROXY_AUTOPROVISION_ACCOUNTS="true"
PROXY_AUTOPROVISION_CLAIM_USERNAME="preferred_username"
PROXY_AUTOPROVISION_CLAIM_EMAIL="email"
PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME="name"
PROXY_AUTOPROVISION_CLAIM_GROUPS="groups"
PROXY_CSP_CONFIG_FILE_LOCATION="/etc/opencloud/csp.yaml"
WEBFINGER_WEB_OIDC_CLIENT_ID="opencloud"
WEBFINGER_WEB_OIDC_CLIENT_SCOPES="openid profile email groups offline_access"
WEBFINGER_ANDROID_OIDC_CLIENT_ID="opencloud-android"
WEBFINGER_ANDROID_OIDC_CLIENT_SCOPES="openid profile email groups offline_access"
WEBFINGER_IOS_OIDC_CLIENT_ID="opencloud-ios"
WEBFINGER_IOS_OIDC_CLIENT_SCOPES="openid profile email groups offline_access"
WEBFINGER_DESKTOP_OIDC_CLIENT_ID="opencloud-desktop"
WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES="openid profile email groups offline_access"
OC_EXCLUDE_RUN_SERVICES="idp"
PROXY_ROLE_ASSIGNMENT_DRIVER="oidc"
GRAPH_ASSIGN_DEFAULT_USER_ROLE="false"

Docker Compose

services:
  openCloud:
    environment:
      OC_OIDC_ISSUER: 'https://auth.example.com'
      PROXY_OIDC_ACCESS_TOKEN_VERIFY_METHOD: 'jwt'
      PROXY_OIDC_REWRITE_WELLKNOWN: 'true'
      PROXY_AUTOPROVISION_ACCOUNTS: 'true'
      PROXY_AUTOPROVISION_CLAIM_USERNAME: 'preferred_username'
      PROXY_AUTOPROVISION_CLAIM_EMAIL: 'email'
      PROXY_AUTOPROVISION_CLAIM_DISPLAYNAME: 'name'
      PROXY_AUTOPROVISION_CLAIM_GROUPS: 'groups'
      PROXY_CSP_CONFIG_FILE_LOCATION: '/etc/opencloud/csp.yaml'
      WEBFINGER_WEB_OIDC_CLIENT_ID: 'opencloud'
      WEBFINGER_WEB_OIDC_CLIENT_SCOPES: 'openid profile email groups offline_access'
      WEBFINGER_ANDROID_OIDC_CLIENT_ID: 'opencloud-android'
      WEBFINGER_ANDROID_OIDC_CLIENT_SCOPES: 'openid profile email groups offline_access'
      WEBFINGER_IOS_OIDC_CLIENT_ID: 'opencloud-ios'
      WEBFINGER_IOS_OIDC_CLIENT_SCOPES: 'openid profile email groups offline_access'
      WEBFINGER_DESKTOP_OIDC_CLIENT_ID: 'opencloud-desktop'
      WEBFINGER_DESKTOP_OIDC_CLIENT_SCOPES: 'openid profile email groups offline_access'
      OC_EXCLUDE_RUN_SERVICES: 'idp'
      PROXY_ROLE_ASSIGNMENT_DRIVER: 'oidc'
      GRAPH_ASSIGN_DEFAULT_USER_ROLE: 'false'

Files

The following files must be configured.

Content Security Policy

Create the CSP configuration file and save it next to opencloud.yaml:

directives:
  child-src:
    - '''self'''
  connect-src:
    - '''self'''
    - 'blob:'
    - 'https://${COMPANION_DOMAIN|companion.opencloud.test}${TRAEFIK_PORT_HTTPS}/'
    - 'wss://${COMPANION_DOMAIN|companion.opencloud.test}${TRAEFIK_PORT_HTTPS}/'
    - 'https://auth.example.com'
    - 'https://raw.githubusercontent.com/opencloud-eu/awesome-apps/'
    - 'https://update.opencloud.eu/'
    - 'https://tile.openstreetmap.org/'
  default-src:
    - '''none'''
  font-src:
    - '''self'''
  frame-ancestors:
    - '''self'''
  frame-src:
    - '''self'''
    - 'blob:'
    - 'https://embed.diagrams.net/'
    - 'https://${COLLABORA_DOMAIN|collabora.opencloud.test}${TRAEFIK_PORT_HTTPS}/'
    - 'https://${EURO_OFFICE_DOMAIN|euro-office.opencloud.test}${TRAEFIK_PORT_HTTPS}/'
    - 'https://docs.opencloud.eu'
    - 'https://auth.example.com'
  img-src:
    - '''self'''
    - 'data:'
    - 'blob:'
    - 'https://raw.githubusercontent.com/opencloud-eu/awesome-apps/'
    - 'https://tile.openstreetmap.org/'
    - 'https://${COLLABORA_DOMAIN|collabora.opencloud.test}${TRAEFIK_PORT_HTTPS}/'
    - 'https://${EURO_OFFICE_DOMAIN|euro-office.opencloud.test}${TRAEFIK_PORT_HTTPS}/'
  manifest-src:
    - '''self'''
  media-src:
    - '''self'''
  object-src:
    - '''self'''
    - 'blob:'
  script-src:
    - '''self'''
    - '''unsafe-inline'''
    - 'https://auth.example.com'
  style-src:
    - '''self'''
    - '''unsafe-inline'''
  worker-src:
    - '''self'''
    - 'blob:'

Refer to csp.yaml

Proxy

When using an external IDP, you need to map groups and roles. Create the following file and save it next to opencloud.yaml:

In this example the opencloud-admins Authelia group maps to the admin role in openCloud. This is because of the role_claim value set to groups, and the list of mappings in role_mappings. Examples also exist for the spaceadmin, user, and user-light roles in openCloud.

You should adapt this configuration to your needs.

role_assignment:
    driver: 'oidc'
    oidc_role_mapper:
        role_claim: 'groups'
        role_mapping:
          - role_name: 'admin'
            claim_value: 'opencloud-admins'
          - role_name: 'spaceadmin'
            claim_value: 'opencloud-space-admins'
          - role_name: 'user'
            claim_value: 'opencloud-users'
          - role_name: 'user-light'
            claim_value: 'opencloud-guests'

openCloud

Tested Versions#

Before You Begin#

Common Notes#

Assumptions#

Configuration#

Authelia#

Application#

Limitations#

Environment Variables#

Standard#

Docker Compose#

Files#

Content Security Policy#

Proxy#

See Also#

Tested Versions

Before You Begin

Common Notes

Assumptions

Configuration

Authelia

Application

Limitations

Environment Variables

Standard

Docker Compose

Files

Content Security Policy

Proxy

See Also