Skip to content

ESign

Digitally sign one or multiple PDF documents with a freely positioned seal.

Visit ESign Demo

The application has two modes for signing

  • Advanced signatures: The user signs on behalf of an organization, like a University, by being authorized to do so.
  • Qualified signatures: The users signs personally, verifying their identity during the process via a mobile phone.

Signature verification is currently handled by referring to https://www.rtr.at/TKP/was_wir_tun/vertrauensdienste/Signatur/signaturpruefung/Pruefung.de.html

Screenshot

esign

Example tech stack

  • A Keycloak server
  • A LAMP server (Linux, Apache, MySQL/MariaDB, PHP>=8.1), but MySQL/MariaDB is not needed in this case
    • The dependency manager for PHP Composer 2 also needs to be installed
    • git >= 2.25 needs to be installed
    • In case that the frontend will also be hosted on the same server, then npm needs to be installed too
    • Several PHP extensions need to be present: ext-ctype, ext-dom, ext-fileinfo, ext-filter, ext-json, ext-ldap, ext-libxml, ext-mbstring, ext-mysql, ext-openssl, ext-pcre, ext-reflection, ext-simplexml, ext-soap, ext-spl, ext-tokenizer, ext-xml, ext-redis, ext-curl, ext-gmp
  • Domains (or sub-domains) along with the needed TLS/SSL certificates for the Relay API web server, the frontend web server and the Keycloak server

Installation

graph TB frontend(ESign App) --> relay(Relay API Gateway) frontend --> keycloak[Keycloak Server] relay --> esign-bundle[[ESign Bundle]] relay --> frontend-bundle[[Frontend Bundle]] relay --> oidc-bundle[[OIDC Bundle]] esign-bundle --> pdf-as[PDF-AS] esign-bundle --> moa-spss[MOA-SPSS] esign-bundle --> core-bundle[[Core Bundle]] frontend-bundle --> core-bundle oidc-bundle --> local-system("University systems (e.g. LDAP)") oidc-bundle --> keycloak keycloak --> local-system pdf-as --> a-trust[A-Trust] moa-spss --> a-trust style frontend fill:#d0d0ff,stroke:#333,stroke-width:4px

Frontend App

You can install the frontend application with a simple command you can find on ESign frontend installation.

The frontend app currently depends on a default profile being configured in the backend for the qualified signature and a official profile for the advanced signature. This will be made configurable in a future version.

If you want to customize your frontend, please have a look at the theming and individualizing your application guide. There, an detailed description of individualizing your fonts, colors, icons, and other assets is given.

Keycloak Server

You need to install and set up the Open Source Identity and Access Management Keycloak.

Tip

There is small guide about the Keycloak Client Setup.

PDF-AS

For the actual PDF signing you need a PDF-AS server 4.1.5+ by EGIZ.

We provide two pre-configured variants of pdf-as, you need at least one of them depending on your use case:

See the repository README files for how to set them up and configure them.

Relay API

This is a guide on how to set up the Relay API for ESign.

Tip

You can find an example implementation on relay-esign-api.

Screenshot

This is how this example will look like in the end.

esign

PHP Modules and other packages

This should install most of the packages you will need on your webserver (if Apache and PHP are already installed):

# Install packages on Debian/Ubuntu
apt-get -y --no-install-recommends install curl sudo git php-apcu php-apcu-bc \
  php-cli php-curl php-gd php-soap php-json php-mbstring php-mysql php-opcache \
  php-readline php-xml php-intl php-zip php-redis php-fpm php-ldap php-gmp \
  openssl composer

# should show something like "PHP 8.1.x" (or higher)
php -v

# Should show something like "Composer 2.x"
composer -V

# Install Remi's RPM repository for php-redis and PHP 8.1
dnf -y install https://rpms.remirepo.net/enterprise/remi-release-8.rpm

# Install PHP 8.1
dnf -y module install php:remi-8.1

