eudi-wallet-it-python

The eID Wallet Python toolchain is a suite of Python libraries designed to make it easy the implementation of an EUDI Wallet Relying Party according to the Italian Wallet implementation profile.

The toolchain contains the following components:

Name	Description	Documentation
jwk	JSON Web Key (JWK) according to RFC7517.	JWK.md
jwt	Signed and encrypted JSON Web Token (JWT) according to RFC7519, RFC7515 and RFC7516	JWT.md
tools.qrcode	QR codes for cross-device flows (OpenID4VP, OpenID4VCI)	TOOLS-QRCODE.md
oauth2.dpop	Tools for issuing and parsing DPoP artifacts, according to OAuth 2.0 DPoP	OAUTH2-DPOP.md
federation	Trust evaluation mechanisms, according to OpenID Federation 1.0	FEDERATION.md
x509	Trust evaluation mechanism using X.509 PKI, according to RFC5280	X509.md
trust	Trust handlers bringing multiple evaluation mechanisms	TRUST.md
satosa.backend	SATOSA Relying Party backend, according to OpenID for Verifiable Presentations	OPENID4VP-SATOSA-BACKEND.md
satosa.frontend	SATOSA Issuer frontend, according to OpenID for Verifiable Credential Issuance	OPENID4VCI-SATOSA-FRONTEND.md
openid4vp	Classes and schemas related to OpenID for Verifiable Presentations	OPENID4VP.md
openid4vci	Classes and schemas related to OpenID for Verifiable Credential Issuance	OPENID4VCI.md
sd_jwt	Issuance and verification of SD-JWT(-VC) according to Selective Disclosure for JWTs (SD-JWT)	SD-JWT.md
status_list	Credential revocation check mechanisms according to Token Status List	STATUS_LIST.md

Setup

Install enviroment and dependencies

sudo apt install python3-dev python3-pip git
sudo python3 -m pip install --upgrade pip
sudo python3 -m pip install virtualenv

Activate the environment. It's optional and up to you if you want to install in a separate env or system wide

virtualenv -p python3 env
source env/bin/activate

Install using pip:

pip install pyeudiw or pip install pyeudiw[satosa] for the satosa backend.

Install using github:

pip install git+https://github.com/italia/eudi-wallet-it-python

Optionally for generate the documentation you need to install the following packages: pip install sphinx sphinx_rtd_theme

Documentation

The API documentation is available in the githubpages, here.

In the docs/ folder you will find:

• Component-specific guides (usage, examples):
  • JWK
  • JWT
  • SD-JWT
  • OAUTH2 DPoP
  • Federation
  • X509
  • Trust
  • Status List
  • tools.qrcode
  • OpenID4VP
  • OpenID4VCI
• SATOSA setup:
  • OpenID4VP Backend
  • OpenID4VCI Frontend

Build the Documentation

For generate the documentation enter in the terminal the following commands. The last argument is the exclude path, unit tests are then excluded from the API documentation.

cd docs
sphinx-apidoc -o ./source ../pyeudiw ../pyeudiw/tests
make html

Example project

The example project is a docker-compose that runs a demo composed by the following component:

• Wordpress with SAML2 support and Bootstrap Italia template preregistered to the IAM Proxy.
• Satosa-Saml2Spid IAM Proxy with a preconfigured OpenID4VP backend.

Please read this README to get a fully working Wordpress setup with SAML2 support.

SatoSa configuration

SaToSa is a general purpose IAM proxy solution that allows interoperability between different entities that implements different authentication protocols such as SAML2, OpenID Connect and OAuth2. This project offers:

• a SaToSa backend to enable the OpenID4VP protocol;
• a SaToSa frontend to enable the OpenID4VCI protocol.

There is a SaToSa distribution, created by the Developers Italia community, pre-configured to facilitate integration with the Italian National Digital Identity Systems, it is Satosa-Saml2Spid.

Please refer to the dedicate README files for details on how to configure SaToSa with the respective components:

• OpenID4VP Relying Party backend;
• OpenID4VCI Issuer fronted.

Protocol Support Recap

Compliance checklist against the Italian Wallet implementation profile and related OpenID4VCI/OpenID4VP specifications.

