Child pages
  • Requirements and Howto for UCS-Crust-App
Skip to end of metadata
Go to start of metadata

The UCS app for Crust was tested extensively with different UCS system configurations and it should be possible to install it on most systems.

However, there are some requirements to be met in order to successfully use the application. Please make sure to understand these requirements and their implications before using the app.

1.1. DNS Settings / Routing

The following three vhosts are created in the UCS Apache2 webserver, they are registered in the UCS DNS service during the installation of the app:

  • didmos2-auth.{hostname}.{domainname}
  • crust.{hostname}.{domainname}
  • api.crust.{hostname}.{domainname}

These domain names will be referred to at multiple points in the following text. Normally, {hostname}.{domainname} would be the domain name under which to access the web interface of your UCS installation.

If the UCS DNS server is used for domain name resolution, this should work without further adjustments. Otherwise an external DNS server must be configured accordingly to forward these three domains to the UCS machine running the app.

For testing purposes, the local /etc/hosts file can be used as follows:

{IP of UCS machine} didmos2-auth.{hostname}.{domainname} crust.{hostname}.{domainname} api.crust.{hostname}.{domainname}

# Example:
# 37.24.13.235 crust.ucs.ucs-crust-demo.daasi.de api.crust.ucs.ucs-crust-demo.daasi.de didmos2-auth.ucs.ucs-crust-demo.daasi.de

1.2. SSL Certificates

During installation, SSL certificates are created by UCS and signed with the UCS CA. These certificates must be trusted by the browser, which is used to access the Crust app. 

If the UCS CA is trusted by your browser, this should work right away. If it does not work, you can try to add the UCS CA to the list of trusted certificates in your browser.

For testing purposes, it is also possible to use untrusted certificates and whitelist them manually in the browser. In order for this to work, you must access all three subdomains (see above) individually and whitelist the certificate. Only then all components can successfully communicate through your browser.

Of course, it is also possible to use your own certificates. This can be configured with UCS system settings for each vhost individually like so:

