satosacontrib.perun

Microservices, backends and add-ons for SATOSA authentication proxy.

Backends

Seznam backend

A backend for SATOSA which implements login using Seznam OAuth.

Use the example config and fill in your client ID and client secret.

Microservices

AuthSwitcher Lite

This request microservice takes ACRs (AuthnContextClassRefs in SAML, acr_values in OIDC) from a frontend and sets them as requested ACRs for the backends. It relies on SATOSA!419

Context attributes microservice

The microservice adds the target IdP data to attributes:

• display name
• logo
• target issuer

The MetaInfoIssuer microservice needs to be run beforehand with the following patch. Another patch is also needed for the satosa package until they are incorporated into the upstream.

Is banned microservice

The microservice connects to database storing user bans and redirects banned users to configured URL.

Requires a MongoDB database (specified in config).

Persist authorization params microservice

This request microservice retrieves configured parameters from GET or POST request (if available) and stores the values to internal context state.

Forward authorization params microservice

This request microservice retrieves configured parameters from GET or POST request (if available) and forwards them through a context parameter. Optionally, default_values can be provided in the config file. These will be forwarded for configured SP and/or IdP if not provided in the GET/POST request. If the parameter with preconfigured default value is sent via GET/POST request anyway, the value form the request will be used instead of the default.

Session started with microservice

This Satosa microservice checks, if configured attribute's value is present in "session_started_with" values (retrieved by Persist authorization params microservice). If so, adds attribute with configured name. The value is expected to be converted to boolean by Attribute typing microservice.

Compute eligibility microservice

The microservice obtains dict with format { eligiblility_type: } from the internal data and runs a function configured for the given eligibility type. The config is of format type: function_path.

The function should have a following signature:
example_func(data: InternalData, *args, **kwargs) -> timestamp | bool, and it either returns False or a new timestamp, in which case the time in the dictionary is updated in internal data. It strongly relies on the PerunAttributes microservice to fill the dict beforehand. If you want to update eligibility in the IDM, use the UpdateUserExtSource microservice.

NameID Attribute microservice

This microservice copies SAML NameID to an internal attribute with preconfigured name ( and format).

It has two modes of operation. The deprecated way of configuring the microservice requires the config to include nameid_attribute: saml2_nameid_persistent, where saml2_nameid_persistent stands for the name of the SAML NameID attribute in format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent. The new way of configuring this microservice expects a dictionary named nameid_attributes containing items like saml2_nameid_format: saml2_nameid_attribute. In case of the newer configuration, both the format and attribute need to be configured correctly in order for the NameID attribute to be copied to the internal attribute.

If one of the ways to use the microservice is configured, it will be used. If both ways are configured, the newer way of configuration - dictionary, will be used.

Demonstrations of both ways of configuration are shown in the example config.

Attribute typing microservice

Converts boolean attributes specified in config under boolean_attributes to bool type. It does this by having list of possible values for both true and false. Unknown values are converted to None.

Auth event logging microservice

Captures and logs authentication and authorization events. It extracts data from incoming requests and records this information in a database.

Requires a PostgreSQL database.

Cardinality single microservice

Convert single-valued attributes specified in config["attributes"] from lists to strings.

Is eligible microservice

Obtains dict with format { eligiblility_type: } and compares the eligibility timestamp of each type with preconfigured thresholds. All applicable eligibility intervals for each eligibility_type are included in the result.

Thresholds are defined in config under supported_eligibility_types: type: suffixes:. To get a clearer idea, see example config.

Targeted attributes are specified in the configuration under the target_attributes parameter. If it isn't provided, it the defaults to using eduPersonAssurance instead.

Multi Idp hint microservice

Microservice designed to process multi-valued identity provider hints (idphint) in authentication requests. It maps entity IDs based on entity_id_mapping in config, generates a WAYF filter, and updates the discovery service URL accordingly.

Proxy statistics microservice

Collects and logs statistics related to authentication and authorization events. It interacts with a database to store data about IDPs, SPs, and user logins.

