Additional Documentation

1 files changed, 97 insertions, 11 deletions

diff --git a/docs/howto/config.rst b/docs/howto/config.rst
index 13edf19d..9883a3eb 100644
--- a/docs/howto/config.rst
+++ b/docs/howto/config.rst
@@ -159,16 +159,6 @@ Since *to* in most cases is the inverse of the *fro* file, the
 software allows you only to specify one of them, and it will
 automatically create the other.
 
-cert_file
-^^^^^^^^^
-
-Example::
-
-    cert_file: "cert.pem"
-
-This is the public part of the service private/public key pair.
-*cert_file* must be a PEM formatted file with a single certificate.
-
 contact_person
 ^^^^^^^^^^^^^^
 
@@ -228,6 +218,28 @@ Example::
 of the service. This is currently used both to encrypt/sign assertions and as
 the client key in an HTTPS session.
 
+cert_file
+^^^^^^^^^
+
+Example::
+
+    cert_file: "cert.pem"
+
+This is the public part of the service private/public key pair.
+*cert_file* must be a PEM formatted file with a single certificate.
+
+
+encryption_keypairs
+^^^^^^^^^^^^^^^^^^^
+
+Indicates which certificates will be used for encryption capabilities::
+
+    # Encryption
+    'encryption_keypairs': [{
+        'key_file': BASE_DIR + '/certificates/private.key',
+        'cert_file': BASE_DIR + '/certificates/public.cert',
+    }],
+
 metadata
 ^^^^^^^^
 
@@ -258,6 +270,11 @@ For example::
                 "cert": "ukfederation-mdq.pem",
                 "freshness_period": "P0Y0M0DT2H0M0S",
             },
+            {
+                "url": "https://mdq.thaturl.org/",
+                "disable_ssl_certificate_validation": True,
+                "check_validity": False
+            },
         ],
     },
 
@@ -269,6 +286,10 @@ metadata signing certificates should be used.  These public keys must be
 acquired by some secure out-of-band method before being placed on the local
 file system.
 
+When using MDQ or remote, the paramenter *disable_ssl_certificate_validation*
+prevents that the validity of ssl certificate involved in the https connection
+will be verified. *check_validity* to False accept as valid the metadata that has expired.
+
 When using MDQ, the `freshness_period` option can be set to define a period for
 which the metadata fetched from the the MDQ server are considered fresh. After
 that period has passed the metadata are not valid anymore and must be fetched
@@ -382,6 +403,13 @@ difference you are prepared to accept.
 .. note:: This will indiscriminately affect all time comparisons.
     Hence your server may accept a statement that in fact is too old.
 
+allow_unknown_attributes
+""""""""""""""""""""""""
+
+Indicates that attributes not configured in attribute-mapping, with
+unsupported attribute name format, will not be discarded.
+Default to False.
+
 xmlsec_binary
 ^^^^^^^^^^^^^
 
@@ -435,6 +463,9 @@ sign_response
 Specifies if the IdP should sign the authentication response or not. Can be
 True or False. Default is False.
 
+want_authn_requests_only_with_valid_cert
+""""""""""""""""""""""""""""""""""""""""
+This option make mandatory the presence of the SP cert in a (signed) AuthnRequest.
 
 policy
 """"""
@@ -622,7 +653,6 @@ Example::
         }
     }
 
-
 hide_assertion_consumer_service
 """""""""""""""""""""""""""""""
 
@@ -881,6 +911,19 @@ Example::
         },
     },
 
+only_use_keys_in_metadata
+"""""""""""""""""""""""""
+
+If True prevents that the certificate contained in a
+SAML message, if present, will be used for signature verification.
+Default True.
+
+validate_certificate
+""""""""""""""""""""
+
+Indicates that the certificate used in signatures must be valid.
+Default to False.
+
 logout_requests_signed
 """"""""""""""""""""""
 
@@ -1046,3 +1089,46 @@ Other considerations
 Entity Categories
 -----------------
 Entity categories and their attributes are defined in src/saml2/entity_category/<registrar of entcat>.py
+We can configure Entity Categories in pysaml2 in two ways:
+
+1. As EntityAttributes, *entity_category_support* or *entity_category*.
+2. As Policy, it acts like a filter.
+
+Entity Category and Entity Category support can be configured as follow::
+
+    'debug' : True,
+    'xmlsec_binary': get_xmlsec_binary([/usr/bin/xmlsec1']),
+    'entityid': '%s/metadata' % BASE_URL,
+
+    # or entity_category: [ ... ]
+    'entity_category_support': [edugain.COCO, # "http://www.geant.net/uri/dataprotection-code-of-conduct/v1"
+                                refeds.RESEARCH_AND_SCHOLARSHIP],
+
+    'attribute_map_dir': 'data/attribute-maps',
+    'description': 'SAML2 IDP',
+
+    'service': {
+        'idp': {
+    ...
+
+In the metadata we'll then have::
+
+    <md:Extensions>
+    <mdattr:EntityAttributes>
+        <saml:Attribute Name="http://macedir.org/entity-category-support" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
+        <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://www.geant.net/uri/dataprotection-code-of-conduct/v1</saml:AttributeValue>
+        <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://refeds.org/category/research-and-scholarship</saml:AttributeValue>
+        </saml:Attribute>
+    </mdattr:EntityAttributes>
+
+If Entity Category would be configured instead in the policy section, as follow, it
+will acts like a filter on the released attributes.
+
+Example::
+
+    "policy": {
+    "default": {
+        "lifetime": {"minutes": 15},
+
+        # if the sp are not conform to entity_categories the attributes will not be released
+        "entity_categories": ["refeds",],