apache2/vhosts/api.crust.ucs.ucs-crust-demo.daasi.de/443/ssl/ca: /etc/univention/ssl/ucsCA/CAcert.pem
apache2/vhosts/api.crust.ucs.ucs-crust-demo.daasi.de/443/ssl/certificate: /etc/univention/ssl/*.ucs.ucs-crust-demo.daasi.de/cert.pem
apache2/vhosts/api.crust.ucs.ucs-crust-demo.daasi.de/443/ssl/key: /etc/univention/ssl/*.ucs.ucs-crust-demo.daasi.de/private.key

Ultimately, these settings are used to populate the Apache2 vhosts settings in /etc/apache2/sites-available/univention-vhosts.conf, which can be edited manually, but might be changed by UCS automatically. Hence, the changes are preferrably applied using the UCS Configuration management. Further examples for this process are included below in the chapter on Let's Encrypt.

1.2.1. Let's Encrypt

On public servers the UCS Let's Encrypt extension can be used to create valid SSL certificates for the server. Currently, the process to acquire certificates with this extension requires various manual changes and is not officially supported but might still be a viable alternative for public UCS setups.

Firstly, it is necessary to add an additional vhost to /etc/apache2/sites-available/univention-vhosts.conf in order to enable the acme challenge done by Let's Encrypt. For this, the respective config template in UCS can be changed in  /etc/univention/templates/files/etc/apache2/sites-available/univention-vhosts.conf like so (the ServerName and ServerAlias  mst be changed to the correct DNS values):

[...]
''')
        if configRegistry.get(vhost_key + 'ssl/certificate'):
                print('</IfModule>')
        print('')

# NEW CONFIG BELOW

print('''
<VirtualHost *:80>
        ServerName crust.{hostname}.{domainname}
        ServerAlias didmos2-auth.{hostname}.{domainname} api.crust.{hostname}.{domainname}

        DocumentRoot /var/www/html

        Alias /.well-known/acme-challenge/ /var/www/.well-known/acme-challenge/
        <Directory /var/www/.well-known/acme-challenge/>
                   AllowOverride None
                   Options -Indexes
                   Require all granted
        </Directory>
</VirtualHost>
''')

# END OF NEW CONFIG

@!@

Afterwards, Apache2 can be reloaded and restarted as follows:

univention-config-registry commit /etc/apache2/sites-available/univention-vhosts.conf
apachectl configtest
systemctl restart apache2

As a next step the certificates can be acquired via the UCS web interface in the Let's Encrypt app settings (Installed Applications → Let's Encrypt → App Settings). In the "Domains" form field all domains must be added, separated by space. This process requires the server to be respsonsive to all subdomains via a public DNS. Otherwise Let's Encrypt won't be able to successfully acquire the certificates.

In addition to the three domains for the Crust app, it is also recommended to add the 'ucs-sso' domain for the UCS SAML2 IDP, if it has not already been added.

The full list might look like this:

  • {hostname}.{domainname}
  • didmos2-auth.{hostname}.{domainname}
  • crust.{hostname}.{domainname}
  • api.crust.{hostname}.{domainname}
  • ucs-sso.{domainname}

Please see the following image for a general example:

During this process Let's Encrypt might automatically create a new Apache2 config, which conflicts with the config generated by the Crust app. If no other apps using Let's Encrypt are installed you can safely disable the new Vhosts:

a2dissite univention-letsencrypt
systemctl reload apache2

Finally the certificates for all Vhosts can be changed in the UCS webinterface under System → Univention Configuration Registry. The following changes are necessary:

UCR-Variable apache2/vhosts/api.crust.ucs.ucs-crust-demo.daasi.de/443/ssl/ca
UCR-Variable apache2/vhosts/crust.ucs.ucs-crust-demo.daasi.de/443/ssl/ca
UCR-Variable apache2/vhosts/didmos2-auth.ucs.ucs-crust-demo.daasi.de/443/ssl/ca
Old value: /etc/univention/ssl/ucsCA/CAcert.pem ? New value: <empty>

UCR-Variable apache2/vhosts/api.crust.ucs.ucs-crust-demo.daasi.de/443/ssl/certificate
UCR-Variable apache2/vhosts/crust.ucs.ucs-crust-demo.daasi.de/443/ssl/certificate
UCR-Variable apache2/vhosts/didmos2-auth.ucs.ucs-crust-demo.daasi.de/443/ssl/certificate
Old value: /etc/univention/ssl/*.ucs.ucs-crust-demo.daasi.de/cert.pem ? New value: /etc/univention/letsencrypt/signed_chain.crt

UCR-Variable apache2/vhosts/api.crust.ucs.ucs-crust-demo.daasi.de/443/ssl/key
UCR-Variable apache2/vhosts/crust.ucs.ucs-crust-demo.daasi.de/443/ssl/key
UCR-Variable apache2/vhosts/didmos2-auth.ucs.ucs-crust-demo.daasi.de/443/ssl/key
Old value: /etc/univention/ssl/*.ucs.ucs-crust-demo.daasi.de/private.key ? New value: /etc/univention/letsencrypt/domain.key

# For UCS SAML2 IDP:
UCR-Variable saml/apache2/ssl/certificate
Old value: <empty> ? New value: /etc/univention/letsencrypt/signed_chain.crt
UCR-Variable saml/apache2/ssl/key
Old value: <empty> ? New value: /etc/univention/letsencrypt/domain.key

These changes can now be reloaded with:

univention-config-registry commit /etc/apache2/sites-available/univention-vhosts.conf
univention-config-registry commit /etc/apache2/sites-available/univention-saml.conf
apachectl configtest
systemctl restart apache2

1.3. User Configuration

UCS users do not require a separate account to access the Crust app as they can use the default UCS SAML2 IDP, which comes with any standard UCS installation.

If the UCS SAML2 IDP is working correctly, all required configuration should be ready after installing the Crust app. Please note, that the requirements regarding DNS and SSL certificates also apply to the UCS SAML2 IDP, which is installed by default on:

  • ucs-sso.{domainname} (e.g. ucs-sso.ucs-demo.daasi.de)

The above example for Let's Encrypt includes instructions for the IDP and might also be helpful in other scenarios.

1.3.1. User Configuration

Currently, in UCS all users, who are supposed to use the Crust app must be authorised manually AND have a "Primary E-Mail Address" attribute.

This can be configured in the UCS webinterface under Users → Users.

The email can be configured under the tab "General" as follows:

Enabling the Crust app means enabling permissions to use the SAML2 IDP for logging into the Crust app. This can be done under the tab "Account" at the bottom of the page and might look like this (click on "Add" to add a new permission):

1.4. Validate the Installation

Make sure you have understood the requirements for the following three areas:

  1. DNS server configuration (either by using the UCS DNS server or by configuring a dedicated external DNS server or  by using a local /etc/hosts configuration)
  2. SSL certificate configuration (either by whitelisting the UCS CA certificates created during installation or  by using your own certificates or  by using Let's Encrypt certificates on a public machine)
  3. User configuration (the user you want to use the Crust app with must have a Primary email address and the Crust SAML2 connection enabled)

With this in mind you should be able to access https://crust.{hostname}.{domainname}. After clicking on the "Crust-didmos" icon you should be redirected to the UCS SAML2 IDP where you are able to enter the appropriate credentials, consequently you will be redirected back to the Crust app and logged in.

1.5. Further Debugging

If access to the app is not possible at all, you should first verify that the DNS configuration is correct. Further steps include looking at the state of the docker containers running on the UCS machine. The output should look like this:

root@ucs:/etc/apache2/sites-enabled# docker ps
CONTAINER ID        IMAGE                                                     COMMAND                  CREATED             STATUS              PORTS                   NAMES
07da9a0136cd        docker.software-univention.de/crust-webapp:2019.12.01     "/entrypoint.sh"         2 hours ago         Up 2 hours          0.0.0.0:9201->80/tcp    crust_webapp_1
c2b22f7b04cb        docker.software-univention.de/crust-server:2019.12.01     "/bin/crust-server s..."   2 hours ago         Up 2 hours          0.0.0.0:9222->80/tcp    crust_server_1
dc3ea63f9edf        docker.software-univention.de/crust-satosa:2019.12.01     "/entrypoint.sh"         2 hours ago         Up 2 hours          0.0.0.0:9211->80/tcp    crust_satosa_1
4b8d25b332ff        docker.software-univention.de/crust-ldap:2019.12.01       "/entrypoint.sh"         2 hours ago         Up 2 hours          389/tcp                 crust_ldap_1
d98259dff545        docker.software-univention.de/crust-mongo:2019.12.01      "docker-entrypoint.s..."   2 hours ago         Up 2 hours          27017/tcp               crust-didmos2-mongo
217febe15545        docker.software-univention.de/crust-db:2019.12.01         "/docker-entrypoint...."   2 hours ago         Up 2 hours          3306/tcp, 33060/tcp     crust_db_1
fb05394ad4bd        docker.software-univention.de/crust-corredor:2019.12.01   "docker-entrypoint.s..."   2 hours ago         Up 2 hours          80/tcp                  crust_corredor_1

If one of these containers is missing or has a status other then "Up x hours", you can try to find out what went wrong with inspecting the docker logs. This should also work if one or more containers do not start at all by using the name as above or by determining the correct name in your system by using docker ps --all (which also shows exited or failed containers):

# docker logs {name}
# e.g.:
docker logs crust_server_1



  • No labels