Under the Working Agenda Value Driven Digitization, the Dutch government is preparing for the introduction of European digital identity wallets (in short ID-wallets) through the revision of the eIDAS-regulation. One of the ways in which they are doing this, is by developing a public reference wallet called the NL Wallet. These ID-wallets will be mobile apps that citizens can use to identify (or ‘log in’) to public and private online services, share data about themselves, and sign electronically.
The first version of the NL Wallet will focus on online identification and data sharing and will be piloted at small scale in 2024. In the future, it may be possible to use such an ID-wallet in a lot of different situations, for example to share your diploma’s when applying for a job, to show your driver’s license, or to prove that you are 18+ to buy a beer.
The NL Wallet is being developed in an open and transparent way. We offer the following channels to allow you to contribute:
Feel free to look around and share your feedback and ideas.
Please note that this code is still experimental and subject to change.
As this project is a work in progress, you will find that the different components are at different levels of maturity. Most notably, the user interface is always a few steps ahead of the software under the hood. To put it simply, we incrementally add functionality to the wallet in three steps:
Once the first version of the app is complete, thoroughly tested and considered secure, we can fill it with real data and pilot it in real life scenarios.
See the releases page for the latest release. You can follow the latest work by subscribing to the releases of this GitHub repository at the top of this page.
TL;DR
With the NL reference wallet we want to achieve the following things:
If you want to learn more about the NL Wallet development, please read the background information on the Pleio hub. The development of the user flows and screens can be followed through Figma.
The source code of the NL Wallet is released under the EUPL license. The documentation is released under the CC0 license. Please see the .reuse/dep5 file for more details, which follows the Reuse specfication.
We’re releasing the source code with the explicit intention of allowing contributions. The coordination of the project lies with the development team of the European Digital Identity Progam, but we’re open to all contributions. You can directly create a new Pull Request via Github, or contact the community manager via edi@minbzk.nl.
The development team works on the repository in a private fork (for reasons of compliance with existing processes) and shares its work as often as possible. If you watch the repository on GitHub, you will be notified of a new release. We will also send a notification through Pleio.
Although we are open to contributions, please consider the nature of this project as outlined in this Readme. At this stage the most useful way to contribute to the project is to participate on our community site edi.pleio.nl, and visit our EDI Meet-ups and/or Heartbeats.
If you plan to make non-trivial changes, we recommend that you open an issue beforehand where we can discuss your planned changes. This increases the chance that we might be able to use your contribution (or it avoids doing work if there are reasons why we wouldn't be able to use it).
Note that all commits should be signed using a GPG key.
This section contains the general setup requirements of the project. For more details on configuration of the wallet app, the wallet core and the wallet_provider, please see the corresponding README files.
The app's UI is build using Flutter, but to avoid tying the app to Flutter & Dart, all core business
logic is build using Rust. This gives us the more flexibility to migrate to completely native
iOS/Android app's if the need arises. This does mean building the app is slightly more complex than
a simple flutter run. This section describes how to set up your environment.
To install Flutter follow this installation guide.
You can validate your initial setup by running flutter doctor.
Easily manage your local Flutter version using: Flutter Version Manager (FVM)
FVM is a simple CLI to manage Flutter SDK versions per project. It enables fast switching between
Flutter versions and pin them to your Flutter project. When using FVM; all Flutter related
command need to be prefixed with fvm, e.g. fvm flutter run.
Optional step:
To install FVM follow this installation guide.
You can validate your initial setup by running fvm flutter doctor after the installations. Hit [Y]es when asked to install the pinned Flutter version defined in fvm_config.json.
Note that FVM only pins the Flutter version for local development, not the CI pipelines.
To install Rust & Cargo (the package manager) follow the installation guide. After installing rust make sure to add the following targets:
rustup target add aarch64-apple-ios x86_64-apple-iosrustup target add aarch64-apple-ios-simrustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-androidTo build for android you need to have the Android SDK and NDK installed on your system. Likely the easiest way to do so is:
export ANDROID_HOME="$HOME/Library/Android/sdk" to your ~/.bash_profile or
~/.zshrc, this will make sure the Android SDK is available in your path and automatically
picks up the NDK version you installed in the previous stepgradle.properties,
e.g. echo "NDK_HOME=\"$HOME/Library/Android/sdk/ndk/{ndk_version}\"" >> ~/.gradle/gradle.propertiescargo install cargo-ndk (>= v3.0.0) to be able to build the Rust code for Android${HOME}/Library/Android/sdk/emulator/emulator -list-avds to list the installed devicesopen -a SimulatorThe Wallet needs several supporting services to run, and also requires the user to log in using DigiD in order to create the Wallet. The services are the following:
Wallet Provider: See wallet_core/wallet_provider/README.md
The Wallet Provider requires a Postgres database.
PID Issuer: See wallet_core/pid_issuer/README.md
Digid Connector: See RDO MAX.
All these applications will need to be configured correctly. A local development environment can be set up using the
scripts/setup-devenv.sh and scripts/start-devenv.sh scripts.
The setup-devenv.sh script will configure the digid-connector to listen on https://localhost:8006/ . Note the https
in the URL, which is provided using self-signed certificates.
Besides that, the development setup runs without using TLS. Therefore, the feature allow_http_return_url enables the
possibility to use a return URL with the scheme http (while normally https is only allowed).
The local wallet can be connected to Sentry for crash and error reporting by setting the SENTRY_DSN environment variable.
Additionally, the wallet crate offers the config_env feature to aid during local development, which does the following:
data.rs can be overridden by an environment variable of the same name at compile time..env in the wallet crate directory, if present.In order to connect to our locally running services from the Android Emulator on the domain localhost, some port
mappings have to be made. Note that this must be done every time the Android Emulator is restarted.
This is automated in the script: scrips/map_android_ports.sh.
The setup-devenv.sh script will automatically run this script when it detects the adb command.
However, when the Android Emulator has been restarted, one can just run map_android_ports.sh.
The individual services of the development environment can be started using start-devenv.sh. Tip: use the --help
commandline option to show the help output
After doing the above flutter doctor should report that at least the following are installed
successfully:
You should now be able to launch an Android Emulator or iOS Simulator and run the app by following these steps:
cd wallet_appflutter pub getflutter run! 🎉In order to run and validate jobs from the GitLab CI locally on a development machine, the gitlab-ci-local tool may be used.
Follow the installation instructions for it here.
The environment variables that are necessary to run the CI jobs need to be specified by copying and populating the example YAML file:
cp .gitlab-ci-local-variables.example.yml .gitlab-ci-local-variables.ymlMake sure that Docker is running and configure it so that containers have a maximum memory size of at least 16GB. Log into Harbor, where the docker images are hosted:
docker login -u <HARBOR USER> -p <HARBOR CLI SECRET> <HARBOR HOSTNAME>Now, any job from GitLab CI can be run localy, e.g.:
gitlab-ci-local test-rustAll Dart code goes in the wallet_app/lib/ directory and their appropriate sub-directories.
All Rust code goes in the wallet_core/ directory and their appropriate sub-directories.
Communication between the Flutter and Rust layers relies on the flutter_rust_bridge package, the bridge code is generated. The definition of this bridge can is located at /wallet_core/src/api.rs and generation is done with the following command:
cargo run --manifest-path wallet_core/flutter_rust_bridge_codegen/Cargo.tomlThe generated code is currently checked in, so that generation only has to be performed when the API changes.
ci- or core-.Example of a branch name: PVW-123-wp-teapot-status-code
See commit message.
Follow these steps to (force) distribute internal alpha & beta builds that target the Android
platform":
Use
Alphadistribution at any time during development cycle.
Use
Betadistribution at the end of a sprint cycle; to represent the sprint demo version.
$ git fetch && git pullmain branch to: beta/v{X.Y.Z}Generate/update localisation files (to compile/run the project successfully):
$ flutter gen-l10n