SATOSA oidcop frontend

SATOSA Frontend based on idpyoidc by Identity Python (previously identity python oidcop).

Features

Endpoints:

• provider discovery
• jwks uri
• authorization
• token
• userinfo
• registration
• registration_read endpoint
• introspection endpoint
• token exchange

Requirements

• satosa
• mongodb, see Satosa-Saml2Spid mongo example.

Setup

pip install satosa_oidcop

Configuration

Environment variables (!ENV)

The frontend YAML config supports !ENV and !ENVFILE tags (via SATOSA's YAML loader), consistent with pyeudiw and other SATOSA backends/frontends. Use them for sensitive or deployment-specific values:

config:
  domain: !ENV SATOSA_HOSTNAME
  storage:
    kwargs:
      url: !ENV MONGO_OIDCOP_HOST
      connection_params:
        username: !ENV MONGODB_OIDCOP_USERNAME
        password: !ENV MONGODB_OIDCOP_PASSWORD
  op:
    server_info:
      session_params:
        encrypter:
          kwargs:
            password: !ENV SATOSA_ENCRYPTION_KEY
            salt: !ENV SATOSA_SALT

Required env vars for the example config: SATOSA_HOSTNAME, MONGO_OIDCOP_HOST, MONGODB_OIDCOP_USERNAME, MONGODB_OIDCOP_PASSWORD, SATOSA_ENCRYPTION_KEY, SATOSA_SALT.

Configuration structure

Anyone can migrate its oidcop configuration, from flask_op or django-oidc-op or whatever, in SATOSA and without any particular efforts. Looking at the example configuration we see that config.op.server_info have a standard SATOSA configuration with the only addition of the following customizations, needed in SATOSA for interoperational needs. These are:

• autentication

        authentication:
          user:
            acr: urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword
            class: satosa.frontends.oidcop.user_authn.SatosaAuthnMethod

• userinfo

       userinfo:
         class: satosa.frontends.oidcop.user_info.SatosaOidcUserInfo

authentication inherits oidcop.user_authn.user.UserAuthnMethod and overloads two methods involved in user authentication and verification. These tasks are handled by SATOSA in its authentication backends.

userinfo inherits oidcop.user_info.UserInfo and proposes a way to store the claims of the users when they comes from the backend. The claims are stored in the session database (actually mongodb) and then they will be fetched during userinfo endpoint (and also token endpoint, for having them optionally in id_token claims).

SSO and cookies

oidcop SSO and cookies were not have been implemented because SATOSA does not support logout, because of this they are quite useless at this moment.

Client and Session Storage

MongoDB is the storage, here some brief descriptions for a demo setup. The interface to SATOSA oidcop storage is satosa.frontends.oidcop.storage.base.SatosaOidcStorage and it has three methods:

• get_client_by_id(self, client_id:str, expired:bool = True)
• store_session_to_db(self, session_manager, **kwargs)
• load_session_from_db(self, req_args, http_headers, session_manager, **kwargs)

satosa.frontends.oidcop.storage.mongo.Mongodb overloads them to have I/O operations on mongodb.

Subject type

The client configuration can also include the subject_type key, with permitted values being public and pairwise. If absent, the default is to choose public. This has been driven by backwards compatibility with existing behaviour: oidcop (session_manager.create_session) defaults to public.

For user privacy, we strongly recommend selecting pairwise for new deployments, unless public is absolutely needed (for linking users across related but distinct services).

Demo

Satosa-Saml2Spid is a custom Satosa configuration to deal with many SAML2 and OIDC Relying parties and many eduGain and SPID Identity Provider.

Contributions

Feel free to open issues and pull requests, we build communities!

Developer notes

Storage design

At this time the storage logic is based on oidcop session_manager load/dump/flush methods. Each time a request is handled by an endpoint, the oidcop session manager loads the definition from the storage, only which one are strictly related to the request will be loaded in the in memory storage of oidcop.

Roadmap

• unit tests
• pytest mongo mock
• test response_type = "code id_token token" (hybrid flow)
• auto prune expired sessions with mongodb index (auto prune, mongo index)
• token refresh
• DPoP support

Tests

Before you run the tests mind that you've to start a local mongod instance, e.g. with:

sudo docker run \
  --rm \
  -e ALLOW_EMPTY_PASSWORD=yes \
  -e MONGODB_ENABLE_JOURNAL=false \
  -p 27017:27017 \
  --name mongodb \
  bitnami/mongodb:latest

If you like you can use mongo-express as a management UI over the local mongo instance:

sudo docker run \
  -e ME_CONFIG_MONGODB_SERVER=$MONGOHOST-OR-DOCKER-BRIDGE-LIKE-172.17.0.1 \
  -p 8081:8081 \
  mongo-express

Then run the tests:

pip install pytest pytest-cov
pytest --cov=satosa_oidcop -v --cov-report term --cov-fail-under=95 tests/

Authors

• Giuseppe De Marco @ Università della Calabria

Credits

• Roland Hedberg
• Andrea Ranaldi @ ISPRA Ambiente
• Pavel Břoušek @ CESNET
• Identity Python Community