### Copy Example Configurations

Source: https://github.com/identitypython/satosa/blob/master/doc/saml2-to-oidc.md

Initial setup involves copying example configuration files from the SATOSA installation directory to your project's configuration folder. This includes proxy, internal attributes, SAML2 frontend, and OpenID Connect backend configurations.

```bash
mkdir -p saml2-oidc/plugins
cp example/{proxy_conf.yaml.example,internal_attributes.yaml.example} saml2-oidc/
cp example/plugins/frontends/saml2_frontend.yaml.example saml2-oidc/plugins/
cp example/plugins/backends/openid_backend.yaml.example saml2-oidc/plugins/
```

--------------------------------

### Install SATOSA Microservices

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Downloads, extracts, and installs SATOSA microservices from GitHub.

```bash
curl -L -o satosa_microservices.tar.gz \
    https://github.com/IdentityPython/satosa_microservices/archive/master.tar.gz \
    && mkdir -p /opt/satosa_microservices \
    && tar -zxf satosa_microservices.tar.gz -C /opt/satosa_microservices --strip-components=1 \
    && rm -f satosa_microservices.tar.gz
```

--------------------------------

### Install SATOSA from GitHub

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Installs the latest version of SATOSA directly from the GitHub master branch.

```bash
yum install git
pip install --upgrade git+https://github.com/IdentityPython/SATOSA.git#egg=SATOSA
```

--------------------------------

### Install SATOSA

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Installs the SATOSA package using pip.

```bash
pip install SATOSA
```

--------------------------------

### Install SATOSA via Pip

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Installs the SATOSA application using pip. This can be used for manual installation after downloading the project or directly from PyPI.

```bash
pip install <satosa_path>
```

--------------------------------

### SATOSA Middleware Configuration Example

Source: https://github.com/identitypython/satosa/wiki/Middlewares

This example shows how to configure middleware in SATOSA using a list of dotted Python paths. Ensure the specified paths point to executable middleware objects.

```python
middlewares = [
    "cookies_samesite_compat.CookiesSameSiteCompatMiddleware",
    "sunet.satosa.extensions.middleware.req_id_tracer.ReqIDTracerMiddleware",
]
```

--------------------------------

### Google Backend Configuration Example

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example configuration for the Google social login backend plugin. Ensure 'client_id' and 'client_secret' are provided and the redirect URI is registered with Google.

```yaml
name: google
config:
  client:
    client_metadata:
      redirect_uris: [<base_url>/<name>]
[...]
```

--------------------------------

### Micro-service Configuration Example

Source: https://github.com/identitypython/satosa/wiki/Anatomy-of-a-response-micro-service

YAML configuration for initializing a SATOSA micro-service, specifying the module path and custom configuration parameters.

```yaml
module: python.path.example.module_name.NameOfMicroservice
name: An example micro-service skeleton
config:
  capitalize_name: True
```

--------------------------------

### Install Dependencies

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Installs necessary packages for running SATOSA with Apache and mod_wsgi on CentOS 7.

```bash
yum install epel-release
yum install httpd mod_ssl httpd-devel python34 python34-devel
yum install xmlsec1-openssl gcc curl
```

--------------------------------

### Install SATOSA Dependencies on Ubuntu

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Installs necessary system packages required for SATOSA on Ubuntu. Ensure you have Python 3.4 or above.

```bash
apt-get install libffi-dev libssl-dev xmlsec1
```

--------------------------------

### Copy Configuration Files

Source: https://github.com/identitypython/satosa/blob/master/doc/SAML2-to-Social_logins.md

Copies necessary base configuration files from the example directory to set up SAML2 and social backend plugins.

```bash
mkdir -p saml2-social/plugins
cp example/{proxy_conf.yaml.example,internal_attributes.yaml.example} saml2-social/
cp example/plugins/frontends/saml2_frontend.yaml.example saml2-social/plugins/
cp example/plugins/backends/{facebook,google}_backend.yaml.example saml2-social/plugins/
```

--------------------------------

### Copy Base Configurations

Source: https://github.com/identitypython/satosa/blob/master/doc/oidc-to-saml2.md

Copies necessary configuration files from the example directory to set up the OIDC to SAML2 proxy.

