1
2
3
4
5
6
7
8
9
10
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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
LEAP Web
---------------------
The LEAP Web App provides the following functions:
* User registration and management
* Help tickets
* Client certificate renewal
* Webfinger access to user’s public keys
* Email aliases and forwarding
* Localized and Customizable documentation
Written in: Ruby, Rails.
The Web App communicates with:
* CouchDB is used for all data storage.
* Web browsers of users accessing the user interface in order to edit their settings or fill out help tickets. Additionally, admins may delete users.
* LEAP Clients access the web app’s REST API in order to register new users, authenticate existing ones, and renew client certificates.
* tokens are stored upon successful authentication to allow the client to authenticate against other services
LEAP Web is provisioned and run as part of the overall [LEAP platform](https://leap.se/en/docs/platform).
[](https://travis-ci.org/leapcode/leap_web)
Original code specific to this web application is licensed under the GNU
Affero General Public License (version 3.0 or higher). See
http://www.gnu.org/licenses/agpl-3.0.html for more information.
Documentation
---------------------------
For more information, see these files in the ``doc`` directory:
* DEPLOY -- for notes on deployment.
* DEVELOP -- for developer notes.
* CUSTOM -- how to customize.
External docs:
* [Overview of LEAP architecture](https://leap.se/en/docs/design/overview) - Bird's eye view of how all the pieces fit together.
* [Contributing](https://leap.se/en/docs/get-involved) - Contributing to LEAP software development.
* Contributing to LEAP software development
* How to issue a pull request
* Overview of the main code repositories
* Ideas for discrete, unclaimed development projects that would greatly benefit the LEAP ecosystem.
Installation
---------------------------
Typically, this application is installed automatically as part of the
LEAP Platform. To install it manually for testing or development, follow
these instructions:
### Install system requirements
You'll need git, ruby (2.1.5), couchdb and bundler installed.
On a recent debian based distribution run
sudo apt install git ruby couchdb bundler
For other operation systems please lookup the install instructions of these
tools.
### Download source
We host our own git repository. In order to create a local clone run
git clone --recursive git://leap.se/leap_web
cd leap_web
The repo is mirrored on github and we accept pull requests there:
https://github.com/leapcode/leap_web
### Pick branch (development only)
We use the master branch for the stable version deployed to production.
Development usually happens on the develop branch. So for development you
want to run
git checkout origin/develop -b develop
This will create a local branch called develop based on our develop branch.
### Install required ruby libraries
bundle --binstubs
Typically, you run ``bundle`` as a normal user and it will ask you for a
sudo password when it is time to install the required gems. If you don't
have sudo, run ``bundle`` as root.
### Installation for development purposes
Please see `doc/DEVELOP.md` for details about installing
leap_web for development purposes.
Configuration for Production
----------------------------
The configuration file `config/defaults.yml` provides good defaults for
most values. You can override these defaults by creating a file
`config/config.yml`.
There are a few values you should make sure to modify:
production:
admins: ["myusername","otherusername"]
domain: example.net
force_ssl: true
secret_token: "4be2f60fafaf615bd4a13b96bfccf2c2c905898dad34"
client_ca_key: "./test/files/ca.key"
client_ca_cert: "./test/files/ca.key"
ca_key_password: nil
* `admins` is an array of usernames that are granted special admin
privilege.
* `domain` is your fully qualified domain name.
* `force_ssl`, if set to true, will require secure cookies and turn on
HSTS. Don't do this if you are using a self-signed server certificate.
* `secret_token`, used for cookie security, you can create one with
`rake secret`. Should be at least 30 characters.
* `client_ca_key`, the private key of the CA used to generate client
certificates.
* `client_ca_cert`, the public certificate the CA used to generate client
certificates.
* `ca_key_password`, used to unlock the client_ca_key, if needed.
Running
-----------------------------
To run leap_web:
cd leap_web
bin/rake db:rotate
bin/rake db:migrate
bin/rails server
Then open http://localhost:3000 in your web browser.
When running in development mode, you can login with administrative
powers by creating an account with username 'staff', 'blue', or 'red'
(configured in config/default.yml).
To peruse the database, visit http://localhost:5984/_utils/
The task `db:rotate` must come before `db:migrate`, in order to assure that
the special rotating databases get created.
Do not run the normal CouchRest task 'couchrest:migrate'. Instead, use
'db:rotate' since the latter will correctly use the couchdb.admin.yml file.
Testing
--------------------------------
To run all tests
bin/rake RAILS_ENV=test db:rotate # if not already run
bin/rake RAILS_ENV=test db:migrate # if not already run
bin/rake test
To run an individual test:
rake test TEST=certs/test/unit/client_certificate_test.rb
or
ruby -Itest certs/test/unit/client_certificate_test.rb
Known problems
---------------------------
* Client certificates are generated without a CSR. The problem is that
this makes the web application extremely vulnerable to denial of
service attacks. This is not an issue unless the provider enables the
possibility of anonymously fetching a client certificate without
authenticating first.
* By its very nature, the user database is vulnerable to enumeration
attacks. These are very hard to prevent, because our protocol is
designed to allow query of a user database via proxy in order to
provide network perspective.
Twitter Timeline on Main View
---------------------------
This is a feature to include a twitter feed that displays most recent tweets
of a (determined) twitter account (accessed via Twitter API).
If you chose to use it, the feature gets included in `home/index` of
LEAP web app (as part of the main view).
* Create Twitter Application on https://apps.twitter.com/
* Visit https://apps.twitter.com/ and log in with the twitter account you want to use
* Make sure you have a mobile phone number registered with your account to be able to proceed
* Choose the option to `Create New App`
* Fill in Application Details and Developer Agreement and `Create your Twitter application`
* Choose the section "Keys and Access Tokens" to get your consumer key and consumer secret
* Optional: Go to section "Permissions" and change the "Access" from `Read and Write` (by default) to `Read only`
* Have your consumer key and secret by hand for one of the next steps
* Activate the feature within your local LEAP Web Application
* If not already existing create a secrets-file in /config with the name secrets.yml (`/config/secrets.yml`)
* Secrets-file should contain the following, make sure its in YAML: {"development"=> {"twitter"=>{"enabled"=>false, "twitter_handle"=>"", "bearer_token"=>"", "twitter_picture"=>nil}}, "test"=>{"twitter"=>{"enabled"=>false, "twitter_handle"=>"", "bearer_token"=>"", "twitter_picture"=>nil}}}
* To have your bearer token created, run script in terminal being in the file of leap_web: `script/generate_bearer_token`
* To have the script run properly you have to add before running: `--key your_consumerkey --secret your_consumersecret`
* Add also `--projectroot your_projectroot --twitterhandle your_twitterhandle` as well to not have manually put the data in your secrets-file
* The full command looks like this: `script/generate_bearer_token --key your_consumerkey --secret your_consumersecret --projectroot your_projectroot --twitterhandle your_twitterhandle`
* If you didn't give all your information to the script, had a typo or want to change anything else, please do so by finding the secrets-file at `/config/secrets.yml`
* Make sure that the correct twitterhandle and bearer-token is included
* Deactivate your bearer token
* To deactivate your generated bearer token you can run `script/invalidate_bearer_token`
* The full command looks like this: `script/invalidate_bearer_token --key your_consumerkey --secret your_consumersecret --token your_bearer_token`
|
