# ESign

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

Visit ESign Demo (opens new window)

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.signaturpruefung.gv.at/ (opens new window)

# Screenshot

esign

# Example tech stack

  • A Keycloak (opens new window) server
  • A LAMP server (Linux, Apache, MySQL/MariaDB, PHP>=7.3), but MySQL/MariaDB is not needed in this case
    • The dependency manager for PHP Composer 2 (opens new window) 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

# Frontend App

You can install the frontend application with a simple command you can find on ESign frontend installation (opens new window).

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 (opens new window).

# Keycloak Server

You need to install and set up the Open Source Identity and Access Management Keycloak (opens new window).

TIP

There is small guide about the Keycloak Client Setup (opens new window).

# PDF-AS

For the actual PDF signing you need a PDF-AS server 4.1.5+ by EGIZ (opens new window).

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 (opens new window).

# 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):

  • Debian/Ubuntu
  • Redhat/CentOS8
# 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 7.3.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 7.3, 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 (opens new window) 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://gitlab.tugraz.at/dbp/relay/dbp-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 "dev-main"

# Change to app directory
cd relay-api

# Install the Frontend Bundle (https://gitlab.tugraz.at/dbp/relay/dbp-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://gitlab.tugraz.at/dbp/esign/dbp-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.

# Auth Bundle config

Follow the these steps to configure the Auth Bundle: Configure the Auth Bundle

# ESign Bundle config

You need to Configure the ESign Bundle (opens new window).

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 (opens new window) to learn how to run the Relay API in production.