```bash
mkdir -p oidc-saml2/plugins
cp example/{proxy_conf.yaml.example,internal_attributes.yaml.example} oidc-saml2/
cp example/plugins/frontends/openid_connect_frontend.yaml.example oidc-saml2/plugins/
cp example/plugins/backends/saml2_backend.yaml.example oidc-saml2/plugins/
```

--------------------------------

### Install pip and mod_wsgi

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Installs the latest production release of pip and mod_wsgi.

```bash
curl https://bootstrap.pypa.io/get-pip.py | python3
pip install mod_wsgi
```

--------------------------------

### Copy Base Configurations for SAML2-SAML2

Source: https://github.com/identitypython/satosa/blob/master/doc/one-to-many.md

Copies the necessary base configuration files from the example directory to set up the SAML2-SAML2 plugin. Ensure you are in the correct directory before running.

```bash
mkdir -p saml2-saml2/plugins
cp example/{proxy_conf.yaml.example,internal_attributes.yaml.example} saml2-saml2/
cp example/plugins/frontends/saml2_frontend.yaml.example saml2-saml2/plugins/
cp example/plugins/backends/saml2_backend.yaml.example saml2-saml2/plugins/
```

--------------------------------

### Example 'context' Parameter Structure in Python

Source: https://github.com/identitypython/satosa/wiki/Anatomy-of-a-response-micro-service

Demonstrates the structure of the 'context' parameter, which includes session state, internal data, and request-specific details for a micro-service.

```python
context = {
    "cookie": 'SATOSA_PROXY_STATE="..."',
    "internal_data": {
        "metadata_store": <saml2.mdstore.MetadataStore object at 0x7fc60e32cb70>
    },
    "request": None,
    "request_authorization": "",

    # type: satosa.state.State
    "state": {
        "ROUTER": "Saml2IDP",
        "SATOSA_BASE": {"requester": "..."},
        "Saml2IDP": {
            "relay_state": "https://example.org/authenticate?as=some-sp",
            "resp_args": {
                "binding": "urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
                "destination": "https://example.org/saml-sp/saml2-acs",
                "in_response_to": "_e923792fde97aa0b6bc82999cba5274a61eae4b96c",
                "name_id_policy": "<ns0:NameIDPolicy xmlns:ns0=\"urn:oasis:names:tc:SAML:2.0:protocol\" AllowCreate=\"true\" Format=\"urn:oasis:names:tc:SAML:2.0:nameid-format:transient\"/>",
                "sp_entity_id": "...",
            },
        },
        "memorized_idp": "...",
    },

    "target_backend": "saml2sp",
    "target_frontend": None,
    "target_micro_service": None,
}

```

--------------------------------

### Install LDAP Attribute Store Dependency

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Installs the 'ldap3' library, required for the LDAP Attribute Store microservice.

```bash
pip install ldap3
```

--------------------------------

### Example 'data' Parameter Structure in Python

Source: https://github.com/identitypython/satosa/wiki/Anatomy-of-a-response-micro-service

Illustrates the expected structure of the 'data' parameter, which holds authentication information, subject identifiers, attributes, and metadata.

