Skip to main content

Modules

Runnable Modules

<<system>>public-api<<system>>login-servicePublic Services[system]<<system>>internal-api<<system>>githubInternal Services[system]<<system_db>>Neo4j<<system_db>>MongoDB<<system_db>>PostgresQLDatabases[system]Public Services[system]1: bolt/TCP2: bolt/TCP3: REST/HTTP4: GraphQL/HTTP5: bolt/TCP6: mongodb/TCP7: TCP

api-public​

The main GraphQL API of the backend. Can safely be publicly exposed and can be horizontally scaled. By default, users have to be authenticated. A JWT must be obtained via the authentication service (tbd) and then provided with each GraphQL request using the Authorization-Header:

Authorization: Bearer token

Authorization can be disabled for debugging purposes by setting gropius.api.debugNoAuthentication=true, however, note that mutations still require the token to determine the user (however permissions will not be checked).
Depends on api-common

Configuration​

Spring propertyDefault valueDescription
gropius.api.public.debugNoAuthenticationfalseIf true, authorization is disabled
gropius.api.public.jwtSecret- (required)Secret for JWT validation. Caution: value is interpreted as Base64 encoded string!

Configuration for Spring Data Neo4j is required.

Requirements​

  • Java >= 17

Runtime Dependencies​

  • Neo4j database

Run​

./gradlew api-public:bootRun

api-internal​

The internal GraphQL API of the backend. MUST NOT be publicly exposed as no authentication or authorization is done. Can be horizontally scaled. If the gropius.api.internal.apiToken config property is set, users have to be authenticated using the Authorization-Header:

Authorization: Bearer token

Depends on api-common

Configuration​

NameDefault valueDescription
gropius.api.internal.apiTokenIf provided, each GraphQL request must provide the token in the Authorization header

Configuration for Spring Data Neo4j is required.

Requirements​

  • Java >= 17

Runtime Dependencies​

  • Neo4j database

Run​

./gradlew api-internal:bootRun

login-service​

Nodejs/Nestjs service that does the user management and authentication for the gropius-backend. It will generate tokens for the user to use to identify against the api.

Configuration​

General settings
Environment variableDefault valueDescription
GROPIUS_LOGIN_SPECIFIC_JWT_SECRET- (required)JWT secret used to sign tokens that are not access tokens to the backend. It is recommended to choos a different secret from GROPIUS_INTERNAL_BACKEND_JWT_SECRET to avoid token misuse. Make sure this is a LONG and RANDOM value and NOBONDY knows it. Else they can create valid tokens.
GROPIUS_JWT_ISSUERgropius-loginThe value to put in the issuer field all jwt signed.Can be any value but a unique value is recommended.
GROPIUS_ACCESS_TOKEN_EXPIRATION_TIME_MS600000 (= 10min)The time after which a issued access token for the backend expires and needs to be refreshed.Specify the value in ms.CAUTION: Access tokens can not easily be revoked. Don't make this time too long.
GROPIUS_OAUTH_CODE_EXPIRATION_TIME_MS600000 (= 10min)The time after which an oauth code, issued after finishing the oauth server flow, expires.This is the time a client has between receiving tha callback and fetching the access token.
GROPIUS_REGISTRATION_EXPIRATION_TIME_MS600000 (= 10min)The time after a registration of a new authentication until it expires. This is a time the USER between passing the authentication flow and submitting the registration form in the client.Don't set this too short or users will be frustrated, that they can't complete the registration.
GROPIUS_REGULAR_LOGINS_INACTIVE_EXPIRATION_TIME_MS0The time after which a regular login event (non sync login) will expire and refresh tokens become invalid. The actual time after which the user looses access is quantized by the expiration time of the issued access token. If 0, logins won't expire.
GROPIUS_PERFORM_IMS_USER_SEARCH_ON=LOGIN,REG,REG_SYNCThe authentication events on which a search for yet unlinked ims users will be done. To link them to the authentication and (if present) the gropius user. Comma separated list.
GROPIUS_CLIENT_SECRET_LENGTH48The length (in bytes) of the generated client secrets for the oauth clients.
GROPIUS_LOGIN_LISTEN_PORT3000The port number on which to listen for API requests
Gropius-backend internal API config
Environment variableDefault valueDescription
GROPIUS_INTERNAL_BACKEND_ENDPOINThttp://localhost:8081/graphqlThe full GraphQL-API endpoint URL of the internal backend api (usually ends with /graphql). Remember: If running in docker-compose, you can use the docker service name as hostname.
GROPIUS_INTERNAL_BACKEND_TOKENThe API secret that the internal backend API expects to allow requests. Will be prefixed with "Bearer ".
GROPIUS_INTERNAL_BACKEND_JWT_SECRET- (required)Secret to be used to sign the access tokens that can be used with the backend. Must be the same value as configured in the backend so the tokens are accepted. It is recommended to choos a different secret from GROPIUS_LOGIN_SPECIFIC_JWT_SECRET to avoid token misuse. Make sure this is a LONG and RANDOM value and NOBONDY knows it. Else they can create valid tokens. Caution: value is interpreted as Base64 encoded string!
Database (postgres) configuration
Environment variableDefault valueDescription
GROPIUS_LOGIN_DATABASE_DRIVERpostgresThe database driver to use. Supported values: "postgres" (reccomended) and ("sqlite"). Note: The application relies on postgres specific types and SQL features in some places. The sqlite functionality is UNTESTED. To run the service without a running database (e.g. for api inspection) it is however useful to be able to switch to "sqlite".
GROPIUS_LOGIN_DATABASE_HOSTlocalhostThe hostname of the postgres databas server (remember: docker service names)
GROPIUS_LOGIN_DATABASE_PORT5432The port on which the postgres database is listening
GROPIUS_LOGIN_DATABASE_USERpostgresThe username in the postgres database to use
GROPIUS_LOGIN_DATABASE_PASSWORDpostgresThe password for the user specified above
GROPIUS_LOGIN_DATABASE_DATABASEgropiusFor postgres: Name of the database to use on the server. For sqlite: appended with ".sqlite" this specifies the Database file path
Passport strategies options
Environment variableDefault valueDescription
GROPIUS_PASSPORT_STATE_JWT_ISSUERgropius-login-stateThe issuer to use in JWTs used to preserve state while using a oauth authentication provider. Using a different value than with GROPIUS_JWT_ISSUER is recommended to avoid token misuse.
GROPIUS_BCRYPT_HASH_ROUNDS10The number of rounds to pass to bcrypt when in use (e.g. for auth client secrets, passwords, ...). The actual number of rounds will be 2^GROPIUS_BCRYPT_HASH_ROUNDS.Choosing this wisely is importand. Too low makes the hashes unsecure and too high makes hasing take too long.
Sync-service API settings
Environment variableDefault valueDescription
GROPIUS_LOGIN_SYNC_API_SECRETThe secret that is expected from a sync service client connecting to the sync API prefixed with "Bearer ". Set this to a long and unguessable value to ensure only the sync services can access tha api and request tokens from users.
Entity management

