NextCloud
=========

|image0|

Presentation
------------

`NextCloud <https://nextcloud.com/>`__ is a fork of Owncloud, suite of
client-server software for creating file hosting services and using
them.

This documentation explains how to interconnect LemonLDAP::NG and
NextCloud using Open ID Connect or SAML 2.0 protocol.

OpenID Connect
--------------

Requirements
~~~~~~~~~~~~

Your LemonLDAP::NG server must be configured as OpenID Connect provider.

Your NextCloud server must be able to join directly the LemonLDAP::NG server.
It using SSL, be sure that certificate of LL::NG portal is trusted on NextCloud server.

LemonLDAP::NG
~~~~~~~~~~~~~

Create a new OpenID Connect RP with these settings:

* Client ID: generate a value
* Client Secret: generate a value
* Login redirection URL: https://nextcloud.example.com/index.php/apps/oidc_login/oidc
* Attributes: at least ``email`` and ``name``
* User attribute: you must set here the identifier that is already used by NextCloud (if you already plugged NextCloud to your LDAP directory).
  It can be ``entryUUID`` for OpenLDAP or ``objectGUID`` for AD. If this is not correctly configured, a new account will be created instead
  of using the existing account.

You can also share groups trough OpenID Connect. In this case, create a ``groups`` claim.

Another optional claim is a boolean to let NextCloud know if user is admin or not. You can easily create a macro for this.

NextCloud
~~~~~~~~~

Install and enable `"OpenID Connect Login" plugin <https://apps.nextcloud.com/apps/oidc_login>`__.

In your ``config.php``, configure OIDC parameters:

.. code-block:: php

  'oidc_login_hide_password_form' => true,
  'oidc_login_auto_redirect' => true,
  'oidc_login_redir_fallback' => false,
  'oidc_login_provider_url' => 'https://auth.example.com',
  'oidc_login_tls_verify' => true,
  'oidc_login_client_id' => 'clientid',
  'oidc_login_client_secret' => 'clientsecret',
  'oidc_login_disable_registration' => false,
  'oidc_login_use_id_token' => false,
  'oidc_login_attributes' =>
    array (
    'id' => 'sub',
    'name' => 'name',
    'mail' => 'email',
  ),
  'oidc_login_scope' => 'openid profile email',
  'oidc_login_logout_url' => 'https://auth.example.com',


For advanced conifguration, with groups and admin claims:

.. code-block:: php

  'oidc_login_attributes' =>
    array (
    'id' => 'sub',
    'name' => 'name',
    'mail' => 'email',
    'groups' => 'groups',
    'is_admin' => 'nextcloud_admin',
  ),
  'oidc_create_groups' => true,


SAML
----

Requirements
~~~~~~~~~~~~

Make sure you have :doc:`set up LemonLDAP::NG a SAML IDP <../samlservice>`

.. warning::
   Nextcloud requires your public SAML Signature key to be in `BEGIN CERTIFICATE`
   format, if this is not the case, you need to :ref:`convert your SAML key to
   a certificate<samlservice-convert-certificate>`. Note that recent versions of 
   LL:NG are already configured to use certificates instead public key.

.. _nextcloud-1:

NextCloud
~~~~~~~~~

.. tip::

    If your NextCloud is behind a proxy (thus having a private
    IP), metadata generated by NextCloud won't work.

    Consider changing the configuration of NextCloud to force the domain and the protocol, in
    **$nextcloudrootwww/config/config.php**, add the following:

    .. code:: php

       'overwritehost' => 'nextcloud.example.com',
       'overwriteprotocol' => 'https',

Enable the `"SAML authentication" plugin <https://apps.nextcloud.com/apps/user_saml>`__.

Create Certificate of Service Provider for Nextcloud
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You will need private key and public key within a certificate to identify your SP in LL:NG IDP.

Select a host with a secure filesystem as a secure random source since private keys are generated.

To create a private key and self-sign a certificate for its public key please adapt to your country/state.

It is recommended to use nextcloud hostname for Common Name.

::

   certname=nextcloud_saml
   openssl req -new -newkey rsa:4096 -keyout $certname.key -nodes -out $certname.pem -x509 -days 3650

   Country Name (2 letter code) [AU]:BTN
   State or Province Name (full name) [Some-State]:North
   Locality Name (eg, city) []:Thimphou
   Organization Name (eg, company) [Internet Widgits Pty Ltd]:NGO
   Organizational Unit Name (eg, section) []:
   Common Name (e.g. server FQDN or YOUR name) []:nextcloud.example.com
   Email Address []:

Please note that once you have copied those in following process it is recommended to remove private
key file from your system.

Configure Service provider within Nextcloud
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

   Administration -> SSO & SAML authentication

You will find the following fields:

-  **Allow the use of multiple user back-ends (e.g. LDAP)**
   Activate it during configuration, remove it later only once a saml
   user with administration rights can login.

-  **Attribute to map the UID to**: Identity attribute provided by your
   LL:NG that will be used as UID in NextCloud.
-  **Optional display name of the identity provider**: choose a name
   meaningfull to identify this nextcloud app without spaces to use
   it in LL:NG too.
-  **Service Provider Data**:

   - **Name ID format**: select Email Address
   - **X509 certificate of Service provider**: a Certificate you have
     created previously for this purpose
   - **Private key of the Service provider**: private key corresponding
     to public key within certificate of Service provider.
-  **Identity Provider Data**:

   -  **Identifier of the IdP entity**: SAML Metadata URL of your LL:NG
   -  **URL Target of the IdP where the SP will send the Authentication
      Request Message**: SingleSignOn URL of your LL:NG
   -  **URL Location of the IdP where the SP will send the SLO
      Request**: SingleLogOut URL of your LL:NG
   -  **Public X.509 certificate of the IdP**: Certificate of your LL:NG

Your fields should look like this: |image3|

Recent versions of LL:NG are already configured to use Certificates
instead public key so you can obtain pem encoded certificate directly
by Copy/Paste of certificate field in the "Public X.509 certificate of
the IdP" field of your NextCloud.

You can now download your metadata xml file.


LL:NG, SAML 2.0 Service Provider configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

We now have to define a service provider (e.g our nextcloud) in LL:NG.

Go to "SAML service providers", click on "Add SAML SP" and name it as
you want (example : 'NextCloud') (was 'NGOSSO' in previous screenshoot)

In the new subtree 'NextCloud', open 'Metadata' and paste the content of
your previously downloaded file (or upload the file)

|image4|

Now go in "Exported attributes" and add, at least, the 'uid'

|image5|

You might need to add 'mail' to fill expected NameID from NextCloud or
to configure explicit 'uid' NameID mapping in **Force NameID session key**.

Don't forget to save your configuration.

You are now good to go, and you can add the application in
:doc:`your menu<../portalmenu>` and
:doc:`your virtual hosts<../configvhost>`.

.. |image0| image:: /applications/nextcloud-logo.png
   :class: align-center
.. |image1| image:: /applications/nextcloud_saml_activation.png
   :class: align-center
.. |image2| image:: /applications/nextcloud_certificate_keys.png
   :class: align-center
.. |image3| image:: /applications/nextcloud_saml_configuration.png
   :class: align-center
.. |image4| image:: /applications/nextcloud_service_metadata.png
   :class: align-center
.. |image5| image:: /applications/nextcloud_service_exportedattributes.png
   :class: align-center
.. |image6| image:: /applications/nextcloud_certificate_keys.png
   :class: align-center