```python
# type: satosa.internal.InternalData
data = {
    # type: satosa.internal.AuthenticationInformation
    # This part holds the authentication information
    # namely, the authentication context classes (ie, the LoA reference)
    # and the issuer of the given identity (ie, the IdP entity-id)
    "auth_info": {
        "auth_class_ref": "urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
        "timestamp": "2020-02-22T19:30:04Z",
        "issuer": "https://www.rediris.es/sir/umaidp",
    },

    # the requester of the authentication; this is typically the SP (or RP) entity-id
    "requester": "https://example.org/saml-sp/metadata.xml",
    "requester_name": [{"text": None, "lang": "en"}],

    # the subject identifier as expressed in different protocols, along with its type or format. 
    # this will match `NameID` for SAML2 and `sub` for OIDC.
    "subject_id": "69e83a116ed953279999d4463541c2799795c816",
    "subject_type": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",

    # the attributes of the subject as expressed in different protocols.
    # this will be a representation of claims for OIDC, 
    # or attribute statements of an assertion for SAML2.
    "attributes": {
        "edupersontargetedid": ["04e8192d48a040f3ef495999958908f8aa10b4a5"],
        "displayname": ["Somename Somesurname"],
        "givenname": ["Somename"],
        "mail": ["someone@uma.es"],
        "name": ["Somename"],
        "surname": ["Somesurname"],
        "epsa": ["alum@uma.es", "staff@uma.es"],
        "eppn": ["06100004X@uma.es"],
        "spuc": [
            "urn:schac:personalUniqueCode:es:rediris:sir:mbid:{sha1}0c938d124632017100980299997b1ab174789657",
            "urn:schac:personalUniqueCode:es:uma:CAU:id:822",
            "urn:schac:personalUniqueCode:es:uma:ESC:code:a98b1a8c-9215-11e9-8545-000077349997",
            "urn:schac:personalUniqueCode:es:uma:codUni:06100004X",
        ],
    },

    # this has been added by another micro-service; namely metainfo
    # the role of that micro-service is to collect metadata information about entities
    # and present it in a unified way.
    # other micro-services can lookup the metadata of an entity using this structure.
    "metadata": {
        "https://www.rediris.es/sir/umaidp": {
            "display_name": "University of Malaga",
            "privacy_statement": None,
            "contacts": [
                {
                    "contact_type": "technical",
                    "given_name": "SIR helpdesk",
                    "email_address": ["mailto:sir@rediris.es"],
                },
                {
                    "contact_type": "other",
                    "given_name": "RedIRIS SIRTFI-CSIRT Team",
                    "email_address": ["mailto:sirtfi-csirt@rediris.es"],
                },
            ],
            "entity_categories": [],
            "supported_entity_categories": [
                "http://refeds.org/category/research-and-scholarship"
            ],
            "assurance_certifications": ["https://refeds.org/sirtfi"],
        },
        "https://example.org/saml-sp/metadata.xml": {
            "display_name": None,
            "privacy_statement": None,
            "contacts": [],
            "entity_categories": [],
            "supported_entity_categories": [],
            "assurance_certifications": [],
        },
    }
}

```

--------------------------------

### Rename Configuration Files

Source: https://github.com/identitypython/satosa/blob/master/doc/SAML2-to-Social_logins.md

Renames example configuration files to their active counterparts. This is a prerequisite for editing the actual proxy settings.

```bash
mv proxy_conf.yaml.example proxy_conf.yaml
```

```bash
mv internal_attributes.yaml.example internal_attributes.yaml
```

```bash
mv plugins/saml2_frontend.yaml.example plugins/saml2_frontend.yaml
mv plugins/facebook_backend.yaml.example plugins/facebook_backend.yaml
mv plugins/google_backend.yaml.example plugins/google_backend.yaml
```

--------------------------------

### Apply Attribute Policy Configuration

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example configuration for applying an attribute policy. Specifies allowed attributes per requester.

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

--------------------------------

### Rename Proxy Configuration File

Source: https://github.com/identitypython/satosa/blob/master/doc/saml2-to-oidc.md

Rename the example proxy configuration file to its active name before editing.

```bash
mv proxy_conf.yaml.example proxy_conf.yaml
```

--------------------------------

### Address Claim Example (OpenID Connect)

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Illustrates the structure of the address claim in OpenID Connect, which can contain nested sub-fields.

```json
{
  "address": {
    "formatted": "100 Universal City Plaza, Hollywood CA 91608, USA",
    "street_address": "100 Universal City Plaza",
    "locality": "Hollywood",
    "region": "CA",
    "postal_code": "91608",
    "country": "USA"
  }
}
```

--------------------------------

### Generate Signed SAML Proxy Metadata

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Run this command to produce signed SAML metadata for all SAML front- and backend modules. Ensure you have the `satosa-saml-metadata` tool installed.

```bash
satosa-saml-metadata <path to proxy_conf.yaml> <path to key for signing> <path to cert for signing>
```

--------------------------------

### Rename Plugin Configurations

Source: https://github.com/identitypython/satosa/blob/master/doc/oidc-to-saml2.md

Renames the example plugin configuration files for the OIDC frontend and SAML2 backend to their active names.

```bash
mv plugins/openid_connect_frontend.yaml.example plugins/openid_connect_frontend.yaml
mv plugins/saml2_backend.yaml.example plugins/saml2_backend.yaml
```

