Digitally sign one or multiple PDF documents with a freely positioned seal.
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)
# 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:
- 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
# 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).
There is small guide about the Keycloak Client Setup (opens new window).
We provide two pre-configured variants of pdf-as, you need at least one of them depending on your use case:
- PDF-AS Server for Advanced Signatures (opens new window) - Configured for advanced signatures
- PDF-AS Server for Qualified Signatures (opens new window) - Configured for qualified signatures
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.
You can find an example implementation on relay-esign-api (opens new window).
This is how this example will look like in the end.
# 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 7.3.x" (or higher) php -v # Should show something like "Composer 2.x" composer -V
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
# enable mod rewrite a2enmod rewrite
In your virtual host configuration you need to allow
.htaccess files and set your
DocumentRoot to the
Note that in this example
/[VHOST-ROOT]/relay-api will be the path where the PHP application resides.
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.
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
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).
PDF_AS_ settings in your
# 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:
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.