<commit_before>.. _howto_config:

Configuration of pySAML2 entities
=================================

Whether you plan to run a pySAML2 Service Provider, Identity provider or an
attribute authority you have to configure it. The format of the configuration
file is the same disregarding which type of service you plan to run.
What differs is some of the directives.
Below you will find a list of all the used directives in alphabetic order.
The configuration is written as a python module which contains a named
dictionary ("CONFIG") that contains the configuration directives.

The basic structure of the configuration file is therefor like this::

    from saml2 import BINDING_HTTP_REDIRECT

    CONFIG = {
        "entityid" : "http://saml.example.com:saml/idp.xml",
        "name" : "<NAME>",
        "service": {
            "idp": {
                "endpoints" : {
                    "single_sign_on_service" : [
                            ("http://saml.example.com:saml:8088/sso",
                                BINDING_HTTP_REDIRECT)],
                    "single_logout_service": [
                            ("http://saml.example.com:saml:8088/slo",
                                BINDING_HTTP_REDIRECT)]
                },
                ...
            }
        },
        "key_file" : "my.key",
        "cert_file" : "ca.pem",
        "xmlsec_binary" : "/usr/local/bin/xmlsec1",
        "metadata": {
            "local": ["edugain.xml"],
        },
        "attribute_map_dir" : "attributemaps",
        ...
    }

.. note:: You can build the metadata file for your services directly from the
    configuration.The make_metadata.py script in the pySAML2 tools directory
    will do that for you.

Configuration directives
::::::::::::::::::::::::

.. contents::
    :local:
    :backlinks: entry

General directives
------------------

attribute_map_dir
^^^^^^^^^^^^^^^^^

Format::

    "attribute_map_dir": "attribute-maps"
    
Points to a directory which has subdirectories, one per name-format you
expect to support. So a typical tree would be.::

    attribute-maps 
        |
        +-- urn:oases:names:tc:SAML:2.0:name-format:basic
        |                       |
        |                       +-- fro
        |                       +-- to
        |
        +-- urn:oases:names:tc:SAML:2.0:name-format:uri
                                |
                                +-- fro
                                +-- to
        
The *to* and *fro* files then contain the mapping between the names.
The start of the urn:oases:names:tc:SAML:2.0:name-format:uri/fro file
for instance looks like this::

    {
      'urn:oid:1.3.6.1.4.1.5923.1.1.1.2': 'eduPersonNickname',
      'urn:oid:1.3.6.1.4.1.5923.1.1.1.9': 'eduPersonScopedAffiliation',
      'urn:oid:1.3.6.1.4.1.5923.172.16.31.10': 'eduPersonAssurance',
      'urn:oid:1.3.6.1.4.1.5923.172.16.31.10': 'eduPersonTargetedID',
      'urn:oid:1.3.6.1.4.1.5923.1.1.1.4': 'eduPersonOrgUnitDN',
      'urn:oid:1.3.6.1.4.1.5923.1.1.1.1': 'eduPersonAffiliation',

As you see the format is again a python dictionary where the key is the
name to convert from and the value is the name to convert to.
    
Since *to* in most cases are the inverse of the *fro* file, the 
software allowes you to only specify one of them and it will 
automatically create the other.

cert_file
^^^^^^^^^

Format::

    cert_file: "cert.pem"

This is the public part of the service private/public key pair.<commit_msg>Updated the attribute maps docs<commit_after>.. _howto_config:

Configuration of pySAML2 entities
=================================

Whether you plan to run a pySAML2 Service Provider, Identity provider or an
attribute authority you have to configure it. The format of the configuration
file is the same disregarding which type of service you plan to run.
What differs is some of the directives.
Below you will find a list of all the used directives in alphabetic order.
The configuration is written as a python module which contains a named
dictionary ("CONFIG") that contains the configuration directives.

The basic structure of the configuration file is therefor like this::

    from saml2 import BINDING_HTTP_REDIRECT

    CONFIG = {
        "entityid" : "http://saml.example.com:saml/idp.xml",
        "name" : "<NAME>",
        "service": {
            "idp": {
                "endpoints" : {
                    "single_sign_on_service" : [
                            ("http://saml.example.com:saml:8088/sso",
                                BINDING_HTTP_REDIRECT)],
                    "single_logout_service": [
                            ("http://saml.example.com:saml:8088/slo",
                                BINDING_HTTP_REDIRECT)]
                },
                ...
            }
        },
        "key_file" : "my.key",
        "cert_file" : "ca.pem",
        "xmlsec_binary" : "/usr/local/bin/xmlsec1",
        "metadata": {
            "local": ["edugain.xml"],
        },
        "attribute_map_dir" : "attributemaps",
        ...
    }

.. note:: You can build the metadata file for your services directly from the
    configuration.The make_metadata.py script in the pySAML2 tools directory
    will do that for you.

Configuration directives
::::::::::::::::::::::::

.. contents::
    :local:
    :backlinks: entry

General directives
------------------

attribute_map_dir
^^^^^^^^^^^^^^^^^

Format::

    "attribute_map_dir": "attribute-maps"
    
Points to a directory which has the attribute maps in Python modules.
A typical map file will looks like this::

    MAP = {
        "identifier": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic",
        "fro": {
            'urn:mace:dir:attribute-def:aRecord': 'aRecord',
            'urn:mace:dir:attribute-def:aliasedEntryName': 'aliasedEntryName',
            'urn:mace:dir:attribute-def:aliasedObjectName': 'aliasedObjectName',
            'urn:mace:dir:attribute-def:associatedDomain': 'associatedDomain',
            'urn:mace:dir:attribute-def:associatedName': 'associatedName',
            ...
            },
        "to": {
            'aRecord': 'urn:mace:dir:attribute-def:aRecord',
            'aliasedEntryName': 'urn:mace:dir:attribute-def:aliasedEntryName',
            'aliasedObjectName': 'urn:mace:dir:attribute-def:aliasedObjectName',
            'associatedDomain': 'urn:mace:dir:attribute-def:associatedDomain',
            'associatedName': 'urn:mace:dir:attribute-def:associatedName',
            ...
        }
    }

The attribute map module contains a MAP dictionary with three items.  The
`identifier` item is the name-format you expect to support.
The *to* and *fro* sub-dictionaries then contain the mapping between the names.

As you see the format is again a python dictionary where the key is the
name to convert from and the value is the name to convert to.
    
Since *to* in most cases are the inverse of the *fro* file, the 
software allowes you to only specify one of them and it will 
automatically create the other.

cert_file
^^^^^^^^^

Format::

    cert_file: "cert.pem"

This is the public part of the service private/public key pair.
{'fraction_non_alphanumeric': 0.1272930962050133, 'fraction_numerical': 0.017924660411707045, 'mean_word_length': 2.241942805265547, 'pattern_counts': {'":': 15, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 8}, 'pii_count': 12, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1959980', 'n_tokens_mistral': 2164, 'n_tokens_neox': 2044, 'n_words': 611}