--------------------------------

### Get mod_wsgi Module Configuration

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Generates the necessary LoadModule and WSGIPythonHome directives for Apache configuration.

```bash
$ mod_wsgi-express module-config
LoadModule wsgi_module "/usr/lib64/python3.4/site-packages/mod_wsgi/server/mod_wsgi-py34.cpython-34m.so"
WSGIPythonHome "/usr"
```

--------------------------------

### Run SATOSA Proxy with Gunicorn (HTTPS)

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Start the SATOSA proxy server using Gunicorn with HTTPS enabled. Specify the socket address, and paths to your SSL key and certificate files.

```bash
gunicorn -b<socket address> satosa.wsgi:app --keyfile=<https key> --certfile=<https cert>
```

--------------------------------

### Rename Plugin Configuration Files

Source: https://github.com/identitypython/satosa/blob/master/doc/saml2-to-oidc.md

Rename the example plugin configuration files for the SAML2 frontend and OpenID Connect backend to their active names before specifying configuration parameters.

```bash
mv plugins/saml2_frontend.yaml.example plugins/saml2_frontend.yaml
mv plugins/openid_backend.yaml.example plugins/openid_backend.yaml
```

--------------------------------

### Rename SAML2 Frontend and Backend Plugin Files

Source: https://github.com/identitypython/satosa/blob/master/doc/one-to-many.md

Renames the example SAML2 frontend and backend plugin configuration files to their active names.

```bash
mv plugins/saml2_frontend.yaml.example plugins/saml2_frontend.yaml
mv plugins/saml2_backend.yaml.example plugins/saml2_backend.yaml
```

--------------------------------

### Add Static Attributes Configuration

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example configuration for adding static attributes to responses. Keys represent internal attribute names.

```yaml
organisation: Example Org.
country: Sweden
```

--------------------------------

### Configure SATOSA Bind Password from Environment File

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example of SATOSA YAML configuration using the !ENVFILE tag to resolve the bind password from a file specified by an environment variable. The content of the file will be used as the 'bind_password'.

```yaml
bind_password: !ENVFILE LDAP_BIND_PASSWORD_FILE
```

--------------------------------

### Rename Internal Attributes Configuration File

Source: https://github.com/identitypython/satosa/blob/master/doc/saml2-to-oidc.md

Rename the example internal attributes configuration file to its active name before mapping attributes.

```bash
mv internal_attributes.yaml.example internal_attributes.yaml
```

--------------------------------

### Configure SATOSA Bind Password with Environment Variable

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example of SATOSA YAML configuration using the !ENV tag to resolve the bind password from an environment variable. The value of 'bind_password' will be dynamically set at runtime.

```yaml
bind_password: !ENV LDAP_BIND_PASSWORD
```

--------------------------------

### SAML2 Frontend Default Attribute Release Exclusion

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure default attribute release exclusion for any IdP or SP. This example prevents 'givenName' from being released universally.

```yaml
config:
    idp_config: [...] 
    custom_attribute_release:
        "default":
            "":
                exclude: ["givenName"]
```

--------------------------------

### Filter Attribute Values: Basic Regex

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example configuration for filtering attribute values. Preserves values matching the regex. Use empty string for defaults.

```yaml
"https://provider.example.com":
    "":
        "": "^foo:bar"
```

--------------------------------

### Internal Attributes Configuration Example

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Defines internal attributes 'mail' and 'address' with mappings for OpenID Connect and SAML profiles. Supports dot-separated access for nested attributes like 'address.formatted'.

```yaml
attributes:
  mail:
    openid: [email]
    saml: [mail, emailAddress, email]
  address:
    openid: [address.formatted]
    saml: [postaladdress]
```

--------------------------------

### Filter Attribute Values: Specific Attribute

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example configuration for filtering specific attributes. Preserves values matching the regex. Use empty string for defaults.

```yaml
"":
    "":
        "attr1": "foo:bar$"
```

--------------------------------

### Filter Attribute Values: Specific Requester

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Example configuration for filtering attributes for a specific requester. Preserves values matching the regex. Use empty string for defaults.

```yaml
"":
    "https://client.example.com":
        "attr1": "foo:bar"
```

--------------------------------

