SPID/CIE OIDC Federation SDK

CI build Python version py-versions

SPID/CIE OIDC Federation is a suite of Django applications designed to make it easy to build an Openid Connect Federation, each of these can be installed separately within a django project. These are the following:

Application	Description
spid_cie_oidc.accounts	Customizable application that extends the django User model.
spid_cie_oidc.entity	OpenID Connect Federation django app that implements OIDC Federation 1.0 Entity Statements, metadata discovery, Trust Chain, Trust Marks and Metadata policy. Technical specifications: OIDC Federation Entity
spid_cie_oidc.authority	OpenID Connect Federation API and models for OIDC Federation Trust Chain/Intermediate, Technical specifications and tutorial.
spid_cie_oidc.onboarding	OpenID Connect Federation onboarding demo service and tools
spid_cie_oidc.relying_party	OpenID Connect Relying Party and test suite for OIDC Providers
spid_cie_oidc.provider	OpenID Connect Provider and test suite for OIDC Relying Parties

Summary

Features
Setup
Docker
Usage
OpenAPI Schema 3
Tools
Contribute
- Contribute as end user
- Contribute as developer
Implementations notes
License and Authors

RP Auth demo An onboarded Relying Party with a succesful authentication.

Setup

All the Django apps are available in the folder spid_cie_oidc/. The examples projects are available in the folder examples/.

There is a substantial difference between an app and a project. The app is installed using a common python package manager, such as poetry or pip, and can be used, inherited, and integrated into other projects.

A project is a service configuration that integrates one or more applications. In this repository we have three example projects:

federation_authority
relying_party
provider

Federation Authority loads all the applications for development needs, acting as both authority, SPID RP and SPID OP. This allows us to make a demo by starting a single service. See admin page http://127.0.0.1:8000/admin/ and user login page http://127.0.0.1:8000/oidc/rp/landing/.

Then we have also another Relying Party, as indipendent project, and another Provider configured with the CIE profile. Relying party and Provider are examples that only integrate spid_cie_oidc.entity and spid_cie_oidc.provider or .relying_party as applications.

Read the setup documentation to get started.

Docker

Docker image

docker pull ghcr.io/italia/spid-cie-oidc-django:latest

Docker compose

Please do your customizations in each settingslocal.py files and/or in the example dumps json file.

Change hostnames from 127.0.0.1 to which one configured in the compose file, in the settingslocal.py files and in the dumps/example.json files. In our example we rename:

We can do that with the following steps:

Execute bash docker-prepare.sh
Customize the example data and settings contained in examples-docker/ if needed (not necessary for a quick demo)

Run the stack

sudo docker-compose up

Configure a proper DNS resolution for trust-anchor.org. In GNU/Linux we can configure it in /etc/hosts:

127.0.0.1   localhost  trust-anchor.org relying-party.org cie-provider.org wallet.trust-anchor.org

Point your web browser to http://relying-party.org:8001/oidc/rp/landing and do your first oidc authentication.

Usage

The demo proposes a small federation composed by the following entities:

Federation Authority, acts as trust anchor and onboarding system. It's available at http://127.0.0.1:8000/. It has also an embedded Spid provider and a embedded Relying Party available at /oidc/rp/landing.
OpenID Relying Party, available at http://127.0.0.1:8001/
CIE OpenID Provider, available at http://127.0.0.1:8002/

In the docker example we have only the Federation Authority with an embedded SPID OP and a RP.

Examples Users and Passwords:

admin oidcadmin
user oidcuser

OpenAPI Schema 3

Each application has an exportable OAS3 available at /rest/schema.json with a browsable reDoc UI at /rest/api/docs.

RP Auth demo The reDoc OAS3 browsable page.

Tools

The OnBoarding app comes with the following collection of tools:

JWK
- Create a jwk
- Convert a private JWK to PEM
- Convert a public JWK to PEM
- Convert a private PEM to JWK
- Convert a public PEM to JWK
- JWT decode and verification
Federation
- Resolve entity statement
- Apply policy
Validators
- Validate OP metadata spid
- Validate OP metadata cie
- Validate RP metadata spid
- Validate RP metadata cie
- Validate Authn Request spid
- Validate Authn Request cie
- Validate Entity Configuration
- Trust mark validation
Schemas
- Authorization Endpoint
- Introspection Endpoint
- Metadata
- Token Endpoint
- Revocation Endpoint
- Jwt client Assertion

OIDC tools facilitates the lives of developers and service operators, here a simple interface to decode and verify a JWT.

To explore a federation on the commandline, use the ofcli tool. It can be used to export federation metadata to json files for further analysis.

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 discoveerd 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.

Backup and share your demo data

# backup your data (upgrade example data), -e excludes.
./manage.py dumpdata -e admin -e spid_cie_oidc_relying_party -e spid_cie_oidc_provider -e spid_cie_oidc_relying_party_test -e auth -e contenttypes -e sessions --indent 2 > dumps/example.json

In this project we adopt Semver and Conventional commits specifications.

Implementation notes

All the operation related to JWT signature and encryption are built on top of IdentityPython cryptojwt

This project proposes an implementation of the italian OIDC Federation profile with automatic_client_registration and the adoption of the trust marks as mandatory.

If you're looking for a fully compliant implementation of OIDC Federation 1.0, with a full support of explicit client registration, please look at idpy's fedservice.

General Features

SPID and CIE OpenID Connect Provider
SPID and CIE OpenID Connect Relying Party
OIDC Federation onboarding demo service
OIDC Federation 1.0
- Trust Anchor and Intermediary
- Automatic client registration
- Entity profiles and Trust marks
- Trust chain storage and discovery
- Entity statement resolve endpoint
- Fetch statement endpoing
- List entities endpoint
- Advanced List endpoint
- Federation CLI
  - RP: build trust chains for all the available OPs
  - OP: build trust chains for all the available RPs
Multitenancy, a single service can configure many entities like RPs, OP, Trust Anchors and intermediaries
gettext compliant (i18n)
Bootstrap Italia Design templates

License and Authors

This software is released under the Apache 2 License by:

Giuseppe De Marco gi.demarco@innovazione.gov.it.

In this project we use the metadata policy code written by Roland Hedberg and licensed under the same Apache 2 license.

Metadata

Release files for spid-cie-oidc 1.6.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spid-cie-oidc 1.6.3
File	Size	Uploaded
spid_cie_oidc-1.6.3.tar.gz	404.6 kB	Mar 23, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spid-cie-oidc 1.6.3
File	Interpreter	ABI	Platform	Reset
spid_cie_oidc-1.6.3-py3-none-any.whl 518.3 kB Mar 23, 2026	Python 3	none	any	Details

Total release size: 923.0 kB

Release files / spid_cie_oidc-1.6.3.tar.gz

Download URL	spid_cie_oidc-1.6.3.tar.gz
Size	404.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`7fb4ac1553dcd94b5158de49404b77ba633ce849286506763e2c27434201874e`
BLAKE2b-256 checksum How to use checksums	`203d748d6ebdd541a79bf6f955110ee279f8013d5a0720c6e5d85cbd2a00f164`
Upload date	Mar 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Release files / spid_cie_oidc-1.6.3-py3-none-any.whl

Download URL	spid_cie_oidc-1.6.3-py3-none-any.whl
Size	518.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`01a951e27aaa461401f232a2212ab2c83e8f9462dbb0133974a637d3e9ddf8f1`
BLAKE2b-256 checksum How to use checksums	`19c60636329bda0614cc688c3f253978e38b17864f5de1163a564eda61d1d65e`
Upload date	Mar 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.7`