SATOSA Protocol Translation Proxy

SATOSA provides several micro-services to implement special routing logic to choose which backend (target provider) to use:

• DecideBackendByRequester: Route based on the identity of the requester.
• DecideBackendByTargetIssuer: Route based on the target entity ID.
• DiscoToTargetIssuer: Used with a Discovery Service to select a backend based on the user's selection in the discovery response.
• DecideIfRequesterIsAllowed: Used with SAMLMirrorFrontend to filter authentication requests to specific SAML entities using allow and deny rules.

In a One-to-Many SAML proxy scenario, the proxy acts as a single interface for multiple Identity Providers (IdPs).

Workflow:

1. The Service Provider (SP) sends a request to the proxy. The SP is only aware of the proxy, not the individual IdPs.
2. The proxy redirects the user to a Discovery Service.
3. The user selects an IdP, and the proxy receives the Entity ID of the selected IdP.
4. The proxy initiates the authentication request with the selected IdP.
5. Once authentication is complete, the user is redirected back to the proxy.
6. The proxy translates the IdP response and returns it to the Service Provider.

In a Many-to-One SAML proxy scenario, the proxy bridges the gap between a Service Provider and an Identity Provider that may be incompatible or unable to handle multiple Entity IDs.

Workflow:

1. The Service Provider sends a request to the proxy.
2. The proxy communicates with the Identity Provider (IdP) on behalf of the SP.
3. The IdP returns a response containing user information.
4. The proxy processes this response and returns it to the Service Provider.

SATOSA uses micro-services to add additional behavior to the proxy. There are two types:

1. Request micro-services: Applied to the incoming request.
2. Response micro-services: Applied to the incoming response from the target provider.

Micro-services act as plugins that can modify the flow of authentication or the data being passed. Some micro-services have specific ordering requirements (e.g., Account Linking must be first, User Consent must be last).

The SATOSA proxy maintains state across different steps of a transaction flow using a secure cookie. To ensure security, the state is encrypted using an AES-256 cipher with CBC mode and a random Initialization Vector (IV).

As a transaction progresses, the state object accumulates data from the core proxy and various enabled modules (like Consent or Account Linking). Developers building plugins or inspecting flows should be aware that the state is a cumulative object that evolves throughout the lifecycle of a single request.

Use the AttributePolicy class to define a list of allowed attributes for a specific requester. This filters attributes delivered from the target provider based on the requester's identity.

attribute_policy:
    <requester>:
        allowed:
            - attr1
            - attr2

SAML2 metadata can be loaded either from local files or from remote URLs.

Local files: Use the local key within the metadata configuration block.

Remote URLs: Use the remote key, providing a list of objects containing the url and an optional cert (set to null if no specific certificate is provided).

# Metadata from local file
"metadata":
    local: [idp.xml]

# Metadata from remote URL
"metadata":
    remote:
        - url: "https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2"
          cert: null

SATOSA uses plugins to handle protocol-specific communication. Plugins are categorized into:

• Frontends: Receive requests from clients.
• Backends: Send requests to target providers.
• Microservices: Additional services.

Every plugin configuration must include two mandatory parameters:

1. name: A unique identifier for the plugin instance.
2. module: The fully qualified name of the importable Python module.

Example structure (conceptual):

- name: my_backend
  module: my_module.backend_implementation

SATOSA can be configured for several protocol translation scenarios:

• SAML2 <-> SAML2: Connect a single Service Provider (e.g., Box) to multiple Identity Providers, or enable communication between an IdP and an SP that cannot communicate directly within a federation.
• SAML2 <-> Social Logins: Connect a SAML2 Service Provider to social media providers like Google or Facebook. The proxy generates SAML2 metadata for the social providers and creates dynamic endpoints to bridge them.
• SAML2 <-> OIDC: Act as a translation layer between a SAML2 Service Provider and an OpenID Connect provider.