Hosting

Run a Digital ID server and host your data yourself

Warning and Disclaimer

We recommend not to run the current Digital ID Server in production. See the roadmap for more information.

Requirements

Java Runtime

The Digital ID Server requires the Java SE Runtime Environment 8. You can check your current version (and whether you already have Java) with java -version on the command line of your operating system.

Please note that the version numbering of Java is decimal. All you need is a version of 1.8 or higher.

Database System

Make sure that you have either MySQL or MariaDB installed and that you know the password to access your database. PostgreSQL is not supported in the current version because of locking issues. If you have the necessary expertise, we would be thrilled if you could help us fixing it.

Domain Name

In order to set up a host on your server, you need to have a registered domain and configure a subdomain with the name ‘id’ (e.g. id.example.com) that references your server (either as an ‘A’ or ‘CNAME’ record).

Please note that the address of a host in Digital ID does not contain this subdomain (i.e. it is only example.com). The subdomain is only used internally for resolving host addresses but never presented to the user.

Port Number

The server has to be reachable on the port number 1494. Make sure that no firewall or router blocks the access and add corresponding exceptions or forwarding rules otherwise.

Apache Maven

Since this is currently only a test version, you need Apache Maven to build the server from the source code. A proper distribution package is planned for the future (and is also something you could help us with).

Installation

Download

Clone the maven, utility, database and core projects from GitHub:

git clone https://github.com/synacts/digitalid-maven.git
git clone https://github.com/synacts/digitalid-utility.git
git clone https://github.com/synacts/digitalid-database.git
git clone https://github.com/synacts/digitalid-core.git

Compilation

Build the source code as follows (and in that order):

cd digitalid-maven
mvn clean install
cd ../digitalid-utility
mvn clean install
cd ../digitalid-database
mvn clean install
cd ../digitalid-core
mvn clean install
cd ..

Execution

Startup

The server can be started from the command line as follows:

cd digitalid-core/server
mvn -q exec:java

If you start the server for the first time, it prompts you to configure the database.

Usage

Once the server has started up, you enter an infinite loop that looks like this:

You have the following options:
–  0: Exit the server.
–  1: Show the version.
–  2: Show the hosts.
–  3: Create a host.
–  4: Export a host.
–  5: Import a host.
–  6: Show the services.
–  7: Reload the services.
–  8: Activate a service.
–  9: Deactivate a service.
– 10: Change a provider.
– 11: Generate tokens.
– 12: Show members.
– 13: Add members.
– 14: Remove members.
– 15: Open a host.
– 16: Close a host.

Execute the option: _

Hosts

You can now choose the option 3 to create a host. Enter your domain name without the subdomain ‘id’ (i.e. only example.com). A host manages all identities and their associated data at the specified domain. You need a separate host for each domain, which can all be run by the same server on a single machine (similar to modern webservers).

Please note that it can take several minutes to generate the cryptographic keys during the creation of a host.

Services

At the moment, the functionality of the Digital ID Server cannot be extended with services.
(This only worked in an older version of the library. See the roadmap for when this will be supported again.)

Directory

All files created by the Digital ID Server are stored by default in an invisible folder in the user’s home directory with the name ~/.digitalid. This directory has the following subfolders:

  • hosts: Contains the public and private keys of all the hosts that run on this server.
    (The keys of the host created above should now be listed in this directory.)
  • clients: Contains the client secrets of all the clients on this machine.
    (Secrets that begin with an underscore belong to the client of the corresponding host.)
  • services: Contains the implementations of additional services as JAR files.
  • data: Contains the database configuration of the server.
    (It also contains the database files if clients are run with SQLite).
  • logs: Contains the log files of the server (and client).
    (A new file with the current date as its name is created each day.)

Please note that the library does not adhere to the above list of folders at the moment.

Certification

Before clients can connect to your host, you need to have its public key certified. Unfortunately, this process is not supported yet, which is one of the main reasons why you should only use the server for testing at the moment. Have a look at the roadmap for more information on this.

Deinstallation

All you have to do to deinstall the Digital ID Server and remove its data is to drop the database, delete the downloaded source directories and remove the hidden folders ~/.m2/repository/net/digitalid and ~/.digitalid.

Troubleshooting

If you run into problems, have a look at the log files in ~/.digitalid/logs. You can adjust the logging threshold in ~/.digitalid/configs/logging.conf with the logging levels being Verbose, Debugging, Information, Warning, Error, Fatal and Off.

Support

Please file any issues you encounter directly in the corresponding GitHub project (utility, database or core). If you are uncertain to which project an issue belongs, use the last one or contact us directly. When you do so, please attach the current log file. (Since the log file might contain sensitive information, it might be a good idea to first have a look at it yourself.)

License

The code of the Digital ID Server is available under the Apache License 2.0, which is a permissive software license that lets you do anything you want with the code as long as you provide proper attribution and don’t hold us liable.