Depends on external PostgreSQL db. Needs package driver psycopg2-binary. If driver is changed in the config, corresponding package needs to be installed instead.

Requester client ID microservices

SendRequesterClientID reads the current requester ID and puts it into a query parameter for next authentication. ForwardRequesterClientID reads requester client ID from a query parameter and puts it into state for the SAML backend to send as SAML requester ID.

Perun Microservices

Subpackage of microservices connecting to perun. These have to be allowed (or not denied) for a given combination of requester/target_entity in order to run.

Additional Identifiers

Takes user attributes by config, checks values with regexes and creates hashes by specified algorithm. Values prepared to hash are parsed into List of List of strings and serialized with json. User ext source and user is found by mathing this hashes. If not even one hash can be created, user will be redirected to error page. If user is not found, he will be redirected to registration page.

This microservice does not update the user in Perun with new values. To update save freshly computed values for the current user, you need to run update_user_ext_source microservice.

RFC - eduTEAMS Identifier Generation
Differences between our soulution and RFC:

• the selections are represented as list of list of attributes values serialized to JSON
• all identifiers are hashed by same hash function and with same salt
• The user’s home IdP entity-id does not need to be part of selection
• hashed values can be scoped but does not have to be

Attributes

This Satosa microservice fetches user attributes by its names listed as keys of attrMap config property and sets them as Attributes values to keys specified as attrMap values. Old values of Attributes are replaced.

It strongly relays on PerunIdentity microservice to obtain perun user id. Configure it properly before using this microservice.

It offers two modes: PARTIAL and FULL, configurable via the mode setting in the config, with FULL being the default. FULL mode includes all attrMap attributes, while PARTIAL mode includes them only if they're false/empty in both attrMap or given data.

Entitlement

Calculates Perun user's entitlements by joining eduPersonEntitlements, forwardedEduPersonEntitlements, resource capabilities and facility capabilities.

Without the group_entitlement_disabled attribute set, user's entitlements are computed based on all user's groups on facility.

When group_entitlement_disabled is set, resources which have this attribute set to true are excluded from the computation. This means that for a group to be included in the computation, it needs to be assigned through at least one resource without this attribute set to true.

Ensure member

This Satosa microservice checks member status of the user and calls registration if needed. Register page is set in config['register_url'].

Perun user

Registers a new perunuser endpoint which looks for user's credentials in external service defined by config["proxy_extsource_name"]. Found user is registered and if the registration was successful, also loaded.

If a user wasn't found in the external system. Redirects user to a registration page if possible, otherwise raises SATOSAError.

Registration page url is taken from config's registration_page_url. Failure to initiate registration results in unauthorized access.

SP Authorization

Provides group based access control.

Without the proxy_access_control_disabled attribute set, this microservice denies access to users who are not members of any group assigned to any resource on the current facility.

If the proxy_access_control_disabled attribute is defined in config, resources which have this attribute set to true are excluded. Groups assigned to these resources are not counted towards user's groups on the current facility. This means, that the user has to be a member of at least one group assigned to a resource without this attribute set.

This feature allows computing entitlements while excluding groups which should not be allowed to access the current service.

Update user ext source

This microservice updates userExtSource attributes when the user logs in.

Addons for SATOSA-oidcop frontend

Userinfo perun updates

SATOSA by default caches user data in subsequent calls of the userinfo endpoint. Thanks to this addon the data is loaded from Perun IDM on each call so they are always up to date.

Requires a configuration for the entitlement microservice in /etc/satosa/plugins/microservices/perun_entitlement_idm.yaml.

How to use:

1. add this to the configuration file of satosa-oidcop frontend, under the key add_on:

   userinfo_perun_updates:
     function: satosacontrib.perun.addons.userinfo_perun_updates.add_support
     kwargs: {}
   

Extended introspection response

Implements RFC 9470 which states that two attributes(acr and auth_time) should be in introspection endpoint. This addon gets them from session manager.

How to use:

1. add this to the configuration file of satosa-oidcop frontend, under the key add_on:

   extended_introspection_response:
     function: satosacontrib.perun.addons.extended_introspection_response.add_support
     kwargs: {}