membership.eclipse.org

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

• Getting Started
• CSRF and API Security
• Running the project in included web server
  • Dependencies to run
  • Setup
    • Local Running instances
    • Environment and properties
  • Running
  • Docker
    • Generate Certs for HTTPS
    • Update your Host file
  • MariaDB setup
  • KeyCloak Setup
    • Create realms
    • Eclipse Foundation as an Identity Provider
    • Client Configuration
• Contributing
  • Declared Project Licenses
• Bugs and feature requests
• Authors
• Trademarks
• Copyright and license

Getting Started

Before you start, please make sure you have yarn installed.

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

yarn --cwd src/main/www
yarn --cwd src/main/www build
yarn --cwd src/main/www start
yarn --cwd src/main/www start-spec

The web app will run in the development mode. Open http://localhost:3000 to view it in the browser.

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

CSRF and API Security

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.

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

Running the project in included web server

Dependencies to run

• Docker-compose
• Maven
• Java version 11
• Make

^ Top

Setup

Environment and properties

This setup assumes that the users developing for this application are employees of Eclipse Foundation with access to internal tooling and servers. If you do not have access to these resources, manual installation and setups will be required. To do initial setup, run make setup in the root of the directory project. This will fetch the missing SQL needed for DB initialization as well as start up the database with all of the needed tables for running the application.

Once initial setup is done, retrieve the secrets in the Webdev collection in BitWarden related to this service. They follow the naming pattern of membership-*-dev-secrets, where the star is replaced by the service the secrets are used for. These dev secrets will bind to the dockerized MariaDB mentioned in the previous step as well as the EF Keycloak instance, connecting to the staging realms (separate from production assets). These secrets should be placed under ./config/*/secret.properties, where the star is the service folder in the BitWarden secret name. This needs to be done before starting the actual services as otherwise Docker will create folders with incorrect permissions and need to be manually fixed. Additionally, if the mariadb password has been changed from default, replace the quarkus.datasource.password and quarkus.datasource.*.password values with the local password value. This can be retrieved by using echo $MARIADB_PASSWORD in the terminal if you're unsure.

Once the DB is running and the secrets have been set into the secret files, then run make compile && make start. This command will compile the react and Java applications, build the images, and start them in docker. This should be all that is needed to start the application. Below are the port mappings used to access the application from outside the docker network.

^ Top

Running

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.

^ Top

Docker

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

• mariadb:latest
• jboss/keycloak:11.0.1

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.

make generate-cert

Update your Host file

We use 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
127.0.0.1 nginx.rem.docker

^ Top

MariaDB setup

The base definitions of the tables as required for the connection of this API are defined under ./application/src/main/resources/sql/rem_ddl.sql, ./portal/src/main/resources/sql/eclipsedb_ddl.sql, ./portal/src/main/resources/sql/dashboard_ddl.sql, and a final file from the FoundationDB API (TODO). These should all be added present in the MariaDB instance to support this API.

Keycloak Setup

Create realms

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, mouse hover where it says master and click on Add Realm, set the name to community and click create. Repeat this and additionally create a foundation realm.

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 since we want our users to login with our standard login page. 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.

Client Configuration

The clients tab allows you to manage the 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.

• Foundation realm
  • rem_api client
    • Root URL = ""
    • Client protocol = ""
    • Access type = ""
  • fdn_api client
    • Root URL = ""
    • Client protocol = ""
    • Access type = ""
• Community realm
  • rem_app client
    • Root URL = "http://localhost:3000"
    • Client protocol = "openid-connect"
    • Access type = "confidential"

An additional client will be required for the FoundationDB API access. Information on setting up this client should be defined under the FoundationDB API README file. Once the client is acquired, it will need to have its client ID and secret set in the secret.properties file. They will be respectively set under the properties quarkus.oidc-client.client-id and quarkus.oidc-client.credentials.secret. The URL of the client within the FoundationDB API realm will need to also be set within the secret.properties under the quarkus.oidc-client.auth-server-url property.

To enable connections to the FoundationDB API, 2 clients will need to be created in the same realm as was created for the FoundationDB API service. This second client will be set up similarly to the first, but have service accounts enabled. Once enabled, roles will need to be set within the service account giving all org related roles, as well as sys read access. This should properly restrict service access to the API.

^ Top

Contributing

1. Fork the membership.eclipse.org repository
2. Clone repository: git clone https://gitlab.eclipse.org/[your_eclipsefdn_username]/membership.eclipse.org.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 merge request

^ Top

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

^ Top

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.

^ Top

Authors

Christopher Guindon (Eclipse Foundation)

• https://twitter.com/chrisguindon
• https://github.com/chrisguindon

Martin Lowe (Eclipse Foundation)

• https://github.com/autumnfound

^ Top

Trademarks

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

^ Top

Copyright and license

Copyright 2018-2022 the Eclipse Foundation, Inc. and the membership.eclipse.org authors. Code released under the Eclipse Public License Version 2.0 (EPL-2.0).