Openconext-Invite

Getting started

System Requirements

• Java 21
• Maven 3+
• Node (nvm)
• Yarn

First install Java 21 with a package manager and then export the correct the JAVA_HOME. For example on macOS:

export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-21.jdk/Contents/Home/

MariaDB and Mailpit in docker for local development

docker compose up -d

Then create the MySQL database:

DROP DATABASE IF EXISTS invite;
CREATE DATABASE invite CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci;
CREATE USER 'invite'@'%' IDENTIFIED BY 'secret';
GRANT ALL privileges ON `invite`.* TO 'invite'@'%';

Note: for MariaDB COLLATE utf8mb4_0900_ai_ci might not work and can be left out

Building and running

This project uses Spring Boot and Maven. To run locally, type:

cd server 
mvn spring-boot:run

Install client frontend dependencies

cd client 
nvm use
yarn install

Install welcome frontend dependencies

cd welcome 
nvm use
yarn install

Run the client frontend http://localhost:3000

cd client
yarn start

Run the welcome frontend http://localhost:4000

cd welcome
yarn start

Run the server backend

mvn spring-boot:run -Dspring-boot.run.profiles=dev -Dmaven.test.skip=true

Mail

In the default application.yml the mail host is localhost and the port is 1025. Run mailpit to capture mails. See https://github.com/axllent/mailpit

Endpoints

https://invite.test.surfconext.nl/ui/swagger-ui/index.html

https://mock.test.surfconext.nl/

https://welcome.test.surfconext.nl/

https://invite.test.surfconext.nl/

Mock

If you want to use the mock-provisioning, add the following metadata in Manage.

SCIM:

"provisioning_type": "scim",
"scim_url": "https://mock.test.surfconext.nl/api/scim/v2",
"scim_user": "user",
"scim_password": "secret",
"scim_update_role_put_method": true

eVA

"provisioning_type": "eva",
"eva_token": "secret",
"eva_guest_account_duration": 30
"eva_url": "https://mock.test.surfconext.nl/eva",

Graph

"provisioning_type": "graph",
"graph_url": "https://mock.test.surfconext.nl/graph/users",
"graph_client_id" : "client_id",
"graph_domain" : "hartingcollege.onmicrosoft.com",
"graph_secret" : "secret",
"graph_tenant": "tenant"

Local endpoints

Login with Mujina IdP and user admin to become super-user in the local environment

http://localhost:8888/ui/swagger-ui/index.html

http://localhost:8081/

http://localhost:4000

http://localhost:3000

Institution Admin

To become an institution admin in invite, add the following values as eduPersonEntitlements using Mujina:

• urn:mace:surfnet.nl:surfnet.nl:sab:organizationGUID:ad93daef-0911-e511-80d0-005056956c1a
• urn:mace:surfnet.nl:surfnet.nl:sab:role:SURFconextverantwoordelijke

Technical documentation

https://openconext.github.io/OpenConext-Invite/

Security

There are several security filters in Invite:

• OAuth2 login where the user logs in with OpenIDConnect. Invite is acting as a backend server and cookies are used to identify the user in the security context.
• Access token login where the user has logged in with OpenIDConnect and the client obtained an access token. Invite is acting as a resource server. The API is stateless and for now no token introspects are cached.
• Basic Authentication for voot, teams, aa, profile, deprovision and sp_dashboard endpoints. The API is stateless and the API users are stored in memory. Endpoints are also secured by scope.
• API token header (X-API-TOKEN) generated for institutional_admins (or super_users) in the GUI. The user stored in the security context is the first user with the same organisational GUID (or super_user) as the user who has generated the token.

Provisioning Secrets

The secrets (passwords / API-keys) used in provisionings are encrypted in OpenConext-Manage using keypairs.

Create private / public keypair

openssl genrsa -traditional -out private_key.pem 2048
openssl rsa -pubout -in private_key.pem -out public_key.pem

Convert private key to pkcs8 format in order to import it from Java

openssl pkcs8 -topk8 -in private_key.pem -inform pem -out private_key_pkcs8.pem -outform pem -nocrypt

Deploy

To build and deploy (the latter requires credentials in your maven settings):

mvn clean deploy

Upgrade

To check the pom.xml with the latest versions, run

cd server
mvn versions:display-dependency-updates -DprocessDependencyManagement=false -DdependencyIncludes=*:*

To see the latest versions report for the client run

cd client
nvm use
yarn outdated

CRM

CRM api calls have been added to enable migration from a legacy application called SAB (SURF Autorisatie Beheer). These api calls are actively used to integrate with the enterprise role administration system.