README.md 13.2 KB
Newer Older
1
2
# react-eclipsefdn-members

3
[![Build Status](https://travis-ci.org/EclipseFdn/react-eclipsefdn-members.svg?branch=master)](https://travis-ci.org/EclipseFdn/react-eclipsefdn-members) [![Netlify Status](https://api.netlify.com/api/v1/badges/b0087dce-17ae-46f6-bbea-b3813d35be3f/deploy-status)](https://app.netlify.com/sites/eclipsefdn-react-members/deploys)
4
5
6

Supported by our member organizations, the Eclipse Foundation provides our community with Intellectual Property, Mentorship, Marketing, Event and IT Services.

7
8

<!-- TOC -->
9
10
11
12
- [react-eclipsefdn-members](#react-eclipsefdn-members)
  - [Getting Started](#getting-started)
  - [CSRF and API Security](#csrf-and-api-security)
  - [Running the project in included web server](#running-the-project-in-included-web-server)
13
14
15
16
    - [Dependencies to run](#dependencies-to-run)
    - [Setup](#setup)
    - [Running](#running)
    - [Docker](#docker)
17
18
19
      - [Generate Certs for HTTPS](#generate-certs-for-https)
      - [Update your Host file](#update-your-host-file)
      - [Environment Variables](#environment-variables)
20
    - [KeyCloak Setup](#keycloak-setup)
21
22
23
24
25
      - [Create a realm](#create-a-realm)
      - [Create a user](#create-a-user)
      - [Eclipse Foundation as an Identity Provider](#eclipse-foundation-as-an-identity-provider)
      - [Client Configuration](#client-configuration)
  - [Contributing](#contributing)
26
    - [Declared Project Licenses](#declared-project-licenses)
27
28
29
30
  - [Bugs and feature requests](#bugs-and-feature-requests)
  - [Authors](#authors)
  - [Trademarks](#trademarks)
  - [Copyright and license](#copyright-and-license)
31
32
<!-- /TOC -->

33
34
## Getting Started

35
Before you start, please make sure you have [yarn](https://classic.yarnpkg.com/en/docs/install/) installed.
36

37
Once that's done, you can install dependencies, build assets and start a dev server:
38

39
40
41
42
```bash
yarn --cwd src/main/www
yarn --cwd src/main/www build
yarn --cwd src/main/www start
43
yarn --cwd src/main/www start-spec
44
```
45

46
The web app will run in the development mode.
47
48
49
50
51
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.

The page will reload if you make edits.<br />
You will also see any lint errors in the console.

52
53

## CSRF and API Security
54
Currently, the endpoints that can contain personal data of users have been secured by OIDC and CSRF. What this means for development in the front end is all requests will need to be performed with a legitimate Eclipse Foundation login and account for the CSRF header.
55
56
57
58
59
60

Pertaining to data posted to the API, there is no current automatic deletion policy enforced, and no current way in the UI to send a call to delete data. If you wish to delete this data, you will need to craft javascript within the site to take advantage of the session and CSRF headers, and manually make the call. More information on the form deletion endpoint can be seen in the OpenAPI spec under `/spec/openapi.yml`.

Additionally, when requesting any PII/form data, a CSRF token will need to be passed unless disabled on a development server. This token will live under the `x-csrf-token` header that is supplied on every request the user makes to the server, including the unprotected `/csrf/` endpoint that is available. The token should be posted back to the server using the same header. This value will remain the same for the duration of the browser session.

[^ Top](#react-eclipsefdn-members)
61
## Running the project in included web server
62

63
### Dependencies to run
64

65
- Docker-compose
66
- Maven
67
- Java version 11
68

69
[^ Top](#react-eclipsefdn-members)
70
### Setup
71

72
As part of the set up, you will need to create a `secret.properties` file within the `./config` folder and set up the secrets that are required to run the application. If named `secret.properties`, the file should be ignored by Github automatically, making it less risky that credentials are accidentally uploaded to a branch.
73

74
The fields required to run are the datasource and OIDC properties. The datasource properties should be a set of user credentials that can write to a local mariadb instance. Within that mariadb instance, a database should be created to contain the data used in development. Once created, a JDBC URL can now be formed for the new database. This URL should follow the pattern below, with port not always required (depending on your local setup and proxy settings).  This will be set in the `secret.properties` file.
75

76
```
77
quarkus.datasource.jdbc.url = jdbc:mariadb://<host><:port?>/<databaseName>
78
```
79

80
Once this is set, set the `quarkus.datasource.username` and `quarkus.datasource.password` fields to the user with access to the given database in the `secret.properties` file.
81

82
The other half of secret configuration is setting up the OIDC credentials for connecting to a keycloak server. This server will require a realm to be set up for access. Using the name `rem_realm` is easiest as it requires no changes to the configuration to work.
83
84

The `quarkus.oidc.auth-server-url` property in the `secret.properties` file will need to be updated. The value set should be the public realm address for your server and realm. The rest of the endpoints will be taken care of by the wellknown endpoint available in Keycloak, and don't need to be configured. For the dockerized service, this should be set to your local IP address (note, not your public address). This can be retrieved from your IP configuration application and added in the format displayed in the `sample.secret.properties` file.
85

86
Inside that realm, create a client and update the `quarkus.oidc.client-id` property within the `secret.properties` file. Inside that client, open the settings and go to the credentials tab. The secret will need to be copied and set into the `secret.properties` file in the `quarkus.oidc.credentials.client-secret.value` property. For proper reading and usage of development data, 3 users should be created and added to the realm with the usernames `user1`, `user2`, and `user3`.
87
88
89
90
91

With these properties updated, the server should be able to start and authenticate properly. If the 3 users mentioned within the OIDC configuration section were added, the data should be accessible in a way that is comparable to how it would be in production.

As a side note, regeneration of the database on start along with the insertion of data into the database can be disabled for development environments by setting the following fields within `src/main/resources/application.properties`:

92
1. Setting `%dev.eclipse.dataloader.enabled` to false. This property is what enables the Data bootstrap to load in mock data.
93
94
2. Removing the `%dev.quarkus.hibernate-orm.database.generation` property or commenting it out. This is what resets the database to empty on start.

95
[^ Top](#react-eclipsefdn-members)
96
### Running
97

Christopher Guindon's avatar
Christopher Guindon committed
98
To run the server as a local instance as a stack, you will need to compile the application first, which can be done through `make compile-start`. This takes care of all of the steps needed to cleanly build and rebuild the application from scratch. This will also run the stack with the packaged application.
99

100
[^ Top](#react-eclipsefdn-members)
Christopher Guindon's avatar
Christopher Guindon committed
101
102
103
104
105
106
107
108
### Docker

We include a `docker-compose.yml` file with this project to help you get started. This includes:

* [mariadb:latest](https://hub.docker.com/_/mariadb)
* [postgres:12.4](https://hub.docker.com/_/postgres)
* [jboss/keycloak:11.0.1](https://hub.docker.com/r/jboss/keycloak/)

109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
#### Generate Certs for HTTPS

, You will need to create a certificate in order to serve the Application on https. Make sure that the Common Name (e.g. server FQDN or YOUR name) is set to `www.rem.docker`.

```sh
make generate-cert
```

#### Update your Host file

We use [jwilder/nginx-proxy](https://hub.docker.com/r/jwilder/nginx-proxy) as automated Nginx reverse proxy for our docker containers. So instead of having to lookup the port of a new service, you can simply remember it's internal dev hostname.

Different operating system, different file paths!

Windows: C:\Windows\System32\drivers\etc\hosts
Linux / MacOS: /etc/hosts

```
# rem services

127.0.0.1 keycloak
127.0.0.1 api.rem.docker
127.0.0.1 www.rem.docker
132
127.0.0.1 nginx.rem.docker
133
134
```

Christopher Guindon's avatar
Christopher Guindon committed
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
#### Environment Variables

To use our `docker-compose.yml` file, create a `.env` file in the root of this project and insert your key/value pairs in the following format of KEY=VALUE. You must make sure to update the value of each variable:

```sh
REM_KEYCLOAK_USER=user_sample
REM_KEYCLOAK_PASSWORD=password_sample
REM_MYSQL_PASSWORD=password_sample
REM_POSTGRES_DB=keycloak_sample
REM_POSTGRES_USER=keycloak_sample
REM_POSTGRES_PASSWORD=password_sample
```

Once this initial setup is done, you can start these services with this command:

```sh
151
make compile-start
Christopher Guindon's avatar
Christopher Guindon committed
152
153
```

154
[^ Top](#react-eclipsefdn-members)
155
156
157
158
159
160
161
162
163
164
165
166
### KeyCloak Setup

#### Create a realm

Realm is a concept in Keycloak that refers to an object managing a set of users along with their credentials, roles and groups. To create a `realm`, visit [Keycloak Admin Console](http://localhost:8080/auth/admin), mouse hover where it says `master` and click on `Add Realm`, set the name to `rem_realm` and click `create`.

#### Create a user

To create a `user`, visit [Keycloak Admin Console](http://localhost:8080/auth/admin) and click on `Users` in the left menu. Then press the `Add User` button and fill up the form with information about the user you wish to create.

To login as the user, you will need to set an initial password. To set a password, click on `Credentials`,  then set a password via the `Set Password` form. You will need to enter it twice to confirm it. You will probably want to disable `Temporary` password by clicking on the `ON` button to turn that feature off.

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
#### Eclipse Foundation as an Identity Provider

It's possible to delegate authentication to third party identity providers with Keycloak. With this App, we want to leverage [Eclipse Foundation OpenID Connect](https://wiki.eclipse.org/OpenID) since we want our users to login with our standard login page. In order to do so, you will need a client_id/secret from us.

Assuming you have access to that already, please follow these steps to add the Eclipse Foundation as an `Identity Provider`.

1. Click on `Identity Providers` in the left menu then click on `Add provider...`. Select `OpenID Connect v1.0` from the dropdown menu.

2. Populate the form with the following information:

```
Alias : eclipsefdn
Display Name: Eclipse Foundation
Sync Mode : Force (To make sure the user is updated each time they login)
Authorization URL: https://accounts.eclipse.org/oauth2/authorize
Token URL: https://accounts.eclipse.org/oauth2/token
Logout URL: https://accounts.eclipse.org/oauth2/revoke
User Info URL: https://accounts.eclipse.org/oauth2/UserInfo
Client Authentication: Client secret sent as post
Client ID: <CLIENT_ID>
Client Secret: <CLIENT_SECRET>
Default Scopes: openid profile email offline_access
```

1. Finally, we want to configure Eclipse Foundation has the only authentication option. Click on `Authentication` in the left menu. Set `Identity Provider Redirector` to `required` and `Forms` to `disabled`. Finally, click on Actions and set `eclipsefdn` has the `Default Identity Provider`.


194
195
196
197
198
199
#### Client Configuration

Clients tab allows you to manage list of allowed applications.

To create a client, click on `Clients` in the left menu. You can set the client_id to `rem_app` and the `Root URL` to `http://localhost:3000`. Make sure that the `Client Protocol` is set to `openid-connect`  and the `Access Type` is set to `confidential`.

200
[^ Top](#react-eclipsefdn-members)
201
202
203
204
205
206
207
208
209
## Contributing

1. [Fork](https://help.github.com/articles/fork-a-repo/) the [eclipsefdn/react-eclipsefdn-members](https://github.com/eclipsefdn/react-eclipsefdn-members) repository
2. Clone repository: `git clone https://github.com/[your_github_username]/react-eclipsefdn-members.git`
3. Create your feature branch: `git checkout -b my-new-feature`
4. Commit your changes: `git commit -m 'Add some feature' -s`
5. Push feature branch: `git push origin my-new-feature`
6. Submit a pull request

210
[^ Top](#react-eclipsefdn-members)
211
212
213
214
215
216
217
218
### Declared Project Licenses

This program and the accompanying materials are made available under the terms
of the Eclipse Public License v. 2.0 which is available at
http://www.eclipse.org/legal/epl-2.0.

SPDX-License-Identifier: EPL-2.0

219
[^ Top](#react-eclipsefdn-members)
220
221
222
223
## Bugs and feature requests

Have a bug or a feature request? Please search for existing and closed issues. If your problem or idea is not addressed yet, [please open a new issue](https://github.com/eclipsefdn/react-eclipsefdn-members/issues/new).

224
[^ Top](#react-eclipsefdn-members)
225
## Authors
226
227
228
229
230
231

**Christopher Guindon (Eclipse Foundation)**

- <https://twitter.com/chrisguindon>
- <https://github.com/chrisguindon>

232
233
234
235
**Martin Lowe (Eclipse Foundation)**

- <https://github.com/autumnfound>

236
237
238
239
**Zhou Fang (Eclipse Foundation)**

- <https://github.com/linkfang>

240
[^ Top](#react-eclipsefdn-members)
241
242
243
244
245
## Trademarks

* Eclipse® is a Trademark of the Eclipse Foundation, Inc.
* Eclipse Foundation is a Trademark of the Eclipse Foundation, Inc.

246
[^ Top](#react-eclipsefdn-members)
247
248
## Copyright and license

249
Copyright 2021 the [Eclipse Foundation, Inc.](https://www.eclipse.org) and the [react-eclipsefdn-members authors](https://github.com/eclipsefdn/react-eclipsefdn-members/graphs/contributors). Code released under the [Eclipse Public License Version 2.0 (EPL-2.0)](https://github.com/eclipsefdn/react-eclipsefdn-members/blob/src/LICENSE).