OpenID4VCI (Credential Issuer Frontend)

🟢 Supported · 🟠 Partial · 🔴 Not supported

Feature	Status
Pushed Authorization Requests (PAR)	🟢
PAR: reject request_uri in request body (RFC 9126)	🟢
OAuth 2.0 Attestation-Based Client Authentication	🟢
PKCE	🟢
Authorization Code Flow	🟢
DPoP at Token endpoint	🟢
Immediate Issuance	🟢
JWT Proof of Possession (openid4vci-proof+jwt)	🟢
Nonce endpoint (c_nonce)	🟢
Credential Offer (by value and QR code)	🟢
Notification endpoint	🟢
SD-JWT VC credential format	🟢
mso_mdoc credential format	🟢
Refresh Token (DPoP-bound)	🟢
Batch Credential Issuance	🔴
Deferred Issuance Flow	🔴

OpenID4VP (Relying Party Backend)

🟢 Supported · 🟠 Partial · 🔴 Not supported

Feature	Status
DCQL (Duckle) query language	🟢
Same Device flow	🟢
Cross Device flow (QR code)	🟢
Request Object by reference (request_uri)	🟢
Request URI method GET	🟢
Request URI method POST (wallet metadata)	🟢
wallet_metadata and wallet_nonce	🟢
Response mode direct_post.jwt (encrypted)	🟢
Response mode direct_post	🟢
vp_token keyed by credential id	🟢
dc+sd-jwt format	🟢
mso_mdoc format	🟢
Status endpoint (session polling)	🟢
Trust evaluation (X.509 PKI, OpenID Federation)	🟢
Credential revocation (status list)	🟢
Custom URL schemes (haip, configurable)	🟢
transaction_data / transaction_data_hashes	🔴

Executing Tests Using Preexisting MongoDb Instances

Use the env variable PYEUDIW_MONGO_TEST_AUTH_INLINE so tests connect with credentials. CI uses PYEUDIW_MONGO_TEST_AUTH_INLINE="" (MongoDB without auth). For local MongoDB with auth, set it in .env (loaded by ./run_tests.sh) or export it:

PYEUDIW_MONGO_TEST_AUTH_INLINE=satosa:thatpassword@ pytest pyeudiw -x
# or: echo 'PYEUDIW_MONGO_TEST_AUTH_INLINE=satosa:thatpassword@' >> .env && ./run_tests.sh

Contribute

Your contribution is welcome, no question is useless and no answer is obvious, we need you.

Contribute as end user

Please open an issue if you've found a bug or if you want to ask some features.

Contribute as developer

Please open your Pull Requests on the dev branch. Please consider the following branches:

• main: where we merge the code before tag a new stable release.
• dev: where we push our code during development.
• other-custom-name: where a new feature/contribution/bugfix will be handled, revisioned and then merged to dev branch.

Executing Unit Tests

Once you have activate the virtualenv, further dependencies must be installed as show below.

pip install -r requirements-dev.txt

Therefore the unit tests can be executed as show below.

pytest pyeudiw -x

If you test pyeudiw on a development machine where also iam-proxy-italia is running with its mongodb and the same collection names, you can run the test by passing the mon user and password in this way

PYEUDIW_MONGO_TEST_AUTH_INLINE="satosa:thatpassword@" pytest pyeudiw -x

Executing integration tests

iam-proxy-italia project must be configured and in execution.

Integrations tests checks bot hthe cross device flow and the same device flow.

The cross device flow requires playwrite to be installed.

cd examples/satosa/integration_tests

playwrite install

PYEUDIW_MONGO_TEST_AUTH_INLINE="satosa:thatpassword@" pytest pyeudiw -x

External Resources and Tools

• EUDIW Ref Implementation VCI
• EUDIW Ref Implementation RP

Authors

• Giuseppe De Marco

Acknowledgments

• Manuel Pacella
• Manuel Ciofo
• Thomas Chiozzi
• Pasquale De Rose
• Elisa Nicolussi Paolaz
• Salvatore Laiso
• Alessio Murru
• Nicola Saitto
• Sara Longobardi