diff options
author | Ivan Kanakarakis <ivan.kanak@gmail.com> | 2020-09-12 23:38:36 +0300 |
---|---|---|
committer | Ivan Kanakarakis <ivan.kanak@gmail.com> | 2020-09-12 23:38:36 +0300 |
commit | 351bb6a7f09edee5eac9e2e895493d123642c6b4 (patch) | |
tree | 8f0b873f185ec5cea3f63bded3df23eaa574ea03 | |
parent | 88951cdbfa27a77872b51a20ca28be2afffe0c9f (diff) | |
download | pysaml2-351bb6a7f09edee5eac9e2e895493d123642c6b4.tar.gz |
Rephrase documentation parts
Signed-off-by: Ivan Kanakarakis <ivan.kanak@gmail.com>
-rw-r--r-- | docs/howto/config.rst | 72 |
1 files changed, 43 insertions, 29 deletions
diff --git a/docs/howto/config.rst b/docs/howto/config.rst index 9883a3eb..c4279974 100644 --- a/docs/howto/config.rst +++ b/docs/howto/config.rst @@ -235,10 +235,12 @@ 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', - }], + 'encryption_keypairs': [ + { + 'key_file': BASE_DIR + '/certificates/private.key', + 'cert_file': BASE_DIR + '/certificates/public.cert', + }, + ], metadata ^^^^^^^^ @@ -273,7 +275,7 @@ For example:: { "url": "https://mdq.thaturl.org/", "disable_ssl_certificate_validation": True, - "check_validity": False + "check_validity": False, }, ], }, @@ -286,9 +288,11 @@ 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 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 @@ -406,8 +410,8 @@ difference you are prepared to accept. allow_unknown_attributes """""""""""""""""""""""" -Indicates that attributes not configured in attribute-mapping, with -unsupported attribute name format, will not be discarded. +Indicates that attributes that are not recognized (they are not configured in +attribute-mapping), will not be discarded. Default to False. xmlsec_binary @@ -465,7 +469,9 @@ 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. + +When verifying a signed AuthnRequest ignore the signature and verify the +certificate. policy """""" @@ -914,14 +920,14 @@ 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. +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 signatures must be valid. +Indicates that the certificate used in sign SAML messages must be valid. Default to False. logout_requests_signed @@ -1088,21 +1094,29 @@ 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. As EntityAttributes, *entity_category_support* or *entity_category*. -2. As Policy, it acts like a filter. +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. -Entity Category and Entity Category support can be configured as follow:: +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], + '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', @@ -1114,21 +1128,21 @@ Entity Category and Entity Category support can be configured as follow:: In the metadata we'll then have:: <md:Extensions> - <mdattr:EntityAttributes> + <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: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> + </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. +If the entity categories are configurated in the policy section, they will act +as filters on the released attributes. Example:: "policy": { - "default": { + "default": { "lifetime": {"minutes": 15}, - - # if the sp are not conform to entity_categories the attributes will not be released + # if the SP is not conform to entity_categories + # the attributes will not be released "entity_categories": ["refeds",], |