This repository is for the OZG application room.
Getting Started
Reference Documentation
For further reference, please consider the following sections:
- Spring Boot Gradle Plugin Reference Guide
- Create an OCI image
- gRPC
- Spring Boot Actuator
- Spring Boot Web
- springdoc-openapi
- Spring Boot DevTools
- Spring Security SAML2
Guides
The following guides illustrate how to use some features:
- Building an Application with Spring Boot
- Building a RESTful Web Service with Spring Boot Actuator
- Validating Form Input
- Documenting a Spring REST API Using OpenAPI 3.0
- gRPC-Spring-Boot-Starter Documentation
- SAML with Spring Boot and Spring Security
- Technical Dokumentation
Healthchecks are available at:
The info endpoint also contains the build information.
REST Interface Dokumentation is available by using OpenAPI V3
When the application is running you can access the swagger page at
http://localhost:8080/swagger-ui/index.html
Run the application
There are three profiles:
- default - The profile for production environment
- local - The profile for dev stages with connection to the info-manager
- lasttest - The profile for running lasttests
You can start the application by command line by using
./mvnw spring-boot:run -Dspring-boot.run.profiles=local
To change the local port of the management api you can use
./mvnw spring-boot:run -Dmanagement.server.port=8081
or with docker compose by using something like:
ozg-applicationroom:
image: docker.ozg-sh.de/antragsraum-server:OZG-4803-0.1.0-SNAPSHOT
platform: linux/amd64
environment:
- SPRING_PROFILES_ACTIVE=local
- MANAGEMENT_SERVER_PORT=8081
ozg-info-manager:
image: docker.ozg-sh.de/info-manager:OZG-4804-0.1.0-SNAPSHOT
platform: linux/amd64
environment:
- SPRING_DATA_MONGODB_HOST=ozg-mongodb
- SPRING_PROFILES_ACTIVE=local
- MANAGEMENT_SERVER_PORT=8084
ozg-mongodb:
image: mongo:4
ports:
- "27017:27017"
environment:
- MONGODB_EXTRA_FLAGS=--profile=2
volumes:
- mongodb-data:/data/db
Setting
Important settings
grpc:
client:
info_manager:
address: static://127.0.0.1:9090 # The address of the InfoManager
negotiation-type: PLAINTEXT # The negotiation type.
clamav:
scanUrl: http://127.0.0.1:3000/api/v1/scan # The REST endpoint for virus scans
ozgcloud:
code:
expire:
seconds: 30 # Time in seconds after the login code expires
jwt:
secret: "346593nbdgb8e74t6vw477q34bg83456§$%/&Hgvt78hlsjdgfw8äy.skeiw44tz asjkdefa wlfugwegw"
# Secret of signing the Jwt Token provided to the front end.
antragsraum:
logoutSuccessUrl: "http://localhost:8082/?logout" # The redirect url after a logout
authOrigins: # the access-allow-oring setting for the authentication endpoints
- "http://localhost:8082"
- "http://localhost:8080"
apiOrigins: # the access-allow-oring setting for the rest endpoints
- "http://localhost:8082"
otherOrigins: # the access-allow-oring setting for other path like static files etc.
- "http://localhost:8082"
The setting regarding the BayernId configuration are documented here BayernId Implementation and configuration
On dev a Keycloak is used als replacement for the BayernId. For the setup of the Keycloak and the test users configured see here Keycloak Configuration
Note: The InfoManager needs have the same value for the Jwt secret configured, so the InfoManager can verify the Tokens send in the gRPC metadata JWT_TOKEN field. Must be at least 256 bit long
Useful Tools
grpcurl
A tool to end requests to a grpc service. Available here
Examples:
Save NachrichtEvent into the InfoManager database
./grpcurl --plaintext -d '{"nachricht": {"postfachId": "28721c6f-b78f-4d5c-a048-19fd2fc429d2", "vorgangId":"6358fd0bee7a051389cdd787", "nachrichtId":"6358fd4146811d04010f44d1", "nachrichtenListUrl":"static://localhost:9090"}}' localhost:9091 de.mgm.bup.ozg.antragsraum.infomanager.NachrichtService.SaveNewNachricht
Query the InfoManager for available services
./grpcurl --plaintext localhost:9091 list
curl
A commandline too to perform http requests.
Examples:
Upload a file to the Antragsraum backend. Where 6358fd0bee7a051389cdd787 is the id of the Vorgang and 6358fd4146811d04010f44d1 is the id of the Nachricht
curl -F file=@</path/to/the/file/file_name> http://localhost:8080/api/file/6358fd0bee7a051389cdd787/6358fd4146811d04010f44d1 -v
Ports used
Local Dev environment:
Port | Application/Service | Addresses |
---|---|---|
8080 | Antragsraum REST Services | http://localhost:8080/ |
8082 | Frontend | http://localhost:8082/ |
8083 | Antragsraum Actuator | http://localhost:8083/actuator |
8084 | Infomanager Actuator | http://localhost:8084/actuator |
9091 | Infomanager GRPC Service | |
27027 | MongoDB |
Only the SAML Login against the Keycloak can be used for local development.
For local development there are stubs of the VorgangManager APIs available.
To enable it the local profile must be used. This uses the settings defined in the application-local.yml file. Within this file following must be configured:
grpc:
client:
info_manager:
address: static://127.0.0.1:9091
negotiation-type: PLAINTEXT
ozg_service:
stubs:
enabled: true
grpc:
client:
negotiation-type: PLAINTEXT
spring:
security:
saml2:
relyingparty:
registration:
bayernid:
entity-id: "https://sso.dev.by.ozg-cloud.de/realms/by-antragsraum-idp"
signing:
credentials:
- private-key-location: "classpath:/bayernid-dev-sign.key"
certificate-location: "classpath:/bayernid-dev-sign.crt"
decryption:
credentials:
- private-key-location: "classpath:/bayernid-dev-sign.key"
certificate-location: "classpath:/bayernid-dev-sign.crt"
assertingparty:
singlesignon:
sign-request: true
metadata-uri: "https://sso.dev.by.ozg-cloud.de/realms/by-antragsraum-idp/protocol/saml/descriptor"
Then you can use the user 'test' with the password 'test' to login.
Whe using the local Profile the redirect url in the antragsraum-client must be configured to http://localhost:8080/login
More Information
Load Test Tools
mujina idp
Mujina is an SAML2 IdentityProvider for testing and if fully configurable using a REST Interface. In this project the mujina IDP is used for the load tests. Encryption of assertions is not supported.
To use build the container and to use it following steps are necessary:
- Clone the repository https://github.com/OpenConext/Mujina
- build the container using maven in the directory mujina-idp.
mvn spring-boot:build-image -DskipTests
- Tag the image
docker tag mujina-idp:8.0.11 docker.ozg-sh.de/mujina-idp:8.0.11
- Push the image
docker push docker.ozg-sh.de/mujina-idp:8.0.11