UseId Backend Service

Kotlin service built with the Spring Web MVC stack.

UseId project

Important: This project has been discontinued ​ This repository is part of the UseId project, that provided the BundesIdent mobile app. You can find other repositories related to this project in the following list: ​

• Architecture
  • Architecture: Documentation and overview of the UseId architecture
• Backend
  • Backend: Kotlin service that acts as the backend for the mobile apps and eID-Service integration for eServices.
• eService
  • eService-example: An example application for an eService integrating with the UseId identity solution.
  • eService-SDK: Javascript SDK to easily integrate with the UseId identity solution.
• eID client (mobile app)
  • iOS client for BundesIdent
  • Android client for BundesIdent
  • AusweisApp2 Wrapper iOS: Forked repository of the Governikus AusweisApp2 Wrapper for iOS

Prerequisites

Kotlin 1.8 w/ Java 17, Docker for building and running the containerized application:

brew install openjdk@17
brew install --cask docker # or just `brew install docker` if you don't want the Desktop app

For the provided Git hooks you will need:

brew install lefthook node

Getting started

To get started with development run:

./run.sh init

This will replace placeholders in the application template and install a couple of Git hooks.

Run locally

To run the application locally, a local PostgreSQL database is required.

To spin up the database run:

docker-compose up -d

To start the application locally run:

You need to set the environment variable TRACKING_MATOMO_DOMAIN.

./gradlew bootRun --args='--spring.profiles.active=local'

Tests

The project has distinct unit and integration test sets.

To run just the unit tests:

./gradlew test

To run the integration tests:

./gradlew integrationTest

Note: Running integration tests requires passing unit tests (in Gradle terms: integration tests depend on unit tests), so unit tests are going to be run first. In case there are failing unit tests we won't attempt to continue running any integration tests.

To run integration tests exclusively, without the unit test dependency:

./gradlew integrationTest --exclude-task test

Denoting an integration test is accomplished by using a JUnit 5 tag annotation: @Tag("integration").

Furthermore, there is another type of test worth mentioning. We're using ArchUnit for ensuring certain architectural characteristics, for instance making sure that there are no cyclic dependencies.

Contributing

Everyone is welcome to contribute the development of this project. You can contribute by opening pull request, providing documentation or answering questions or giving feedback. Please always follow the guidelines and our Code of Conduct.

Contributing code

Open a pull request with your changes and it will be reviewed by someone from the team. When you submit a pull request, you declare that you have the right to license your contribution to the DigitalService and the community. By submitting the patch, you agree that your contributions are licensed under the MIT license.

Please make sure that your changes have been tested before submitting a pull request.

Formatting & Linting

For linting and formatting Kotlin code ktlint is used.

Consistent formatting for Kotlin, as well as various other types of source code (JSON, Markdown, Yaml, ...), is being enforced via Spotless.

Check formatting:

./gradlew spotlessCheck

Autoformat sources:

./gradlew spotlessApply

IntelliJ IDEA setup

See https://github.com/pinterest/ktlint#-with-intellij-idea

brew install ktlint
ktlint applyToIDEAProject

Git hooks

The repo contains a Lefthook configuration, providing a Git hooks setup out of the box.

To install these hooks, run:

./run.sh init

The hooks are supposed to help you to:

• commit properly formatted source code only (and not break the build otherwise)
• write conventional commit messages
• not accidentally push secrets and sensitive information

Code quality analysis

Continuous code quality analysis is performed in the pipeline upon pushing to trunk; it requires a token provided as SONAR_TOKEN repository secret that needs to be obtained from https://sonarcloud.io.

To run the analysis locally:

SONAR_TOKEN=[sonar-token] ./gradlew sonarqube

Go to https://sonarcloud.io for the analysis results.

Container image

Container images running the application are automatically published by the pipeline to the GitHub Packages Container registry .

To run the latest published image:

docker run -p8080:8080 "ghcr.io/digitalservicebund/useid-backend-service:$(git log -1 origin/main --format='%H')"

The service will be accessible at http://localhost:8080.

We are using Spring's built-in support for producing an optimized container image:

./gradlew bootBuildImage
docker run --name useid-backend-service -e "SPRING_PROFILES_ACTIVE=local" --network="host" -d ghcr.io/digitalservicebund/useid-backend-service

Container images in the registry are signed with keyless signatures.

To verify an image:

cosign verify "ghcr.io/digitalservicebund/useid-backend-service:$(git log -1 origin/main --format='%H')"

If you need to push a new container image to the registry manually there are two ways to do this:

Via built-in Gradle task:

export CONTAINER_REGISTRY=ghcr.io
export CONTAINER_IMAGE_NAME=digitalservicebund/useid-backend-service
export CONTAINER_IMAGE_VERSION="$(git log -1 --format='%H')"
CONTAINER_REGISTRY_USER=[github-user] CONTAINER_REGISTRY_PASSWORD=[github-token] ./gradlew bootBuildImage --publishImage

Note: Make sure you're using a GitHub token with the necessary write:packages scope for this to work.

Using Docker:

echo [github-token] | docker login ghcr.io -u [github-user] --password-stdin
docker push "ghcr.io/digitalservicebund/useid-backend-service:$(git log -1 --format='%H')"

Note: Make sure you're using a GitHub token with the necessary write:packages scope for this to work.

Deployment

Changes in trunk are continuously deployed in the pipeline. After the staging deployment, the pipeline runs a verification step in form of journey tests against staging, to ensure we can safely proceed with deploying to production.

Denoting a journey test is accomplished by using a JUnit 5 tag annotation: @Tag("journey"). Journey tests are excluded from unit and integration test sets.

To run the journey tests:

STAGING_URL=[staging-url] && STAGING_API_KEY=[staging-api-key] ./gradlew journeyTest

When omitting the STAGING_URL and STAGING_API_KEY env variable journey tests run against the local spring application.

Deploy specific commits or branches to staging

If you want to deploy a different commit than the latest to main to staging(e.g. for testing purposes), you can use the custom Github Actions. First you need to run the Build image workflow manually here. You have to reference the branch or commit you want to base the image on and give a name to the resulting image. After you have built the image, you can deploy it to staging using the Deploy staging action here. You have to use the same image name as before.

Vulnerability Scanning

Scanning container images for vulnerabilities is performed with Trivy as part of the pipeline's build job, as well as each night for the latest published image in the container repository.

To run a scan locally:

Install Trivy:

brew install aquasecurity/trivy/trivy

./gradlew bootBuildImage
trivy image --severity HIGH,CRITICAL ghcr.io/digitalservicebund/useid-backend-service:latest

License Scanning

License scanning is performed as part of the pipeline's build job. Whenever a production dependency is being added with a yet unknown license the build is going to fail.

To run a scan locally:

./gradlew checkLicense

Architecture Decision Records

Architecture decisions are kept in the docs/adr directory. For adding new records install the adr-tools package:

brew install adr-tools

See https://github.com/npryce/adr-tools regarding usage.

Slack notifications

Opt in to CI posting notifications for failing jobs to a particular Slack channel by setting a repository secret with the name SLACK_WEBHOOK_URL, containing a url for Incoming Webhooks.

API documentation

• Production:
  • Swagger UI
  • JSON
• Staging:
  • Swagger UI
  • JSON
• Local
  • Swagger UI
  • JSON

Note: Prototype Code

This repository includes code used only for a prototype version of the widget. The code is tagged with // PROTOTYPE comments.

Find more details about the prototype in this proposal for a device switch.