### SAML2 Frontend Custom Attribute Release Exclusion

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure custom attribute release for a specific IdP and SP to exclude attributes. This example shows how to prevent the 'givenName' attribute from being released.

```yaml
config:
    idp_config: [...]
    custom_attribute_release:
        idp-entity-id1
            sp-entity-id1:
                exclude: ["givenName"]
```

--------------------------------

### Create SATOSA Configuration File

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Creates the /etc/satosa directory and the proxy_conf.yaml configuration file with essential settings.

```bash
$ mkdir /etc/satosa
$ cat << EOF > /etc/satosa/proxy_conf.yaml

BASE: https://some.host.org

STATE_ENCRYPTION_KEY: fazmC8yELv38f9PF0kbS

INTERNAL_ATTRIBUTES: "/etc/satosa/internal_attributes.yaml"

COOKIE_STATE_NAME: "SATOSA_STATE"

BACKEND_MODULES:
  - "/etc/satosa/plugins/saml2_backend.yaml"

FRONTEND_MODULES:
  - "/etc/satosa/plugins/ping_frontend.yaml"
  - "/etc/satosa/plugins/saml2_frontend.yaml"

MICRO_SERVICES:
  - "/etc/satosa/plugins/primary_identifier.yaml"
  - "/etc/satosa/plugins/ldap_attribute_store.yaml"

CONSENT:
  enable: No

ACCOUNT_LINKING:
  enable: No

LOGGING:
  version: 1
  formatters:
    simple:
      format: "[%(asctime)s] [%(levelname)s] [%(name)s]: %(message)s"
  handlers:
    console:
      class: logging.StreamHandler
      formatter: simple
      stream: ext://sys.stderr
  loggers:
    satosa:
      level: INFO
      handlers:
        - console
      propagate: no
  root:
    level: INFO
    handlers:
      - console
EOF
```

--------------------------------

### Configure WSGI Daemon Process

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Sets up the WSGI daemon process for SATOSA, specifying worker count, threads, display name, home directory, user, group, and Python path.

```apache
WSGIDaemonProcess satosa processes=2 threads=15 \
  display-name=%{GROUP} home=/etc/satosa user=satosa group=satosa \
  restart-interval=86400 graceful-timeout=3600 \
  python-path=/opt/satosa_microservices/src/satosa/micro_services:/etc/satosa

WSGIApplicationGroup satosa
WSGIProcessGroup satosa

WSGIScriptAlias / /usr/lib/python3.4/site-packages/satosa/wsgi.py
WSGICallableObject app
WSGIImportScript /usr/lib/python3.4/site-packages/satosa/wsgi.py \
  process-group=satosa application-group=satosa
```

--------------------------------

### Configure Proxy Backend and Frontend Modules

Source: https://github.com/identitypython/satosa/blob/master/doc/SAML2-to-Social_logins.md

Specifies the backend and frontend modules to be used by the SATOSA proxy. Ensure these paths match your directory structure.

```yaml
BACKEND_MODULES:
  - saml2-social/plugins/facebook_backend.yaml
  - saml2-social/plugins/google_backend.yaml
FRONTEND_MODULES:
  - saml2-social/plugins/saml2_frontend.yaml
```

--------------------------------

### Configure Proxy Backend and Frontend Modules

Source: https://github.com/identitypython/satosa/blob/master/doc/saml2-to-oidc.md

Specify the backend and frontend modules to be used by the SATOSA proxy. This involves setting the BACKEND_MODULES and FRONTEND_MODULES parameters in the proxy configuration file.

```yaml
BACKEND_MODULES:
  - saml2-oidc/plugins/openid_backend.yaml
FRONTEND_MODULES:
  - saml2-oidc/plugins/saml2_frontend.yaml
```

--------------------------------

### Create Release Tag

Source: https://github.com/identitypython/satosa/blob/master/release-howto.rst

Create an annotated Git tag for the release version.

```bash
git tag -a -s vX.Y.Z -m "Version X.Y.Z"
```

--------------------------------

### Configure Proxy Backend and Frontend Modules

Source: https://github.com/identitypython/satosa/blob/master/doc/oidc-to-saml2.md

Specifies the backend and frontend modules to be used by the SATOSA proxy.

