EID-Based Single Sign-On Service

Authentication via username and password has a couple of disadvantages. Hence, enterprises and governments attempt to replace the authentication by username and password with an alternative solution such as the use of hardware tokens. In Germany, the government introduced nPa as an official hardware token that can be used for authentication and that fulfills high standards in security and privacy.

In the course of this project, an authentication service is designed and implemented that enables third parties to authenticate their users using eid, i.e. the "neuen Personalausweis" ("new" german id card) or the electronic residency permit, instead of using username and password.

Getting Started

Install Docker

This project uses Docker CE and Docker Compose to run all services. Installing Docker depends on the platform and is hence not included here. Docker Compose has to be installed separately.

Source Code

To obtain the source code, please clone this repository.

git clone https://github.com/nils-wisiol/django-rest-boilerplate

Running

Running this project requires a fully configured .env file. A template for .env can be found in .env.default. Below, all values are documented.

• BOILERPLATE_DOMAIN: the domain name of the service provided
• BOILERPLATE_IPV4_16PREFIX: internal network IPv4 address prefix. The default value 172.16 will suit most users.
• BOILERPLATE_IPV6_SUBNET: internal network IPv6 subnet. The default value bade:affe:dead:beef:b011::/80 will suit most users.
• BOILERPLATE_IPV6_ADDRESS: internal network IPv6 address. The default value bade:affe:dead:beef:b011:0642:ac10:0080 will suit most users.

• BOILERPLATE_WWW_CERTS: location of the required SSL certificates in PEM format. This folder needs to contain the following four files:

  • MAIN.cer, MAIN.key: certificate and private key for BOILERPLATE_DOMAIN.
  • www.cer, www.key: certificate and private key for www. BOILERPLATE_DOMAIN.

  The certificates can be obtained any way (and can also be the same). Please see below for an convenient way to obtain debug certificates for BOILERPLATE_DOMAIN (but lacking a valid certificate for www.BOILERPLATE_DOMAIN). Alternatively, you can also use self-signed certificates.

• BOILERPLATE_API_SECRETKEY: needs to be set to an instance-specific random secret value.
• BOILERPLATE_DB_PASSWORD: the database user password, should also be set to an instance-specific random secret value.

Optional for using the example oidc client:

• CLIENT_ID: id generated by the OpenID-Provider
• REDIRECT_URL: uri that will be called after authentication
• AUTHORITY_URL: uri of the authentication service

After populating .env with all appropriate values, the service can be started with

docker-compose up

and be reached at your chosen domain name. Remember to have your domain name point at $BOILERPLATE_IPV4_16PREFIX.0.128 (for the default configuration this is 172.16.0.128). At $BOILERPLATE_DOMAIN/api/admin/, the generic django administration backend is available.

Project Design

This project uses Docker CE and Docker Compose to run all services. All components of the project are within docker containers and docker-compose scripts are provided to start all necessary services.

• The api container contains the Django-implemented RESTful API implementation. As such, it handles

  • routing of all requests with URL beginning with https://$BOILERPLATE_DOMAIN/api/,
  • authentication of these requests, and
  • providing requested data and/or updating the database accordingly.

  It communicates with www through an uwsgi interface and implements the necessary components for the authentication process with eid

  • __eid_server__
  • __eid_service__
  • eid_oidc_provider

  Please see the corresponding Software Architecture#components section in the WIKI for further information.

• The db container provides the MySQL (MariaDB) database used by the api. It is the only container in our setup that uses a Docker volume to persistently store data.

• The static container serves static files. This can be a basic website advertising the API service or an involved JavaScript application designed for usage with the API. (It can also be easily removed entirely.)

• The www container accepts all incoming connections. It handles

  • forwarding the request to either the API or static servers,
  • transport layer security, and
  • rate limits.

• The test/e2e container mocks a user and executes the defined end-to-end tests. (Cf. test/e2e/spec/*_spec.js.)
  For further information read the [[Testing]] section.

• The oidc_client_example container mocks a third party which uses the authentication with this eid authentication service.

OIDC Provider

Before third parties can use this service, they have to register as clients. Therefore, see the [[OIDC Provider|Software Architecture#oidc-provider]] section.

After registering the client, this service can be used to authenticate their users according to the OpenID Connect process by calling $BOILERPLATE_DOMAIN/api/openid as authority URL. For further information concerning the OpenID Connect process see the OpenID Connect section in the WIKI. This project also includes an example OIDC client.

OIDC example client

Start example client

• Run the client in the project root dir, via docker-compose -f docker-compose.example.yml up

Environment variables to be set in .env:

• CLIENT_ID id generated by the OpenID-Provider
• REDIRECT_URL uri that will be called after the authentication
• AUTHORITY_URL uri of the authentication service

Generate a client id

You have to register your client in your openID provider, during this registration process a provider unique client id will be created. This is the id you can use as value for CLIENT_ID.

Set Urls

The redirect url is the url which will be used if the authorization process was successfull. You have to set a set of possible redirect urls during the registration process mentioned above. Therefore the redirect url used in the variable has to be an element of the former defined set. In our case a valid value could be http://localhost:3000.

The authority url is the url to the open id provider server, that will be used to authenticate. In our case a valid value could be something like https://eid.localhost/api/openid.

For more information about the used javascript library see here. If you are interested in the documentation of the used openid provider see here.

Step-by-Step Guide

Open a console:

git clone git@github.com:swp-fu-eid/eid-fu-swp.git
cd eid-fu-swp
mkdir certs
cd certs
openssl req -newkey rsa:2048 -nodes -keyout www.key -x509 -days 365 -out www.cer
openssl req -newkey rsa:2048 -nodes -keyout MAIN.key -x509 -days 365 -out MAIN.cer
cd ..
cp .env.default .env

Edit .env:

BOILERPLATE_DOMAIN=eid.local

# network
BOILERPLATE_IPV4_16PREFIX=172.16
BOILERPLATE_IPV6_SUBNET=bade:affe:dead:beef:b011::/80
BOILERPLATE_IPV6_ADDRESS=bade:affe:dead:beef:b011:0642:ac10:0080

#certificates
BOILERPLATE_WWW_CERTS=./certs

# API-related
BOILERPLATE_API_SECRETKEY=1234
BOILERPLATE_DB_PASSWORD=1234

Open a console:

echo -e "\n172.16.0.128\teid.local" | sudo tee --append /etc/hosts
docker-compose up --build
docker-compose exec api python manage.py createsuperuser
docker-compose exec api python manage.py creatersakey

Open a browser and go to: https://eid.local/api/admin.

Login as superuser.

Choose "Add Client".

Create a new client with Name=test, Client Type=Public, Response Type=id_token token (Implicit Flow), Redirect URIs=http://localhost:3000, JWT Algorithm=RS256, Require Consent?=true, Reuse Consent?=true, Save.

Copy the <Client ID>.

Logout.

Append to .env:

# Example OIDC-Client
CLIENT_ID=<Client ID>
AUTHORITY_URL=https://eid.local/api/openid
REDIRECT_URL=http://localhost:3000

Stop the `docker-compose up --build' and restart it in order to load the new .env-file.

Open another console:

docker-compose -f docker-compose.example.yml up

Open a browser and go to: http://localhost:3000.

As the eid server in this project is not working you can not execute the whole process. But you have now setup the provider and registered a client which could use the service.

License

All work in this repository is licensed under the MIT license. For details, see the LICENSE file.