Satosa-Saml2Spid

A SAML2/OIDC IAM Proxy based on SATOSA for SAML-to-SAML, OIDC-to-SAML and SAML-to-Wallet interoperability with the Italian Digital Identity Systems.

Glossary
General features
Introduction
Demo components
Setup
For Developers
Author
Credits

Glossary

Frontend, SAML2 Identity Provider, OpenID Connect Provider.
Backend, SAML2 Service Provider, OpenID Connect Relying Party, Wallet Relying Party.
TargetRouting, a SATOSA microservice for selecting the output backend to reach the endpoint (IdP) selected by the user.
Discovery Service, interface that allows users to select the authentication endpoint.

General features

Backends:

SPID SP
CIE SP
FICEP SP (eIDAS 1.0)
SAML2 SP
EUDI Wallet (eIDAS 2.0, experimental and not intended for production use)

Frontends:

SAML2 IDP
OIDC OP (see satosa-oidcop)

This project is tested in Continuous Integration using spid-sp-test, with Metadata, Authn Requests and Responses.

Introduction

Satosa-Saml2 Spid is an intermediate between many SAML2/OIDC Service Providers and many SAML2 Identity Providers. It allows traditional Saml2 Service Providers to communicate with Spid, CIE and eIDAS Identity Providers adapting Metadata and AuthnRequest operations.

Figure1 : Traditional SAML2 Service Providers (SPs) proxied through the SATOSA SPID Backend gets compliances on AuthnRequest and Metadata operations.

This solution configures multiple proxy frontends and backends to get communicating systems that, due to protocol or specific limitations, traditionally could not interact each other.

Demo components

The example project comes with some preconfigured static pages.

for other page screenshots, see here.

These demo pages are static files, available in example/static. To get redirection to these pages, or redirection to third-party services, it is required to configure the files below:

file: example/proxy_conf.yml, example value: UNKNOW_ERROR_REDIRECT_PAGE: "https://static-contents.example.org/error_page.html"
file: example/plugins/{backends,frontends}/$filename, example value: disco_srv: "https://static-contents.example.org/static/disco.html"

Usage

The average time to set up this project for your needs takes roughly 1 hour. This time may vary depending on your configuration, how many backend and frontend you configure, the machine's resources and the type of network connection for the download of the docker images.

For the setup of this project, the following dependency must be installed in your machine:

Python 3.10 or higher
Git
Docker

Setup

All the setup instructions for your Satosa-Saml2spid configuration are available in README-SETUP.md.

Docker Compose

This project uses Docker, all the instructions to configure this project using the official docker images are available in Docker-compose.

The docker compose may use the enviroment variables to configure Satosa-Saml2Spid.

The official Satosa-Saml2SPID docker image is available at italia/satosa-saml2spid.

To install it, you can execute the following command: sudo docker pull ghcr.io/italia/satosa-saml2spid:latest.

Otherwise you can build the image executing the following command: docker build -t satosa-saml2spid ..

Then you can even inspect the image content, by running the following command: docker run -it -v $(pwd)/example:/satosa_proxy --entrypoint sh satosa-saml2spid.

Setup a Djangosaml2 example Service Provider

This project provides an example SAML2 Service Provider for demo purposes, this Service Provider is executed by default in the Docker Compose.

For any further detail about its configuration, see example_sp/djangosaml2_sp/README.md.

Below the demo using the djangosaml2 Service Provider with the Wallet authentication OpenID4VP .

For Developers

If you're running tests and you don't want to pass through the Discovery page each time you can use idphinting if your SP support it. Below an example using a djangosaml2 Service Provider:

https://localhost/saml2/login/?idp=https://localhost/Saml2IDP/metadata&next=/saml2/echo_attributes&idphint=https%253A%252F%252Flocalhost%253A8080

If you're going to test Satosa-Saml2Spid with spid-sp-test, take a look to .github/workflows/python-app.yml.

Additional information can be found here.

Warnings

Here something that you should know before start.

You must enable more than a single IdP (multiple metadata or single metadata with multiple entities) to get Discovery Service working.
Proxy doesn't handle SAML2 SLO, so the spidSaml2 backend is configured with Authnforce -> True. For any further information see Single Logout in Satosa.
SATOSA Saml2 backend configuration has a policy section that will let us to define specialized behaviours and configuration for each SP (each by entityid). In this example I defined a single "default" behaviour with attributes name_format to urn:oasis:names:tc:SAML:2.0:attrname-format:uri, due to my needs to handle many service providers for which it could be painfull do a static definition each time. An additional "hack" have been made in example/attributes-maps/satosa_spid_uri_hybrid.py, where I adopted a hybrid mapping that works for both URI and BASIC formats. Feel free to customized or decouple these format in different files and per SP.

External references