```yaml
BACKEND_MODULES:
  - "oidc-saml2/plugins/saml2_backend.yaml"
FRONTEND_MODULES:
  - "oidc-saml2/plugins/openid_connect_frontend.yaml"
```

--------------------------------

### Configure Backend and Frontend Modules

Source: https://github.com/identitypython/satosa/blob/master/doc/one-to-many.md

Specifies the SAML2 backend and frontend modules to be used by the proxy. These paths must be correctly set in the 'proxy_conf.yaml' file.

```yaml
BACKEND_MODULES:
  - saml2-saml2/plugins/saml2_backend.yaml
FRONTEND_MODULES:
  - saml2-saml2/plugins/saml2_frontend.yaml
```

--------------------------------

### Create SATOSA User

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Creates a dedicated system user 'satosa' to run the WSGI daemon.

```bash
useradd --home-dir /etc/satosa --no-create-home --system --user-group satosa
```

--------------------------------

### SAML2 Metadata from Local File

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure SAML2 metadata to be loaded from a local file.

```yaml
"metadata":
    local: [idp.xml]
```

--------------------------------

### Enable Discovery Service for IdP Selection

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure the discovery service URL to allow users to choose their identity provider when multiple IdPs are available.

```yaml
config:
  disco_srv: http://disco.example.com
  sp_config: [...]
```

--------------------------------

### Commit Release Changes

Source: https://github.com/identitypython/satosa/blob/master/release-howto.rst

Add and commit updated release files (CHANGELOG.md, setup.py, .bumpversion.cfg) with a descriptive message.

```bash
git add CHANGELOG.md
git add setup.py
git add .bumpversion.cfg
git commit -v -s -m "Release version X.Y.Z"
```

--------------------------------

### Configure Custom Error Documents

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Sets up custom error pages for 404 and 500 errors, aliasing them to a specific HTML file.

```apache
ErrorDocument 404 /error.html
ErrorDocument 500 /error.html

Alias /error.html /var/www/html/error.html
```

--------------------------------

### Generate Package Metadata

Source: https://github.com/identitypython/satosa/blob/master/release-howto.rst

Use this command to generate package metadata and inspect PKG-INFO.

```bash
python setup.py egg_info
```

--------------------------------

### SATOSA Response Micro-service Skeleton

Source: https://github.com/identitypython/satosa/wiki/Anatomy-of-a-response-micro-service

Python code for a basic SATOSA ResponseMicroService, demonstrating initialization and the process method for modifying data attributes.

```python
"""A micro-service example."""

import logging

import satosa
from satosa.micro_services.base import ResponseMicroService

from .helpers import ExtraLogger


# see the logging helper, below
logger = ExtraLogger(logging.getLogger(__name__))


class NameOfMicroservice(ResponseMicroService):
    """
    A micro-service to show an example skeleton.

    Example configuration:

    ```yaml
    module: python.path.example.module_name.NameOfMicroservice
    name: An example micro-service skeleton
    config:
        capitalize_name: True
    ```
    """

    def __init__(self, config, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.capitalize_name = config.get("capitalize_name", False)
        logger.debug("initialized the micro-service")

    # context: satosa.context.Context
    # data: satosa.internal.InternalData
    def process(self, context, data):
        logger.bind("session_id", context.state.session_id)

        logger.debug("running the micro-service")

        # do things with data.attributes
        if self.capitalize_name:
            data.attributes["name"] = [
                value.upper() for value in data.attributes.get("name", [])
            ]

            # log a message
            logger.info("name has been capitilized")

        logger.debug("end of the micro-service")
        # return updated context and data
        return super().process(context, data)
```

--------------------------------

### Create Release Branch

Source: https://github.com/identitypython/satosa/blob/master/release-howto.rst

Create a new Git branch for the release version.

```bash
git branch vX.Y.Z
```

--------------------------------

### Middleware Initialization Interface

Source: https://github.com/identitypython/satosa/wiki/Middlewares

Defines the expected initialization interface for SATOSA middleware. Middleware components receive the next application in the stack and SATOSA's configuration.

```python
from typing import Any
from typing import Callable
from typing import Mapping


def __init__(self, app: Callable, config: Mapping[str, Any]):
    ... 
```

--------------------------------

### Test Name Capitalization Microservice