The following section allows creating default strategy instance and user for initialization. If none of the values are set (i.e. if they're commented out), no entity creation will take place.

Parameters for creating a strategy instance. Type and instance cnfig must be given for creation to happen. The config should follow the same rules as when creating through the API.

Environment variableDefault valueDescription
GROPIUS_DEFAULT_STRATEGY_INSTANCE_TYPEuserpassType of the default strategy instance
GROPIUS_DEFAULT_STRATEGY_INSTANCE_CONFIG{}Config of the default strategy instance
GROPIUS_DEFAULT_STRATEGY_INSTANCE_NAMEuserpass-localName of the default strategy instance

Parameters for creating an admin user. Username, displayName and strategy instance name are required for creation to happen. This can only create users for strategies that accept credentials via POST. (i.e. not for oauth, ...). The structure/valiables of the post data must be the same as for the API request. If a user with that username already exists or the credentials aren't unique, the creation will fail.

Environment variableDefault valueDescription
GROPIUS_DEFAULT_USER_USERNAMEadministratorName of the default user
GROPIUS_DEFAULT_USER_DISPLAYNAMESystem-AdminDisplay name of the default user
GROPIUS_DEFAULT_USER_POST_DATA{"password": "admin"}Credentials for the default user that would otherwise have been passed via POST
GROPIUS_DEFAULT_USER_STRATEGY_INSTANCE_NAMEuserpass-localName of the authentication strategy instance used for credential management
Environment variableDefault valueDescription
GROPIUS_DEFAULT_AUTH_CLIENT_NAMEinitial-clientParameter for creating an auth client. If this is set, an auth client with that name and with no requirement for secrets will be created. The clientId of the created/found auth client will be printed to the console on startup.

Requirements​

  • Node >= 16.17.0

Runtime Dependencies​

Run​

# install
./gradlew login-service:npm_install
# run
./gradlew login-service:npm_start

github​

Github sync that executes exactly one sync cycle. May not be executed more than once at the same time. Documentation about the concept can be found here.
Depends on sync

Configuration​

Spring propertyDefault valueDescription
gropius.sync.github.maxMutationCount100Maximum number of Mutations per cycle that are allowed for one IMS

Configuration for sync, Spring Data Neo4j and Spring Data MonoDB is required.

Requirements​

  • Java >= 17

Runtime Dependencies​

Run​

./gradlew github:bootRun

Abstract Modules

core​

The core part of the Gropius backend, contains the domain model as well as service and repository classes.
Requires a Neo4j database, for the configuration see Configure the project.

Configuration​

Configuration for Spring Data Neo4j is required.

Requirements​

  • Java >= 17

Runtime Dependencies​

  • Neo4j database

api-common​

Contains common functionality for api-public and api-internal.
By default, the API is provided on port 8080 at the endpoint /graphql, a GraphiQL can be found at /graphiql. For the configuration of the GraphQL endpoints, see Configuration Properties.
Depends on core

Configuration​

Configuration for Spring Data Neo4j is required.

Requirements​

  • Java >= 17

Runtime Dependencies​

  • Neo4j database

sync​

Contains abstract helpers for general sync development.
Depends on core

Configuration​

Spring propertyDefault valueDescription
gropius.sync.loginServiceBase- (required)Base url of the login service
gropius.sync.apiSecret- (required)Secret for login service

Configuration for Spring Data Neo4j is required.

Requirements​

  • Java >= 17

Runtime Dependencies​