You need leiningen and a recent JDK (preferably OpenJDK to build the application.
The clojure/java library dependencies will be automatically downloaded when needed by leiningen.
Start the REPL connect your IDE, or run
lein repl
To start the service from the REPL, type (start!) at the REPL
prompt. Use (restart!) to reload code changes and restart the
service.
Default url is http://localhost:8080/
The service can be build as a standalone jar:
lein uberjar
This will generate
target/uberjar/ooapi-gateway-configurator.jar.
You will need only a JVM (no leiningen) to run the jar:
java -jar target/uberjar/ooapi-gateway-configurator.jar
This application is mostly configured using environment variables.
The hostname that the web server binds to. Default is "localhost"
The port that the web server binds to. Default is "8080"
The OIDC authorize URI to use for initiating an authorization flow.
For testing, this should be set to "https://connect.test.surfconext.nl/oidc/authorize". In production, "https://connect.surfconext.nl/oidc/authorize" should be used.
The OIDC token endpoint to use.
For testing, this should be set to "https://connect.test.surfconext.nl/oidc/token". In production, "https://connect.surfconext.nl/oidc/token" should be used.
The OIDC client ID to use. This should be "ooapi-gateway-configurator.surf.nl"
The OIDC client secret.
The OIDC userinfo_endpoint to use.
For testing, this should be set to "https://connect.test.surfconext.nl/oidc/userinfo". In production, "https://connect.surfconext.nl/oidc/userinfo" should be used.
The callback URI that will be passed to the OIDC server. Make sure this URI points to the "/oauth2/conext/callback" endpoint.
The default is "/oauth2/conext/callback", which will be resolved to a full URL based on the request that starts the authentication process.
The default will not work when the configurator service is behind a TLS terminating proxy and you need the redirect to use HTTPS. You then have to specify a full URL to ensure a matching hostname and scheme, like "https://manage.test.gateway.eduapi.nl/oauth2/conext/callback"
A comma separated list of Conext group ids (urns). Access to the application is granted to users who are members of any of the groups.
For testing, you can use "urn:collab:group:test.surfconext.nl:nl:surfnet:diensten:beta"
The path to the gateway configuration file. This file must exist and be readable and writable for the application process.
Path to a file containing a 192 bit hexadecimal secret used for encoding and decoding proxy options.
The name of the pipeline to be configured in the gateway configuration file.
Directory where backups and staging information is kept. This
directory needs to exist, be writable and persist through restarts and
reboots. When left unset, the same directory as that of
GATEWAY_CONFIG_YAML will be used.
Note: the gateway itself does not need access to this directory.
Versions are listed with the date and time they are deployed. By
default the system timezone is used to display these timestamps. Use
the TZ variable to override this setting.
Note: this is a POSIX environment variable which the JVM honors.
Logging uses logback. There is an
example configuration in dev/logback.xml, which is loaded in
development. When running the configurator jar (in production) you can
specify a logback config file by using
java -Dlogback.configurationFile=/path/to/logback.xml \
-jar target/uberjar/ooapi-gateway-configurator.jar
In production we aggregate logs (from gateway, configurator and supporting infrastructure) in Graylog. The ooapi-configurator repository contains an development setup in dev/observability containing a docker-compose.yml and supporting configuration files that set up Graylog, Prometheus, and fluentd in a docker network called "observability".
Any docker container running in dev can then use the fluentd docker
logging driver to send console output to Graylog. The
development docker-compose.yml has this entry
to set that up:
logging:
driver: "fluentd"
options:
fluentd-address: localhost:24224
tag: docker.configurator
Not that we tag the logging with docker.configurator so that we
process the configurator messages separately, see below.
The development Dockerfile for this application
installs ./configurator.production.logback.xml as the logback
configuration. This sets up JSON-formatted output for all log
messages. The generated JSON data does not contain the required
properties for GELF messages, so some translation is necessary. In
development, we used a fluentd configuration file for
docker.
That contains the following relevant entries specifically for logback JSON to GELF translation:
# Settings for parsing logback JSON logs
# logback uses "message" for the message, but "short_message" is
# required.
[FILTER]
Name modify
Match docker.configurator
Hard_rename message short_message
# Timestamp in json log is confusing graylog and we're already
# receiving a timestamp from docker.
[FILTER]
Name modify
Match docker.configurator
Remove timestamp
# MDC is the Java logging context, pass along all the keys
[FILTER]
Name nest
Match docker.configurator
Operation lift
Nested_under mdc
Note that these entries match the docker.configurator tag mentioned
above.
If you have found a vulnerability in the code, we would like to hear about it so that we can take appropriate measures as quickly as possible. We are keen to cooperate with you to protect users and systems better. See https://www.surf.nl/.well-known/security.txt for information on how to report vulnerabilities responsibly.
Copyright (C) 2021 - 2023 SURFnet B.V.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.