Source: https://github.com/identitypython/satosa/wiki/Anatomy-of-a-response-micro-service

Tests a SATOSA microservice plugin for name capitalization. It sets up mock context and data, then asserts whether the 'name' attribute is correctly capitalized based on the plugin's configuration.

```python
from unittest import TestCase

from satosa.context import Context
from satosa.state import State
from satosa.internal import AuthenticationInformation
from satosa.internal import InternalData

from python.path.example.module_name import NameOfMicroservice


class NameOfMicroserviceTests(TestCase):
    def setUp(self):
        config = {
            "capitalize_name": True
        }

        plugin = NameOfMicroservice(config, "name", "url")
        plugin.next = lambda context, data: (context, data)

        context = Context()
        context.state = State()
        data = InternalData(
            auth_info=AuthenticationInformation(
                issuer="entity-id-of-issuer",
                auth_class_ref="urn:oasis:names:tc:SAML:2.0:ac:classes:Password",
            ),
            requester="entity-id-of-service",
            requester_name=[{"text": "name of service", "lang": "en"}],
            subject_id="the-subject-identifier",
            subject_type="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
            attributes={
                "edupersontargetedid": ["an-edupersontargetedid-value"],
                "displayname": ["SomeName SomeSurname"],
                "givenname": ["SomeGivenName"],
                "mail": ["someone@example.org"],
                "name": ["SomeName"],
                "surname": ["SomeSurname"],
                "epsa": ["someone@example.org", "staff@example.org"],
                "eppn": ["an-eppn-value@example.org"],
            },
        )

        self.context = context
        self.data = data
        self.plugin = plugin

    def test_should_capitalize(self):
        new_context, new_data = self.plugin.process(self.context, self.data)
        expected = [value.upper() for value in self.data.attributes["name"]]
        self.assertEqual(new_data.attributes["name"], expected)

    def test_should_not_capitalize(self):
        self.plugin.capitalize_name = False
        new_context, new_data = self.plugin.process(self.context, self.data)
        expected = self.data.attributes["name"]
        self.assertEqual(new_data.attributes["name"], expected)
```

--------------------------------

### Set SATOSA Configuration Path Environment Variable

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Use the `SATOSA_CONFIG` environment variable to specify the location of your `proxy_conf.yaml` file if it is not in the working directory.

```bash
set SATOSA_CONFIG=/home/user/proxy_conf.yaml
```

--------------------------------

### Enable WSGI Error Override

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Configures Apache to catch and override SATOSA error responses with custom HTML.

```apache
WSGIErrorOverride On
```

--------------------------------

### SAML2 Frontend Policy Configuration Defaults

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Define default policy settings for SAML response formation, including whether to sign the response and assertion. These defaults are used if no specific SP overrides are provided.

```yaml
config:
  idp_config:
    service:
      idp:
        policy:
          default:
            sign_response: True
            sign_assertion: False
          <sp entityID>:
            ...
```

--------------------------------

### Use Memorized IdP with ForceAuthn

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure `use_memorized_idp_when_force_authn` to `True` to allow reusing the memorized IdP even when `ForceAuthn` is set in the request.

```yaml
config:
  memorize_idp: True
  use_memorized_idp_when_force_authn: True
  [...]
```

--------------------------------

### SAML2 Metadata from Remote URL

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure SAML2 metadata to be loaded from a remote URL, with an option to specify a certificate.

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

--------------------------------

### Custom Logging Helper for Micro-services

Source: https://github.com/identitypython/satosa/wiki/Anatomy-of-a-response-micro-service

A Python helper class extending LoggerAdapter to add bound context to log messages, useful for tracking requests across micro-services.

```python
from logging import LoggerAdapter


class ExtraLogger(LoggerAdapter):
    def __init__(self, logger, extra={}):
        super().__init__(logger, extra)

    def bind(self, key, value):
        self.extra[key] = value

    def process(self, msg, kwargs):
        extra = " ".join(
            "[{key}: {value}]".format(key=key, value=value)
            for key, value in self.extra.items()
        )
        logline = "{extra} {msg}".format(extra=extra, msg=msg).lstrip()
        return logline, kwargs
```

--------------------------------

