Merge pull request #715 from peppelinux/nameid_format_example

Document more configuration options and entity category settings

Author: c00kiemon5ter

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,30 @@ 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 +272,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 +288,12 @@ 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 the parameter *check_validity* is set to False metadata that have expired
+will be accepted as valid.
+
+When the paramenter *disable_ssl_certificate_validation* is set to True the
+validity of ssl certificate will be skipped.
+
 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 +407,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 that are not recognized (they are not configured in
+attribute-mapping), will not be discarded.
+Default to False.
+
 xmlsec_binary
 ^^^^^^^^^^^^^
 
@@ -435,6 +467,11 @@ 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
+""""""""""""""""""""""""""""""""""""""""
+
+When verifying a signed AuthnRequest ignore the signature and verify the
+certificate.
 
 policy
 """"""
@@ -599,7 +636,7 @@ metadata of an entity.
 Example::
 
     "service": {
-        "idp": {
+        "sp": {
             "name_id_format": [
                 "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
                 "urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
@@ -622,7 +659,6 @@ Example::
         }
     }
 
-
 hide_assertion_consumer_service
 """""""""""""""""""""""""""""""
 
@@ -881,6 +917,19 @@ Example::
         },
     },
 
+only_use_keys_in_metadata
+"""""""""""""""""""""""""
+
+If set to False, the certificate contained in a SAML message will be used for
+signature verification.
+Default True.
+
+validate_certificate
+""""""""""""""""""""
+
+Indicates that the certificate used in sign SAML messages must be valid.
+Default to False.
+
 logout_requests_signed
 """"""""""""""""""""""
 
@@ -1045,4 +1094,55 @@ Other considerations
 
 Entity Categories
 -----------------
-Entity categories and their attributes are defined in src/saml2/entity_category/<registrar of entcat>.py
+
+Entity categories and their attributes are defined in
+src/saml2/entity_category/<registrar-of-entity-category>.py.
+We can configure Entity Categories in pysaml2 in two ways:
+
+1. Using the configuration options *entity_category_support* or
+   *entity_category*, to generate the appropriate EntityAttribute metadata
+   elements.
+2. Using the configuration option *entity_categories* as part of the policy
+   configuration, to make the entity category work as a filter on the
+   attributes that will be released.
+
+If the entity categories are configured as metadata, 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 the entity categories are configurated in the policy section, they will act
+as filters on the released attributes.
+
+Example::
+
+    "policy": {
+      "default": {
+        "lifetime": {"minutes": 15},
+        # if the SP is not conform to entity_categories
+        # the attributes will not be released
+        "entity_categories": ["refeds",],