PySAML2

The policy configuration allows an IdP or AA to behave differently based on the requesting service (SP).

Policies are looked up in this order:

1. The SP's entityID.
2. The Registration Authority name (if present in SP metadata).
3. The default key.

If no default is provided and only specific SP IDs are listed, the server will only accept connections from those specified SPs.

Key policy options:

• lifetime: Maximum time (in minutes/hours) before information is considered stale (maps to NotOnOrAfter).
• attribute_restrictions: A dictionary mapping attribute names to allowed values (can be None for all values, or a regex string/list for filtering).
• name_form: The name-form used when sending assertions.
• nameid_format: The NameID format (defaults to urn:oasis:names:tc:SAML:2.0:nameid-format:transient).
• entity_categories: List of entity categories to apply.
• sign: Choices: "response", "assertion", "on_demand".

"service": {
        "idp": {
            "policy": {
                "urn:mace:example.com:saml:roland:sp": {
                    "lifetime": {"minutes": 5},
                    "attribute_restrictions": {
                        "givenName": None,
                        "surName": None,
                    },
                },
                "http://www.swamid.se/": {
                    "attribute_restrictions": {
                        "givenName": None,
                    },
                },
                "default": {
                    "lifetime": {"minutes":15},
                    "attribute_restrictions": None,
                    "name_form": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri",
                    "entity_categories": [
                        "edugain",
                    ],
                },
            }
        }
    }

The sp_test tool is organized into several hierarchical abstractions that manage the lifecycle of a SAML2 test session:

• Client (sp_test/__init__.py): The top-level orchestrator. It reads configuration files (using the json_config key) and command-line arguments, initializes the test driver IDP, creates a Conversation, and executes the test sequence via .do_sequence_and_tests().
• Conversation (sp_test/base.py): Manages the state and execution of a specific test session.
• Operation (oper): A named test scenario (e.g., 'Basic Login test'). It contains a sequence of flows and optional pre and post tests.
• Flow: A tuple of classes representing a SAML request-response pair. A standard solicited authentication flow consists of 4 elements:
  • flow[0]: An Operation (e.g., handling discovery or WAYF).
  • flow[1]: A Request class (processes the authentication request).
  • flow[2]: A Response class (sends the authentication response).
  • flow[3]: An optional Check class (e.g., verifying error status).
• Test: A class executed during an operation. These can be run pre (before the sequence), post (after the sequence), or mid (between a SAML request and response, such as VerifyIfRequestIsSigned).
• Check: An optional class executed upon receiving the SP's HTTP response(s). It writes structured reports to conv.test_output. Checks can validate expected errors (like invalid signatures) without raising exceptions.
• Interaction: An automation mechanism that searches responses for constants to simulate human user interface interactions.

PySAML2 supports Entity Categories in two distinct ways depending on whether you want to include them in your metadata or use them to filter attributes released to Service Providers (SPs).

1. Including Entity Categories in Metadata

To generate EntityAttribute metadata elements, use the entity_category_support configuration option. This is useful for declaring which categories your entity belongs to (e.g., edugain.COCO).

2. Using Entity Categories as Attribute Filters

To use Entity Categories as a filter that controls which attributes are released to an SP, include the entity_categories option within your policy configuration. If an SP does not conform to the specified categories, the attributes will not be released.

Note: Entity category definitions and attributes are located in src/saml2/entity_category/<registrar-of-entity-category>.py.

# Example 1: Metadata configuration
config = {
    'entity_category_support': [
        edugain.COCO, # "http://www.geant.net/uri/dataprotection-code-of-conduct/v1"
        refeds.RESEARCH_AND_SCHOLARSHIP,
    ],
    # ... other config
}

# Example 2: Policy configuration (Attribute Filtering)
config = {
    "policy": {
      "default": {
        "lifetime": {"minutes": 15},
        "entity_categories": ["refeds"],
      }
    }
}

To set up a development environment for PySAML2, follow these steps:

1. Manage Python versions: Use pyenv to install and enable supported Python versions (3.6, 3.7, 3.8, 3.9, 3.10).
2. Manage dependencies: Use poetry to manage dependencies and virtual environments. It is recommended to install poetry using pipx.
3. Install dependencies: Use poetry install with specific groups to include development, testing, coverage, and documentation tools.
4. Activate environment: Use poetry shell to enter a shell with the virtual environment loaded, or simply use poetry run <command> to execute commands within the environment.

# Install supported python versions using pyenv
$ for v in 3.6 3.7 3.8 3.9 3.10; do pyenv install "${v}:latest"; done
$ pyenv versions --bare | xargs pyenv local

# Install development dependencies with poetry
$ poetry install --with dev,test,coverage,docs --sync

# Enter the virtual environment
$ poetry shell