# Install packages on Redhat/CentOS
dnf -y install curl composer php php-apcu php-bcmath php-cli php-curl php-gd \
  php-soap php-json php-mbstring php-mysqlnd php-opcache php-readline php-xml \
  php-intl php-zip php-redis php-fpm php-ldap php-gmp openssl php-pecl-redis5 \
  sudo git

# should show something like "PHP 8.1.x" (or higher)
php -v

# Should show something like "Composer 2.x"
composer -V

Warning

Please make sure you have installed PHP with at least version 8.1, Composer version 2 and Git with at least version 2.25!

Apache Webserver configuration

First you need to enable the Apache Rewrite module so all requests can be redirected to the index.php.

# enable mod rewrite
a2enmod rewrite

In your virtual host configuration you need to allow .htaccess files and set your DocumentRoot to the public directory.

Note that in this example /[VHOST-ROOT]/relay-api will be the path where the PHP application resides.

Warning

You need to replace /[VHOST-ROOT] with the root path of your virtual hosts!

# Allow .htaccess
<Directory /[VHOST-ROOT]/relay-api>
        Options Indexes FollowSymLinks
        AllowOverride All
        Require all granted
</Directory>

# Set DocumentRoot to public directory
<VirtualHost *:80>
    DocumentRoot "/[VHOST-ROOT]/relay-api/public"
    ServerName api.your-domain

    # Other directives here ...
</VirtualHost>

You now can restart your web server with:

sudo service apache2 restart

App and bundle install

We will use the DBP API Server Template as starting point for our implementation.

Tip

Keep in mind that your current user needs to have permissions to create files and directories in the /[VHOST-ROOT] directory for this example.

# You need to replace "/[VHOST-ROOT]" with the root path of your virtual hosts!
# And keep in mind that your current user needs to have permissions to
# create files and directories in the "/[VHOST-ROOT]" directory.
cd /[VHOST-ROOT]

# Install the DBP API Server Template (https://github.com/digital-blueprint/relay-server-template)
# as base Symfony PHP application
# The relay-api/public directory then is the directory to let the webserver point at 
composer create-project dbp/relay-server-template relay-api

# Change to app directory
cd relay-api

# Install the Frontend Bundle (https://github.com/digital-blueprint/relay-frontend-bundle),
# which contains APIs mostly useful for frontend apps.
# It is a required dependency for all DBP frontend apps.
composer require dbp/relay-frontend-bundle

# Install the ESign Bundle (https://github.com/digital-blueprint/relay-esign-bundle),
# which allows you to create permits for the Covid19 certificate evaluation process.
composer require dbp/relay-esign-bundle

Tip

Executing composer check-platform-reqs shows that the required PHP extensions are installed.

OIDC Bundle config

Follow the these steps to configure the OIDC Bundle: Configure the Core Connector OIDC Bundle

ESign Bundle config

You need to Configure the ESign Bundle.

Adapt all PDF_AS_ settings in your .env.

# PDF-AS
PDF_AS_WEB_ADVANCED_URI=https://pdfas-dev.tugraz.at/pdf-as-web
PDF_AS_WEB_QUALIFIED_URI=https://sig-dev.tugraz.at/pdf-as-web
PDF_AS_WEB_QUALIFIED_STATIC_URI=https://sig-dev.tugraz.at/static
PDF_AS_VERIFICATION_ENABLE=false

Health Checks

If you are finished setting up and configuring the API server you can run the builtin health checks to ensure that all external systems are reachable and correctly hooked up.

Simply run the following in the API server directory:

./bin/console dbp:relay:core:check-health

If everything is working it should print something like:

[esign]
  Check if we can reach the pdf-as-web SOAP interface: [SUCCESS]
  Check if we can reach the callback URLs: [SUCCESS]
[core.queue]
  Check if the queue is configured: [SUCCESS]
[core.symfony]
  APP_SECRET should be set: [SUCCESS]
  APP_ENV should be set to 'prod': [SUCCESS]
[core.system]
  Check if DNS is working: [SUCCESS]
  Check if TLS is working: [SUCCESS]

Running in Production

When you are done with setting things up please visit Running in Production to learn how to run the Relay API in production.