### Memorize IdP Selection

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Enable `memorize_idp` to `True` to retain the user's last selected IdP for the duration of the session, skipping the discovery service.

```yaml
config:
  memorize_idp: True
  [...]
```

--------------------------------

### Git Configuration for Signed Commits and Merges

Source: https://github.com/identitypython/satosa/wiki/satosa-core-development-guidelines

This configuration enables GPG signing for commits and merges, ensuring code integrity. It specifies the user's email, name, and signing key, and enforces signed commits and non-fast-forward merges.

```bash
[user]
    email = john@sunet.se
    name = John Van de Meulebrouck Brendgard
    signingkey = 807A5FD4B3337B77

[pull]
    ff = yes

[merge]
    gpgsign = true
    ff = no

[commit]
    gpgsign = true
```

--------------------------------

### Push Release Tag and Changes to GitHub

Source: https://github.com/identitypython/satosa/blob/master/release-howto.rst

Push the release tag and associated changes to the GitHub repository.

```bash
git push --follow-tags origin vX.Y.Z
git push --follow-tags origin vX.Y.Z:vX.Y.Z
```

--------------------------------

### Configure SAML2 Name ID Formats

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Specify desired Name ID formats for SP metadata and authentication requests. Ensure the IdP supports the requested formats.

```yaml
config:
  sp_config:
    service:
      sp:
       name_id_format:
       - urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
       - urn:oasis:names:tc:SAML:2.0:nameid-format:transient
       name_id_policy_format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
```

--------------------------------

### Restart Apache Server

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Restarts the Apache HTTP server to apply configuration changes.

```bash
systemctl restart httpd
```

--------------------------------

### Upgrade pySAML2

Source: https://github.com/identitypython/satosa/blob/master/doc/mod_wsgi.md

Upgrades to the latest release of the pySAML2 library.

```bash
pip install --upgrade pysaml2
```

--------------------------------

### Render Long Description to HTML

Source: https://github.com/identitypython/satosa/blob/master/release-howto.rst

Verify that the long description renders as valid reStructuredText using rst2html.py.

```bash
python setup.py --long-description | rst2html > test.html
```

--------------------------------

### Mirror SAML ForceAuthn Option

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Set `mirror_force_authn` to `True` to propagate the `ForceAuthn` flag from incoming SAML requests to upstream IdP requests.

```yaml
config:
  mirror_force_authn: True
  [...]
```

--------------------------------

### Allow all but one SP for a target IdP

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure the `DecideIfRequesterIsAllowed` microservice to allow all Service Providers (SPs) except for a specific one for a given Identity Provider (IdP). This is useful for broad acceptance with a few exceptions.

```yaml
rules:
    target_entity_id1:
        allow: ["*"]
        deny: ["requester1"]
```

--------------------------------

### Configure Assertion Consumer Service Selection Strategy

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Set `acs_selection_strategy` to `prefer_matching_host` to prioritize an ACS URL matching the request host, falling back to the first ACS if no match is found.

```yaml
config:
  acs_selection_strategy: prefer_matching_host
  [...]
```

--------------------------------

### SAML2 Authentication Context Class Reference Mapping

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Map target provider identifiers to specific Authentication Context Class References (ACRs). Includes a default ACR for unspecified providers.

```yaml
config:
    [...] 
    acr_mapping:
        "": "urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified"
        "https://accounts.google.com": "http://eidas.europa.eu/LoA/low"
```

--------------------------------

### Deny all but one SP for a target IdP

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Use the `DecideIfRequesterIsAllowed` microservice to deny all Service Providers (SPs) except for a specified one for a given Identity Provider (IdP). This configuration ensures that only a single, explicitly allowed SP can send requests to the target IdP.

```yaml
rules:
    target_entity_id1:
        allow: ["requester1"]
        deny: ["*"]
```

--------------------------------

### Allow specific requesters for a target IdP

Source: https://github.com/identitypython/satosa/blob/master/doc/README.md

Configure the `DecideIfRequesterIsAllowed` microservice to specify which Service Providers (SPs) are allowed to send requests to a particular Identity Provider (IdP). This is useful when a SAMLMirrorFrontend needs to support additional SPs for specific IdPs.

```yaml
rules:
    target_entity_id1:
        allow: ["requester1", "requester2"]
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.