italia / spid-cie-oidc-django

The SPID/CIE OIDC Federation SDK, written in Python

SPID/CIE OIDC Federation SDK

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

---

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

Install Docker using the packages distributed from the official website and the following tools.

sudo pip install 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:

• http://127.0.0.1:8000 to http://trust-anchor.org:8000/
• http://127.0.0.1:8001 to http://relying-party.org:8001/
• http://127.0.0.1:8002 to http://cie-provider.org:8002/

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.

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 [email protected].

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

spid-cie-oidc-django's Issues

[Feat] Advanced Entity Listing endpoint for TA

A request/response example

this feature MAY be implemented in spid_cie_oidc.authority.

GET /federation_adv_list HTTP/1.1
Host: registry.spid.gov.it

200 OK
Last-Modified: Mon, 17 Dec 2018 11:15:56 GMT
Content-Type: application/json



{
 "iss": "https://registry.spid.gov.it/",
 "iat": 1620050972,
 "entities": [
   {
    "https://rp.example.it/spid/": {
       "iat": 1588455866,
   },
   {
    "https://rp.another.it/spid/": {
       "iat": 1588455856,
   },
   {
    "https://rp.it/spid/": {
       "iat": 1588355866,
   },
   ... # many other entries
 ],
"page": 1,
"total_pages": 2,
"total_entries": 189,
"next_page_path": "/federation_adv_list/?page=2",
"prev_page_path": ""
}

Failed to load example dump for federation_authority example project

at this stage

spid-cie-oidc-django/docs/SETUP.md

Line 69 in 546ba2c

./manage.py loaddata dumps/example.json

following error occurs

django.db.utils.IntegrityError: Problem installing fixtures: The row in table 'spid_cie_oidc_provider_oidcsession' with primary key '1' has an invalid foreign key: spid_cie_oidc_provider_oidcsession.user_id contains a value '1' that does not have a corresponding value in spid_cie_oidc_accounts_user.id.

[Feat] Metadata discovery filter on valid trust marks

A Metadata discovery won't be executed if there wan't at least a valid and verified trust mark in the entity configuration of the requestor

[Feat] Proxy function to get cached Entity Statements in Metadata discovery

We need that all the trust chains and statements validations/operations must be independent from django framework.

This way the code can be used/imported as it is even in a different python framework.

at the same time we MAY support the resuse of already cached statements, instead of download them each time.

this can be done in two different way:

1. pass all the cached entries as argument -> bad
2. create and dynamically import a proxy function that queries the django ORM. This function can be configured as a string in a general setting and imported dynamicall runtime -> good

with the second choice we'll get all the statements on each occurence

[Provider]: User claims in CIE idToken

User claims in idToken as CIE specifications

[Feat] [trust marks] a better generalization for dynamic claims in trust marks templates

We're considering the requirement to improve the mechanism to mint new trust marks with more dynamic claim then these:
https://github.com/peppelinux/spid-cie-oidc-django/blob/49649c2117ecd8fab2dda0bc7a9397030a996795/spid_cie_oidc/onboarding/models.py#L231

we must consider also to have exp claim dynamically defined (this is an easy win)

[Metadata Policy] scopes or scope claim?

https://bitbucket.org/openid/connect/issues/1456/scopes-metadata-parameter-needs-to-be

Trust Chains storage

We have trust chain builder with an inmemory cache

we need a storage mechanism to entity.models.TrustChain

we may serialize the TrustChain().trust_path and also sto the TrustChain().finale_metadata in the model

both RP and OP will query the TrustChain model and only if it were expired they will execute the TrustchainBuilder

Revocation Token Response status code != 200

The endpoint is protected by private key jwt so unattacher can't brute force or predict a refresh token.
Having said this we propose to answer even with other http status code different from 200

[Feat] SPID/CIE Authn Request validation

We need a pydatic schema to validate every objects involved in a authn code flow.
We start this task with the validation of authn requests.

The goal is to have an exportable json schema, that can be used by other developers, for other languages/SDK, to reuse our validation approach.

[Feat] [Provider] Metadata validation with warning on unsupported sign/enc algs

in entity.settings we defined the allowd algs

but in federation entity configuration we don't check if in the submitted metadata we have some values not supported.

TODO: log a warning message to the user or raise a ValidationError

[Feat] Trust Mark status endpoint

This is to allow an entity to check whether a trust mark is still active or not. The query MUST be sent to the trust mark issuer.

The request MUST be an HTTP request using the GET method and the https scheme to a resolved status endpoint with the following query string parameters:

sub
OPTIONAL. The entity_id for the entity to which the trust mark was issued.

id
OPTIONAL. Identifier of the trust mark.

iat
OPTIONAL. When the trust mark was issued. If iat is not specified and the trust issuer have issued several trust marks with the id specified in the request to the entity identified by sub. Then the last last one is assumed.

trust_mark
OPTIONAL. The whole trust mark

[Bug] Provider - Deny consent button doesn't make nothing

If a user declined his consent, he must be redirected to the RP (with an error page)

[Docs] ONBOARDING demo

@dezhizhang1985 this is the README where we illustrate to a new user how to run the example project
https://github.com/peppelinux/spid-cie-oidc-django/blob/dev/docs/technical_specifications/ONBOARDING.md

we need also to put a screenshot of all the pages related to the onboarding service
this will be done when we'll release v0.3.0

[Docs] Relying Party: How to load identity provider metadata

How to create a SPID/CIE Button

1. configure idps OIDCFED_IDENTITY_PROVIDERS = ["http://127.0.0.1:8000/oidc/op/"] in settings.py
2. fetch manage.py fetch_openid_providers --start
3. open the landing page of the RP in the browser

[Feat] OnBoarding Frontend Navigation Bar

required!

Error in settings.py in realying_party example project

spid-cie-oidc-django/examples/relying_party/relying_party/settings.py

Line 53 in 7cfa8d7

'NAME': BASE_DIR / 'db.sqlite3',

possible solution ?

        'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),

[Feat] SPID/CIE Token endpoint Request/Response validation

on the track here:
#21

[feature] SPID/CIE onboarding frontend

spid_cie_oidc.onboarding comes with an admin backend that allows operators to register new entities as descendants of their trust anchor or intermediate entity.

It would be useful to have a frontend accessible by means of SPID/CIE authentication that allows to verify the ownership of a user to start an administrative practice of onboarding and the registration of a new entity.

Trust chain expiration mechanism

the Trust Chain must have a global expiration attribute and a method that tells if it's expired or not

[Feat] OIDC Provider staff panel for testing a RP

if a user gets logged in and he is a staff (user.is_staff == True) we MUST redirect the user to the testing page instead of the consent one.

In the testing page the user (staff) can select one of the several test we'll have to check the compliances of a RP to SPID and/or CIE id.

the user can also be able to change the attributes, remove or add, to be released to the RPs.

[Fix] Add new attributes to authn request schema validator

Add this attributes to authn request schema validator both for spid and cie:

• sub
• iss
• iat
• exp
• jti
• aud

jti can be produced like this:

import uuid

jti: str(uuid.uuid4())

[Feat] Metadata discovery loop prevention

during the build of the trust chain a loop may occour due to a bad configurations on entities in a federation.
In this case the trust chain builder have to break that short circuit :)

BREAKING CHANGE: Separate OnBoarding from Authority

We must be able to load in our project only the authority features to create a trust anchor or an intermediary, without taking also the onboarding demo.

Having said this we'll have another app called authority that loads the models we have in the actual onboarding
The onboarding app will only have the demo frontend and models for an authority/intermediary

Missing SPID claims

here
https://github.com/peppelinux/spid-cie-oidc-django/blob/673fb962cdaf36b39832ca55f5b8a91f6e65087b/spid_cie_oidc/onboarding/schemas/authn_requests.py#L51

we have CIE user claims
we need also the spid user claims

[Feat] Metadata validators for RP and OP

Hi @francescatronconi

I have just adjusted the sample data and made some bugfix in trust chain evaluation here:
1e3ab6a

What I realized is that we need metadata validators for openid_provider and openid_relying_party to be developed as standalone schemas and also included in models validators

in entity.models.FederationEntityConfiguration and in authority.models.FederationEntityDescendants

I had jwks out of rp metadata and lost a few minutes due to this.

That said I think if it’s okay with you we should continue on pydantic and the metadata of OP and RP
Metadata is on OIDC CIE, section 3, page 8

[Core] OIDC Provider Authz endpoint

I'll start over this
#43

[Test] Better coverage for Trust Marks

here

https://github.com/peppelinux/spid-cie-oidc-django/blob/f1694c6ae5f26d3e249f05f23e0e15cc8f8da2e7/spid_cie_oidc/authority/tests/test_02_trust_anchor_intermediary.py#L171

we need more coverage with faulty use cases

[Feat] [Provider] a settings parameter to define how many times a token can be refreshed with a refresh_token

in provider.settings

OIDCFED_PROVIDER_MAX_REFRESH = 1

in provider.views.TokenEndpoint.grant_refresh_token we have to count how many token have been issued and check if the threshold have been exceeded

this issue is also linked to this other
#76

[Feat] RP Authz Request request object as signed JWT

I get authz request to work, and that's the initialization url
http://localhost:8001/oidc/spid/begin?provider=http://127.0.0.1:8000/oidc/op

@dezhizhang1985 that's what the SPID/CIE button MUST trigger

anyway the kind of auth request not use the request object.

[Doc] create a smart tutorial for JWS operations API

in the /docs folder

[Chore][Provider] refactor code for a better reuse/generalization

here
https://github.com/peppelinux/spid-cie-oidc-django/pull/75/files#diff-d623506a77bf9eb93df08f99f22fe7580d3f2cf12dc3bd3111a8a18baa945245R583

Dependency install fails for example projects on Windows

Windows 11
Pytrhon 3.10.2
pip 22.0.4

some text decoding problem seems to be on this line

spid-cie-oidc-django/setup.py

Line 24 in 546ba2c

README = readme.read()

[Docs] OpenID Connect Provider

We need to document how to get a working oidc provider

Coverage on management commands

TODO:

• spid_cie_oidc/relying_party/management/commands/fetch_openid_providers.py
• spid_cie_oidc/provider/management/commands/fetch_openid_relying_parties.py

Access Token preview is broken

[Feat][Tools] Metadata policy UI

in the onboarding tools we need a tool where the user submits a metadata and a metadata policy, so a form with two textfield

the result is a final metadata with the applied policy.

the view that handle this feature will implement what's already done and documented here:
https://github.com/italia/spid-cie-oidc-django/blob/main/docs/FEDERATION_METADATA_POLICY.md

[Feat] OIDC RP landing page with SPID/CIE auth button

Add a url and a view that renders a landing page with spid button

• a CIE and a SPID button in a bootstrap italia template, raw example here look at the JS code
• The SPID button MUST be built using all the valid trust chains related to OPs
• Authn request trigger that calls this webpath

[Provider] Refresh token grant type

this method MUST be implemented

https://github.com/peppelinux/spid-cie-oidc-django/blob/5e5032eb64eb8172c3e974d96f8484d8f87f9251/spid_cie_oidc/provider/views.py#L522

[Feat] [Onboarding] FederationAuthority Operations to onboard a new descendant

We have a form to submit a new registration

we need that a is_staff user can enable a descendant, without assigning any profiles (any active trust marks) to test it in the federation

[Fix] Entity statements and trust mark status content type

As made up by @selfissued here
https://bitbucket.org/openid/connect/pull-requests/129

OIDC tools

in the onboarding frontend we need some tools to

• create a jwk
• convert a PEM certificate/key to private/public jwk
• create a trust chain by submitting only a sub
• validating a trust mark
• decode a jwt and verify if a jwk is also submitted

[Feat][Provider] Logo linked to SPID or CIE profile

@dezhizhang1985 we need different logo for different Provider profiles, as defined here for example:
https://github.com/italia/spid-cie-oidc-django/blob/main/spid_cie_oidc/provider/settings.py

[Provider][RelyingParty] Revocation endpoint

We need to implement this endpoint for Provider and also handle this http request in the rp initiated logout endpoint of the RP

we need to:

• create a view for this

  • in the POST method we need to calidate the client_assertion, as here f233568
  • check if the issuedtoken is still valid and not expired, anyway.
  • revoke the issued token and all the tokens linked to the parent oidc session
  • destroy the user session, see: 17530d0#diff-95680d9a64d71e280f1266c1cbf174154db4ae2d114ed044aacabb2a8706cf1cR44

• add it in the provider's urls.py file

Functions for Tools Missing

• create functions for convert a PEM certificate/key to private/public jwk

[Feat] Resolve Entity Statement Endpoint

Done here:
3db5e85

[Feat][RP] SPID button random ordering of entities

here:
https://github.com/italia/spid-cie-oidc-django/blob/main/spid_cie_oidc/relying_party/views.py#L588

we just need to implement a shuffle method to randomize the elements ordering inside of a list

@mauro ^

[Feat] Token introspection endpoint

Here
https://github.com/peppelinux/spid-cie-oidc-django/blob/provider/spid_cie_oidc/provider/views.py#L779

[RP] Echo attributes page

We need a fancy page for the RP's resource echo attributes

[Feat] Trust Chain, metadata discovery and metadata policy

here
#10