Version 1.0.0

README.md

@@ -1,11 +1,79 @@
 # HA-AuthCode-Generation-Service (CovidCode-Service)
 HA-AuthCode-Generation-Service is an authorization code generation service for the CovidCode-UI and the proximity tracing app.
 
+# Developer Instructions
+
+## Initial setup
+
+Do this once:
+
+1. Install a JDK (tested with Oracle JDK v11 and OpenjDK 1.8.0)
+1. [Install Maven](https://maven.apache.org/install.html)
+1. Install [Docker](https://docs.docker.com/get-docker/) and [docker-compose](https://docs.docker.com/compose/install/)
+1. Check out [CovidCode-UI](https://github.com/admin-ch/CovidCode-UI) in another directory
+
+## Development Cycle
+
+Do this at the beginning of your session:
+1. Run <pre>docker-compose up -d
+docker-compose logs -f</pre> and wait for the logs to become quiescent
+1. Run CovidCode-UI in another window (`ng serve`)
+
+To run manual tests, you can run CovidCode-Service with the `local`
+and `keycloak-local` Spring profiles using the following command:
+```
+mvn compile exec:java
+```
+(or the equivalent using your IDE's Maven functionality, if you
+require access to a debugger)
+
+To run the test suite:
+```
+mvn verify
+```
+
+To perform a clean build, and run the test suite with full code coverage
+and upload the data to a locally-running SonarQube:
+```
+mvn clean org.jacoco:jacoco-maven-plugin:prepare-agent verify sonar:sonar
+```
+SonarQube results are thereafter visible at http://localhost:9000/
+
+To tear down the development support environment (but retain its state on-disk):
+```
+docker-compose down
+```
+
+To wipe everything:
+```
+docker-compose down
+docker volume rm covidcode_dbdata
+mvn clean
+```
+
 ## Swagger-UI
 Swagger-UI is running on http://localhost:8113/swagger-ui.html.
 
+## Local KeyCloak instance
+
+If CovidCode-Service is being run as suggested above, it will perform
+authentication and access control against an OIDC / OAuth server
+running on http://localhost:8180/ (and so will CovidCode-UI in its
+default development configuration).
+
+The credentials for the KeyCloak administrator are visible in
+docker-compose.yml in section `keycloak:`. Additionally, KeyCloak is
+automatically pre-populated with a `bag-pts` realm, containing a
+`doctor` account (password `doctor`) that enjoys access to both
+CovidCode-UI and CovidCode-Service.
+
 ## PostgreSQL database
-To start up the application locally, run a new PostgreSQL 11+ database on port 3113. Use the profile "local" to run the application.
+
+docker-compose runs a new PostgreSQL database on port 3113 and takes
+care of setting it up. The superuser credentials are in
+`docker-compose.yml`.
+
+The "local" Spring profile should be used to run the application (see above).
 The other profiles run the script afterMigrate to reassign the owner of the objects.
 
 ### Dockerfile

devsupport/haauthcodegeneration/create-database-and-user.sql

@@ -0,0 +1,7 @@
+CREATE DATABASE haauthcodegeneration;
+CREATE USER haauthcodegeneration WITH PASSWORD 'secret';
+ALTER USER haauthcodegeneration WITH SUPERUSER;
+GRANT ALL ON DATABASE haauthcodegeneration TO haauthcodegeneration;
+
+CREATE ROLE haauthcodegeneration_role_full;
+GRANT ALL ON DATABASE haauthcodegeneration TO haauthcodegeneration_role_full;

devsupport/keycloak/create-database-and-user.sql

@@ -0,0 +1,3 @@
+CREATE DATABASE keycloak;
+CREATE USER keycloak WITH PASSWORD 'keycloak';
+GRANT ALL ON DATABASE keycloak TO keycloak;

devsupport/keycloak/realm-bag-pts-localhost.json

@@ -0,0 +1,80 @@
+{
+  "id": "BAG-PTS",
+  "realm": "bag-pts",
+  "enabled": true,
+  "clients": [
+    {
+      "clientId": "ha-ui-web-client",
+      "rootUrl": "https://www.covidcode-d.admin.ch",
+      "adminUrl": "",
+      "publicClient": true,
+      "surrogateAuthRequired": false,
+      "enabled": true,
+      "redirectUris": [
+        "http://localhost:4200/*"
+      ],
+      "webOrigins": [
+        "http://localhost:4200"
+      ],
+      "protocolMappers": [
+        {
+          "id": "showRolesInUserinfoAsUserroles",
+          "name": "Realm Mapper",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-usermodel-realm-role-mapper",
+          "consentRequired": false,
+          "config": {
+            "usermodel.clientRoleMapping.rolePrefix": "bag-pts-",
+            "multivalued": "true",
+            "userinfo.token.claim": "true",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "userroles",
+            "jsonType.label": "String"
+          }
+        },
+        {
+          "id": "hardcodedCtxClaim",
+          "name": "Context Claim",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-hardcoded-claim-mapper",
+          "consentRequired": false,
+          "config": {
+            "userinfo.token.claim": "false",
+            "id.token.claim": "true",
+            "access.token.claim": "true",
+            "claim.name": "ctx",
+            "claim.value": "USER",
+            "jsonType.label": "String"
+          }
+        }
+      ]
+    }
+  ],
+  "roles": {
+    "realm": [
+      {
+        "name": "bag-pts-allow",
+        "description": "Grant this role to users, so that they can use ha-ui",
+        "composite": false,
+        "clientRole": false,
+        "containerId": "BAG-PTS",
+        "attributes": {}
+      }
+    ]
+  },
+  "users" : [
+    {
+      "username" : "doctor",
+      "enabled": true,
+      "email" : "doctor@example.com",
+      "firstName": "Doctor",
+      "lastName": "Example",
+      "credentials" : [
+        { "type" : "password",
+          "value" : "doctor" }
+      ],
+      "realmRoles": [ "bag-pts-allow" ]
+    }
+  ]
+}

docker-compose.yml

@@ -0,0 +1,88 @@
+# docker-compose.yml for developer support
+#
+# Usage:
+#
+#  docker-compose up -d
+#
+# Port allocation scheme:
+#   3113    The PostgreSQL database
+#   4200    The Angular UI (not part of this project)
+#   8113    The covidcode back-end server (not managed by docker-compose)
+#   8180    The Keycloak server, exposed through Træfik with some URL rewriting
+#   9000    SonarQube, a source code linter and metrics renderer (e.g. for test coverage)
+
+version: "3"
+
+# To purge all state, stop all containers and say
+#
+#    docker volume rm covidcode_dbdata
+#
+# This will erase the PostgreSQL database. Then start everything again
+volumes:
+  dbdata:
+
+services:
+
+  db:
+    image: "postgres:11"
+    container_name: "dp3t_postgres"
+    ports:
+      - "3113:5432"
+    environment:
+      POSTGRES_PASSWORD: secret
+    volumes:
+      - dbdata:/var/lib/postgresql/data
+      - ./devsupport/keycloak/create-database-and-user.sql:/docker-entrypoint-initdb.d/create-keycloak-database-and-user.sql
+      - ./devsupport/haauthcodegeneration/create-database-and-user.sql:/docker-entrypoint-initdb.d/create-haauthcodegeneration-database-and-user.sql
+
+  keycloak:
+    image: jboss/keycloak
+    container_name: "keycloak"
+    environment:
+      # https://hub.docker.com/r/jboss/keycloak
+      KEYCLOAK_USER: admin
+      KEYCLOAK_PASSWORD: masterPassword
+      DB_VENDOR: postgres
+      DB_ADDR: db
+      DB_DATABASE: keycloak
+      DB_USER: keycloak
+      DB_PASSWORD: keycloak
+      KEYCLOAK_IMPORT: /tmp/realm-bag-pts-localhost.json
+    volumes:
+      - ./devsupport/keycloak/realm-bag-pts-localhost.json:/tmp/realm-bag-pts-localhost.json
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.keycloak.entrypoints=web"
+      - "traefik.http.routers.keycloak.rule=PathPrefix(`/`)"  # i.e. accept anything
+      # Rewrite URLs so that e.g.
+      # http://localhost:8180/.well-known/openid-configuration
+      # works (as expected by ha-ui in its dev configuration):
+      - "traefik.http.routers.keycloak.middlewares=rewrite-url-oidc"
+      - "traefik.http.middlewares.rewrite-url-oidc.replacepathregex.regex=^/(\\.well-known/.*)$$"
+      - "traefik.http.middlewares.rewrite-url-oidc.replacepathregex.replacement=/auth/realms/bag-pts/$$1"
+
+  traefik:
+    image: traefik:2.2.1
+    volumes:
+      - "/var/run/docker.sock:/var/run/docker.sock:ro"
+    command:
+      - "--entrypoints.web.address=:80"
+      ## Enable docker provider
+      - "--providers.docker=true"
+      ## Do not expose containers unless explicitly told so
+      - "--providers.docker.exposedbydefault=false"
+      ## Uncomment the following two lines to turn on the Træfik
+      ## dashboard (handy for troubleshooting errors in the
+      ## `traefik.*` labels, above):
+      # - "--api.dashboard=true"
+      # - "--api.insecure=true"
+    ports:
+      - "8180:80"
+      ## Uncomment the following line to expose the Træfik dashboard
+      ## on port 8080:
+      # - "8080:8080"
+
+  sonarqube:
+    image: sonarqube:community
+    ports:
+      - "9000:9000"

pom.xml

@@ -10,7 +10,7 @@
 	</parent>
 	<groupId>ch.admin.bag.covidcode</groupId>
 	<artifactId>ha-authcode-generation-service</artifactId>
-	<version>0.2.1-SNAPSHOT</version>
+	<version>1.0.0-SNAPSHOT</version>
 	<name>ha-authcode-generation-service</name>
 	<description>Service for generating an authorization code for the proximity tracing app</description>
 
@@ -222,6 +222,18 @@
 					<useSystemClassLoader>false</useSystemClassLoader>
 				</configuration>
             </plugin>
+            <!-- Run the server with `mvn exec:java` -->
+            <plugin>
+              <groupId>org.codehaus.mojo</groupId>
+              <artifactId>exec-maven-plugin</artifactId>
+              <version>1.2.1</version>
+              <configuration>
+                <mainClass>ch.admin.bag.covidcode.authcodegeneration.AuthCodeGenerationServiceApplication</mainClass>
+                <arguments>
+                  <argument>--spring.profiles.active=local,keycloak-local</argument>
+                </arguments>
+              </configuration>
+            </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-failsafe-plugin</artifactId>