README.md 3.97 KB
Newer Older
Livius's avatar
Livius committed
1 2 3 4 5 6 7 8 9
![id4me](http://id4me.org/wp-content/uploads/2018/03/ID4me_logo_2c_pos_rgb.png)

ID4me Open Prototype
--------------------

In order to help interested parties better understand how the **ID4me** protocol works and give the developers a 
starting point for their implementation, we have built an **Open Prototype** which includes the core functionalities of 
an agent. The **Open Prototype** was built as a proof of concept and it is not intended to be used in production.   

10
The agent works together with the **AUTHORITY** implementation provided by **DENIC** (https://id.denic.de/). 
Livius's avatar
Livius committed
11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41


Core functionalities
--------------------

The Open Prototype implementation has full **AGENT** functionalities as they are presented in 
[ID4me Technical Documentation](http://id4me.org/files/ID4me_Technical_Overview_v1.2.2.pdf):

* new identity registration and domain proof of ownership via **ACME** (*user has to manually add the DNS records) 
* claims storage
* user info retrieval
* claims management 
* access log
* authorization log 
 

Beside the core functionalities of an **AGENT** the open prototype also uses **ID4me** as a login method for the 
identity management, this way providing also a full implementation of a **RELYING PARTY**.   

Technical details
--------------------

The **Open Prototype** is written in **Python** and is using an embedded storage provided by **SQLite**. Our main concern
was to build something simple to understand and easy to get it running on a local machine. But keep in mind that when the 
application is running on a local environment some of the functionalities will not be available as the authority will 
not be able to send requests to the agent.

How to run
--------------------

* Install Docker (https://docs.docker.com/install/linux/docker-ce/ubuntu/)
42
* Build image locally
43 44 45
    ```
    docker build . -t id4me
    ```
Livius's avatar
Livius committed
46
* Create a new `id.db` sqlite database and apply `schema.sql`
47 48 49 50
    ```
    sqlite3 id.db < schema.sql
    chown www-data:www-data id.db
    ```
Livius's avatar
Livius committed
51

52
* Create your system-configuration
53 54 55 56 57 58 59 60 61 62 63 64 65
    ```
    # Start from example
    cp ./system-configuration.example ./system-configuration
    
    # Generate a RSA key - needed for signing JWT
    openssl genrsa -out ./system-configuration/id4me/private-key.pem 2048
    
    # Python settings
    vim ./system-configuration/id4me/main.cfg
    
    # Nginx settings
    vim ./system-configuration/nginx/id4me
    ```
66

67
* Place your own SSL certificate `.cer` and `.key` in `system-configuration`
68 69 70 71
    ```
    cp [local-path-to-certificate]/[certificate].cer ./system-configuration/nginx/ssl_certificate.cer
    cp [local-path-to-certificate]/[certificate].key ./system-configuration/nginx/ssl_certificate.key
    ```
Livius's avatar
Livius committed
72

73
* Run new container
74 75 76
    ```
    docker run --name id4me -p [IP]:[EXPOSED_PORT]:443 -d -v [local-path-to-db]/id.db:/usr/local/lib/id4me/id.db -v [local-path-to-system-config]/system-configuration:/etc/system-configuration id4me
    ```
77
* Check https://[IP]:[EXPOSED_PORT]
78 79


80 81
How to update existing app
-------------------------
82

83
* Rebuild docker image (only if repository was updated)
84 85 86
    ```
    docker build . -t id4me
    ```
87
* If necessary, update your system configuration
88 89 90 91 92 93 94
    ```
    # Python settings
    vim ./system-configuration/id4me/main.cfg
    
    # Nginx settings
    vim ./system-configuration/nginx/id4me
    ```
95
* Restart container
96 97 98 99 100 101 102
    ```
    # Stop and remove existing instance
    docker stop id4me && docker rm id4me
    
    # Start id4me
    docker run --name id4me -p [IP]:[EXPOSED_PORT]:443 -d -v [local-path-to-db]/id.db:/usr/local/lib/id4me/id.db -v [local-path-to-system-config]/system-configuration:/etc/system-configuration id4me
    ```
103
* If you want to reset app's account registered at an authority:
104 105 106 107 108
    ```
    sqlite3 id.db 'DELETE FROM identity_authority WHERE host = "[host]"';
    ```
    * Example:
    ```
109
    sqlite3 id.db 'DELETE FROM identity_authority WHERE host = "id.denic.de"';
110
    ```
Andreea Muscalu's avatar
Andreea Muscalu committed
111
    **WARNING**: if you do this, you must also update your `private-key.pem` & `main.cfg` with a new agent name.