1.. _howto_config: 2 3Configuration of pySAML2 entities 4================================= 5 6Whether you plan to run a pySAML2 Service Provider, Identity Provider or an 7attribute authority, you have to configure it. The format of the configuration 8file is the same regardless of which type of service you plan to run. 9What differs are some of the directives. 10Below you will find a list of all the used directives in alphabetical order. 11The configuration is written as a python module which contains a named 12dictionary ("CONFIG") that contains the configuration directives. 13 14The basic structure of the configuration file is therefore like this:: 15 16 from saml2 import BINDING_HTTP_REDIRECT 17 18 CONFIG = { 19 "entityid": "http://saml.example.com:saml/idp.xml", 20 "name": "Rolands IdP", 21 "service": { 22 "idp": { 23 "endpoints": { 24 "single_sign_on_service": [ 25 ( 26 "http://saml.example.com:saml:8088/sso", 27 BINDING_HTTP_REDIRECT, 28 ), 29 ], 30 "single_logout_service": [ 31 ( 32 "http://saml.example.com:saml:8088/slo", 33 BINDING_HTTP_REDIRECT, 34 ), 35 ], 36 }, 37 ... 38 } 39 }, 40 "key_file": "my.key", 41 "cert_file": "ca.pem", 42 "xmlsec_binary": "/usr/local/bin/xmlsec1", 43 "delete_tmpfiles": True, 44 "metadata": { 45 "local": [ 46 "edugain.xml", 47 ], 48 }, 49 "attribute_map_dir": "attributemaps", 50 ... 51 } 52 53.. note:: You can build the metadata file for your services directly from the 54 configuration. The make_metadata.py script in the pySAML2 tools directory 55 will do that for you. 56 57Configuration directives 58:::::::::::::::::::::::: 59 60.. contents:: 61 :local: 62 :backlinks: entry 63 64General directives 65------------------ 66 67logging 68^^^^^^^ 69 70The logging configuration format is the python logging format. 71The configuration is passed to the python logging dictionary configuration handler, 72directly. 73 74Example:: 75 76 "logging": { 77 "version": 1, 78 "formatters": { 79 "simple": { 80 "format": "[%(asctime)s] [%(levelname)s] [%(name)s.%(funcName)s] %(message)s", 81 }, 82 }, 83 "handlers": { 84 "stdout": { 85 "class": "logging.StreamHandler", 86 "stream": "ext://sys.stdout", 87 "level": "DEBUG", 88 "formatter": "simple", 89 }, 90 }, 91 "loggers": { 92 "saml2": { 93 "level": "DEBUG" 94 }, 95 }, 96 "root": { 97 "level": "DEBUG", 98 "handlers": [ 99 "stdout", 100 ], 101 }, 102 }, 103 104The exapmle configuration above will enable DEBUG logging to stdout. 105 106 107debug 108^^^^^ 109 110Example:: 111 112 debug: 1 113 114Whether debug information should be sent to the log file. 115 116additional_cert_files 117^^^^^^^^^^^^^^^^^^^^^ 118 119Example:: 120 121 additional_cert_files: ["other-cert.pem", "another-cert.pem"] 122 123Additional public certs that will be listed. Useful during cert/key rotation or 124if you need to include a certificate chain. 125 126Each entry in *additional_cert_files* must be a PEM formatted file with a single certificate. 127 128entity_attributes 129^^^^^^^^^^^^^^^^^ 130 131Generates an ``Attribute`` element with the given NameFormat, Name, FriendlyName and 132values, each as an ``AttributeValue`` element. 133 134The element is added under the generated metadata ``EntityDescriptor`` as an 135``Extension`` element under the ``EntityAttributes`` element. 136 137And omit 138 139Example:: 140 141 "entity_attributes": [ 142 { 143 "name_format": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri", 144 "name": "urn:oasis:names:tc:SAML:profiles:subject-id:req", 145 # "friendly_name" is not set 146 "values": ["any"], 147 }, 148 ] 149 150 151assurance_certification 152^^^^^^^^^^^^^^^^^^^^^^^ 153 154Example:: 155 156 "assurance_specification": [ 157 "https://refeds.org/sirtfi", 158 ] 159 160Generates an ``Attribute`` element with name-format 161``urn:oasis:names:tc:SAML:2.0:attrname-format:uri`` and name 162``urn:oasis:names:tc:SAML:attribute:assurance-certification`` that contains 163``AttributeValue`` elements with the given values from the list. 164The element is added under the generated metadata ``EntityDescriptor`` as an 165``Extension`` element under the ``EntityAttributes`` element. 166 167Read more about `representing assurance information at the specification <https://wiki.oasis-open.org/security/SAML2IDAssuranceProfile>`_. 168 169attribute_map_dir 170^^^^^^^^^^^^^^^^^ 171 172Points to a directory which has the attribute maps in Python modules. 173 174Example:: 175 176 "attribute_map_dir": "attribute-maps" 177 178A typical map file will look like this:: 179 180 MAP = { 181 "identifier": "urn:oasis:names:tc:SAML:2.0:attrname-format:basic", 182 "fro": { 183 'urn:mace:dir:attribute-def:aRecord': 'aRecord', 184 'urn:mace:dir:attribute-def:aliasedEntryName': 'aliasedEntryName', 185 'urn:mace:dir:attribute-def:aliasedObjectName': 'aliasedObjectName', 186 'urn:mace:dir:attribute-def:associatedDomain': 'associatedDomain', 187 'urn:mace:dir:attribute-def:associatedName': 'associatedName', 188 ... 189 }, 190 "to": { 191 'aRecord': 'urn:mace:dir:attribute-def:aRecord', 192 'aliasedEntryName': 'urn:mace:dir:attribute-def:aliasedEntryName', 193 'aliasedObjectName': 'urn:mace:dir:attribute-def:aliasedObjectName', 194 'associatedDomain': 'urn:mace:dir:attribute-def:associatedDomain', 195 'associatedName': 'urn:mace:dir:attribute-def:associatedName', 196 ... 197 } 198 } 199 200The attribute map module contains a MAP dictionary with three items. The 201`identifier` item is the name-format you expect to support. 202The *to* and *fro* sub-dictionaries then contain the mapping between the names. 203 204As you see the format is again a python dictionary where the key is the 205name to convert from, and the value is the name to convert to. 206 207Since *to* in most cases is the inverse of the *fro* file, the 208software allows you only to specify one of them, and it will 209automatically create the other. 210 211contact_person 212^^^^^^^^^^^^^^ 213 214This is only used by *make_metadata.py* when it constructs the metadata for 215the service described by the configuration file. 216This is where you describe who can be contacted if questions arise 217about the service or if support is needed. The possible types are according to 218the standard **technical**, **support**, **administrative**, **billing** 219and **other**.:: 220 221 contact_person: [ 222 { 223 "givenname": "Derek", 224 "surname": "Jeter", 225 "company": "Example Co.", 226 "mail": ["jeter@example.com"], 227 "type": "technical", 228 }, 229 { 230 "givenname": "Joe", 231 "surname": "Girardi", 232 "company": "Example Co.", 233 "mail": "girardi@example.com", 234 "type": "administrative", 235 }, 236 ] 237 238entityid 239^^^^^^^^ 240 241Example:: 242 243 entityid: "http://saml.example.com/sp" 244 245The globally unique identifier of the entity. 246 247.. note:: It is recommended that the entityid should point to a real 248 webpage where the metadata for the entity can be found. 249 250 251key_file 252^^^^^^^^ 253 254Example:: 255 256 key_file: "key.pem" 257 258*key_file* is the name of a PEM formatted file that contains the private key 259of the service. This is currently used both to encrypt/sign assertions and as 260the client key in an HTTPS session. 261 262cert_file 263^^^^^^^^^ 264 265Example:: 266 267 cert_file: "cert.pem" 268 269This is the public part of the service private/public key pair. 270*cert_file* must be a PEM formatted file with a single certificate. 271 272 273encryption_keypairs 274^^^^^^^^^^^^^^^^^^^ 275 276Indicates which certificates will be used for encryption capabilities:: 277 278 # Encryption 279 'encryption_keypairs': [ 280 { 281 'key_file': BASE_DIR + '/certificates/private.key', 282 'cert_file': BASE_DIR + '/certificates/public.cert', 283 }, 284 ], 285 286metadata 287^^^^^^^^ 288 289Contains a list of places where metadata can be found. This can be 290 291* a local directory accessible on the server the service runs on 292* a local file accessible on the server the service runs on 293* a remote URL serving aggregate metadata 294* a metadata query protocol (MDQ) service URL 295 296For example:: 297 298 "metadata": { 299 "local": [ 300 "/opt/metadata" 301 "metadata.xml", 302 "vo_metadata.xml", 303 ], 304 "remote": [ 305 { 306 "url": "https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2", 307 "cert": "kalmar2.cert", 308 }, 309 ], 310 "mdq": [ 311 { 312 "url": "http://mdq.ukfederation.org.uk/", 313 "cert": "ukfederation-mdq.pem", 314 "freshness_period": "P0Y0M0DT2H0M0S", 315 }, 316 { 317 "url": "https://mdq.thaturl.org/", 318 "disable_ssl_certificate_validation": True, 319 "check_validity": False, 320 }, 321 ], 322 }, 323 324The above configuration means that the service should read two aggregate local 325metadata files, one aggregate metadata file from a remote server, and query a 326remote MDQ server. To verify the authenticity of the metadata aggregate 327downloaded from the remote server and the MDQ server local copies of the 328metadata signing certificates should be used. These public keys must be 329acquired by some secure out-of-band method before being placed on the local 330file system. 331 332When the parameter *check_validity* is set to False metadata that have expired 333will be accepted as valid. 334 335When the paramenter *disable_ssl_certificate_validation* is set to True the 336validity of ssl certificate will be skipped. 337 338When using MDQ, the `freshness_period` option can be set to define a period for 339which the metadata fetched from the the MDQ server are considered fresh. After 340that period has passed the metadata are not valid anymore and must be fetched 341again. The period must be in the format defined in 342`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`_ 343or `RFC3999 <https://tools.ietf.org/html/rfc3339#appendix-A>`_. 344 345By default, if `freshness_period` is not defined, the metadata are refreshed 346every 12 hours (`P0Y0M0DT12H0M0S`). 347 348 349organization 350^^^^^^^^^^^^ 351 352Only used by *make_metadata.py*. 353Where you describe the organization responsible for the service.:: 354 355 "organization": { 356 "name": [ 357 ("Example Company", "en"), 358 ("Exempel AB", "se") 359 ], 360 "display_name": ["Exempel AB"], 361 "url": [ 362 ("http://example.com", "en"), 363 ("http://exempel.se", "se"), 364 ], 365 } 366 367.. note:: You can specify the language of the name, or the language used on 368 the webpage, by entering a tuple, instead of a simple string, 369 where the second part is the language code. If you don't specify a 370 language, the default is "en" (English). 371 372preferred_binding 373^^^^^^^^^^^^^^^^^ 374 375Which binding should be preferred for a service. 376Example configuration:: 377 378 "preferred_binding" = { 379 "single_sign_on_service": [ 380 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 381 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 382 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact', 383 ], 384 "single_logout_service": [ 385 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP', 386 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 387 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 388 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact', 389 ], 390 } 391 392The available services are: 393 394* manage_name_id_service 395* assertion_consumer_service 396* name_id_mapping_service 397* authn_query_service 398* attribute_service 399* authz_service 400* assertion_id_request_service 401* artifact_resolution_service 402* attribute_consuming_service 403 404 405service 406^^^^^^^ 407 408Which services the server will provide; those are combinations of "idp", "sp" 409and "aa". 410So if a server is a Service Provider (SP) then the configuration 411could look something like this:: 412 413 "service": { 414 "sp": { 415 "name": "Rolands SP", 416 "endpoints": { 417 "assertion_consumer_service": ["http://localhost:8087/"], 418 "single_logout_service": [ 419 ( 420 "http://localhost:8087/slo", 421 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 422 ), 423 ], 424 }, 425 "required_attributes": [ 426 "surname", 427 "givenname", 428 "edupersonaffiliation", 429 ], 430 "optional_attributes": ["title"], 431 "idp": { 432 "urn:mace:umu.se:saml:roland:idp": None, 433 }, 434 } 435 }, 436 437There are two options common to all services: 'name' and 'endpoints'. 438The remaining options are specific to one or the other of the service types. 439Which one is specified alongside the name of the option. 440 441accepted_time_diff 442^^^^^^^^^^^^^^^^^^ 443 444If your computer and another computer that you are communicating with are not 445in sync regarding the computer clock, then here you can state how big a 446difference you are prepared to accept. 447 448.. note:: This will indiscriminately affect all time comparisons. 449 Hence your server may accept a statement that in fact is too old. 450 451allow_unknown_attributes 452"""""""""""""""""""""""" 453 454Indicates that attributes that are not recognized (they are not configured in 455attribute-mapping), will not be discarded. 456Default to False. 457 458xmlsec_binary 459^^^^^^^^^^^^^ 460 461Currently xmlsec1 binaries are used for all the signing and encryption stuff. 462This option defines where the binary is situated. 463 464Example:: 465 466 "xmlsec_binary": "/usr/local/bin/xmlsec1", 467 468delete_tmpfiles 469^^^^^^^^^^^^^^^ 470 471In many cases temporary files will have to be created during the 472encryption/decryption/signing/validation process. 473This option defines whether these temporary files will be automatically deleted when 474they are no longer needed. Setting this to False, will keep these files until they are 475manually deleted or automatically deleted by the OS (i.e Linux rules for /tmp). 476Absence of this option, defaults to True. 477 478 479valid_for 480^^^^^^^^^ 481 482How many *hours* this configuration is expected to be accurate.:: 483 484 "valid_for": 24 485 486This, of course, is only used by *make_metadata.py*. 487The server will not stop working when this amount of time has elapsed :-). 488 489Specific directives 490------------------- 491 492Directives that are specific to a certain type of service. 493 494idp/aa 495^^^^^^ 496 497Directives that are specific to an IdP or AA service instance. 498 499sign_assertion 500"""""""""""""" 501 502Specifies if the IdP should sign the assertion in an authentication response 503or not. Can be True or False. Default is False. 504 505sign_response 506""""""""""""" 507 508Specifies if the IdP should sign the authentication response or not. Can be 509True or False. Default is False. 510 511want_authn_requests_only_with_valid_cert 512"""""""""""""""""""""""""""""""""""""""" 513 514When verifying a signed AuthnRequest ignore the signature and verify the 515certificate. 516 517policy 518"""""" 519 520If the server is an IdP and/or an AA, then there might be reasons to do things 521differently depending on who is asking (which is the requesting service); the 522policy is where this behaviour is specified. 523 524The keys are SP entity identifiers, Registration Authority names, or 'default'. 525First, the policy for the requesting service is looked up using the SP entityID. 526If no such policy is found, and if the SP metadata includes a Registration 527Authority then a policy for the registration authority is looked up using the 528Registration Authority name. If no policy is found, then the 'default' is looked 529up. If there is no default and only SP entity identifiers as keys, then the 530server will only accept connections from the specified SPs. 531 532An example might be:: 533 534 "service": { 535 "idp": { 536 "policy": { 537 # a policy for a service 538 "urn:mace:example.com:saml:roland:sp": { 539 "lifetime": {"minutes": 5}, 540 "attribute_restrictions": { 541 "givenName": None, 542 "surName": None, 543 }, 544 }, 545 546 # a policy for a registration authority 547 "http://www.swamid.se/": { 548 "attribute_restrictions": { 549 "givenName": None, 550 }, 551 }, 552 553 # the policy for all other services 554 "default": { 555 "lifetime": {"minutes":15}, 556 "attribute_restrictions": None, # means all I have 557 "name_form": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri", 558 "entity_categories": [ 559 "edugain", 560 ], 561 }, 562 } 563 } 564 } 565 566*lifetime* 567 This is the maximum amount of time before the information should be 568 regarded as stale. In an Assertion, this is represented in the NotOnOrAfter 569 attribute. 570*attribute_restrictions* 571 By default, there are no restrictions as to which attributes should be 572 returned. Instead, all the attributes and values that are gathered by the 573 database backends will be returned if nothing else is stated. 574 In the example above the SP with the entity identifier 575 "urn:mace:umu.se:saml:roland:sp" 576 has an attribute restriction: only the attributes 577 'givenName' and 'surName' are to be returned. There are no limitations as to 578 what values on these attributes that can be returned. 579*name_form* 580 Which name-form that should be used when sending assertions. 581 Using this information, the attribute name in the data source will be mapped to 582 the friendly name, and the saml attribute name will be taken from the uri/oid 583 defined in the attribute map. 584*nameid_format* 585 Which nameid format that should be used. Defaults to 586 `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`. 587*entity_categories* 588 Entity categories to apply. 589*sign* 590 Possible choices: "response", "assertion", "on_demand" 591 592If restrictions on values are deemed necessary, those are represented by 593regular expressions.:: 594 595 "service": { 596 "aa": { 597 "policy": { 598 "urn:mace:umu.se:saml:roland:sp": { 599 "lifetime": {"minutes": 5}, 600 "attribute_restrictions": { 601 "mail": [".*\.umu\.se$"], 602 } 603 } 604 } 605 } 606 } 607 608Here only mail addresses that end with ".umu.se" will be returned. 609 610sp 611^^ 612 613Directives specific to SP instances 614 615authn_requests_signed 616""""""""""""""""""""" 617 618Indicates if the Authentication Requests sent by this SP should be signed 619by default. This can be overridden by application code for a specific call. 620 621This sets the AuthnRequestsSigned attribute of the SPSSODescriptor node 622of the metadata so the IdP will know this SP preference. 623 624Valid values are True or False. Default value is True. 625 626Example:: 627 628 "service": { 629 "sp": { 630 "authn_requests_signed": True, 631 } 632 } 633 634 635want_response_signed 636"""""""""""""""""""" 637 638Indicates that Authentication Responses to this SP must be signed. If set to 639True, the SP will not consume any SAML Responses that are not signed. 640 641Valid values are True or False. Default value is True. 642 643Example:: 644 645 "service": { 646 "sp": { 647 "want_response_signed": True, 648 } 649 } 650 651 652force_authn 653""""""""""" 654 655Mandates that the identity provider MUST authenticate the presenter directly 656rather than rely on a previous security context. 657 658Example:: 659 660 "service": { 661 "sp": { 662 "force_authn": True, 663 } 664 } 665 666 667name_id_policy_format 668""""""""""""""""""""" 669 670A string value that will be used to set the ``Format`` attribute of the 671``<NameIDPolicy>`` element of an ``<AuthnRequest>``. 672 673Example:: 674 675 "service": { 676 "sp": { 677 "name_id_policy_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", 678 } 679 } 680 681 682name_id_format_allow_create 683""""""""""""""""""""""""""" 684 685A boolean value (``True`` or ``False``) that will be used to set the ``AllowCreate`` 686attribute of the ``<NameIDPolicy>`` element of an ``<AuthnRequest>``. 687 688Example:: 689 690 "service": { 691 "sp": { 692 "name_id_format_allow_create": True, 693 } 694 } 695 696 697name_id_format 698"""""""""""""" 699 700A list of string values that will be used to set the ``<NameIDFormat>`` element of the 701metadata of an entity. 702 703Example:: 704 705 "service": { 706 "sp": { 707 "name_id_format": [ 708 "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", 709 "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", 710 ] 711 } 712 } 713 714 715allow_unsolicited 716""""""""""""""""" 717 718When set to true, the SP will consume unsolicited SAML Responses, i.e. SAML 719Responses for which it has not sent a respective SAML Authentication Request. 720 721Example:: 722 723 "service": { 724 "sp": { 725 "allow_unsolicited": True, 726 } 727 } 728 729hide_assertion_consumer_service 730""""""""""""""""""""""""""""""" 731 732When set to true the AuthnRequest will not include the 733AssertionConsumerServiceURL and ProtocolBinding attributes. 734 735Example:: 736 737 "service": { 738 "sp": { 739 "hide_assertion_consumer_service": True, 740 } 741 } 742 743This kind of functionality is required for the eIDAS SAML profile. 744 745> eIDAS-Connectors SHOULD NOT provide AssertionConsumerServiceURL. 746 747.. note:: 748 This is relevant only for the eIDAS SAML profile. 749 750 751sp_type 752""""""" 753 754Sets the value for the eIDAS SPType node. By the eIDAS specification the value 755can be one of *public* and *private*. 756 757Example:: 758 759 "service": { 760 "sp": { 761 "sp_type": "private", 762 } 763 } 764 765.. note:: 766 This is relevant only for the eIDAS SAML profile. 767 768 769sp_type_in_metadata 770""""""""""""""""""" 771 772Whether the SPType node should appear in the metadata document 773or as part of each AuthnRequest. 774 775Example:: 776 777 "service": { 778 "sp": { 779 "sp_type_in_metadata": True, 780 } 781 } 782 783.. note:: 784 This is relevant only for the eIDAS SAML profile. 785 786 787requested_attributes 788"""""""""""""""""""" 789 790A list of attributes that the SP requires from an eIDAS-Service (IdP). 791Each attribute is an object with the following attributes: 792 793* friendly_name 794* name 795* required 796* name_format 797 798Where friendly_name is an attribute name such as *DateOfBirth*, name is the 799full attribute name such as 800*http://eidas.europa.eu/attributes/naturalperson/DateOfBirth*, required 801indicates whether this attributed is required for authentication, and 802name_format indicates the name format for that attribute, such as 803*urn:oasis:names:tc:SAML:2.0:attrname-format:uri*. 804 805It is mandatory that at least name or friendly_name is set. 806By default attributes are assumed to be required. 807Missing attributes are inferred based on the attribute maps data. 808 809Example:: 810 811 "service": { 812 "sp": { 813 "requested_attributes": [ 814 { 815 "name": "http://eidas.europa.eu/attributes/naturalperson/PersonIdentifier", 816 }, 817 { 818 "friendly_name": "DateOfBirth", 819 "required": False, 820 }, 821 ], 822 } 823 } 824 825.. note:: 826 This is relevant only for the eIDAS SAML profile. 827 828 This option is different from the required_attributes and 829 optional_attributes parameters that control the requested 830 attributes in the metadata of an SP. 831 832 833idp 834""" 835 836Defines the set of IdPs that this SP is allowed to use; if unset, all listed 837IdPs may be used. If set, then the value is expected to be a list with entity 838identifiers for the allowed IdPs. 839A typical configuration, when the allowed set of IdPs are limited, would look 840something like this:: 841 842 "service": { 843 "sp": { 844 "idp": ["urn:mace:umu.se:saml:roland:idp"], 845 } 846 } 847 848In this case, the SP has only one IdP it can use. 849 850optional_attributes 851""""""""""""""""""" 852 853Attributes that this SP would like to receive from IdPs. 854 855Example:: 856 857 "service": { 858 "sp": { 859 "optional_attributes": ["title"], 860 } 861 } 862 863Since the attribute names used here are the user-friendly ones an attribute map 864must exist, so that the server can use the full name when communicating 865with other servers. 866 867required_attributes 868""""""""""""""""""" 869 870Attributes that this SP demands to receive from IdPs. 871 872Example:: 873 874 "service": { 875 "sp": { 876 "required_attributes": [ 877 "surname", 878 "givenName", 879 "mail", 880 ], 881 } 882 } 883 884Again as for *optional_attributes* the names given are expected to be 885the user-friendly names. 886 887want_assertions_signed 888"""""""""""""""""""""" 889 890Indicates if this SP wants the IdP to send the assertions signed. This 891sets the WantAssertionsSigned attribute of the SPSSODescriptor node 892of the metadata so the IdP will know this SP preference. 893 894Valid values are True or False. Default value is False. 895 896Example:: 897 898 "service": { 899 "sp": { 900 "want_assertions_signed": True, 901 } 902 } 903 904want_assertions_or_response_signed 905"""""""""""""""""""""""""""""""""" 906 907Indicates that *either* the Authentication Response *or* the assertions 908contained within the response to this SP must be signed. 909 910Valid values are True or False. Default value is False. 911 912This configuration directive **does not** override ``want_response_signed`` 913or ``want_assertions_signed``. For example, if ``want_response_signed`` is True 914and the Authentication Response is not signed an exception will be thrown 915regardless of the value for this configuration directive. 916 917Thus to configure the SP to accept either a signed response or signed assertions 918set ``want_response_signed`` and ``want_assertions_signed`` both to False and 919this directive to True. 920 921Example:: 922 923 "service": { 924 "sp": { 925 "want_response_signed": False, 926 "want_assertions_signed": False, 927 "want_assertions_or_response_signed": True, 928 } 929 } 930 931 932idp/aa/sp 933^^^^^^^^^ 934 935If the configuration is covering both two or three different service types 936(like if one server is actually acting as both an IdP and an SP) then in some 937cases you might want to have these below different for the different services. 938 939endpoints 940""""""""" 941 942Where the endpoints for the services provided are. 943This directive has as value a dictionary with one or more of the following keys: 944 945* artifact_resolution_service (aa, idp and sp) 946* `assertion_consumer_service <https://wiki.shibboleth.net/confluence/display/CONCEPT/AssertionConsumerService>`_ (sp) 947* assertion_id_request_service (aa, idp) 948* attribute_service (aa) 949* manage_name_id_service (aa, idp) 950* name_id_mapping_service (idp) 951* single_logout_service (aa, idp, sp) 952* single_sign_on_service (idp) 953 954The value per service is a list of endpoint specifications. 955An endpoint specification can either be just the URL:: 956 957 ”http://localhost:8088/A" 958 959or it can be a 2-tuple (URL+binding):: 960 961 from saml2 import BINDING_HTTP_POST 962 (”http://localhost:8087/A”, BINDING_HTTP_POST) 963 964or a 3-tuple (URL+binding+index):: 965 966 from saml2 import BINDING_HTTP_POST 967 (”http://lingon.catalogix.se:8087/A”, BINDING_HTTP_POST, 1) 968 969If no binding is specified, no index can be set. 970If no index is specified, the index is set based on the position in the list. 971 972Example:: 973 974 "service": 975 "idp": { 976 "endpoints": { 977 "single_sign_on_service": [ 978 ("http://localhost:8088/sso", BINDING_HTTP_REDIRECT), 979 ], 980 "single_logout_service": [ 981 ("http://localhost:8088/slo", BINDING_HTTP_REDIRECT), 982 ], 983 }, 984 }, 985 }, 986 987only_use_keys_in_metadata 988""""""""""""""""""""""""" 989 990If set to False, the certificate contained in a SAML message will be used for 991signature verification. 992Default True. 993 994validate_certificate 995"""""""""""""""""""" 996 997Indicates that the certificate used in sign SAML messages must be valid. 998Default to False. 999 1000logout_requests_signed 1001"""""""""""""""""""""" 1002 1003Indicates if this entity will sign the Logout Requests originated from it. 1004 1005This can be overridden by application code for a specific call. 1006 1007Valid values are True or False. Default value is False. 1008 1009Example:: 1010 1011 "service": { 1012 "sp": { 1013 "logout_requests_signed": False, 1014 } 1015 } 1016 1017 1018signing_algorithm 1019""""""""""""""""" 1020 1021Default algorithm to be used. Example:: 1022 1023 "service": { 1024 "sp": { 1025 "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512", 1026 "digest_algorithm": "http://www.w3.org/2001/04/xmlenc#sha512", 1027 } 1028 } 1029 1030 1031digest_algorithm 1032""""""""""""""""" 1033 1034Default algorithm to be used. Example:: 1035 1036 "service": { 1037 "idp": { 1038 "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512", 1039 "digest_algorithm": "http://www.w3.org/2001/04/xmlenc#sha512", 1040 } 1041 } 1042 1043 1044logout_responses_signed 1045""""""""""""""""""""""" 1046 1047Indicates if this entity will sign the Logout Responses while processing 1048a Logout Request. 1049 1050This can be overridden by application code when calling ``handle_logout_request``. 1051 1052Valid values are True or False. Default value is False. 1053 1054Example:: 1055 1056 "service": { 1057 "sp": { 1058 "logout_responses_signed": False, 1059 } 1060 } 1061 1062 1063subject_data 1064"""""""""""" 1065 1066The name of a database where the map between a local identifier and 1067a distributed identifier is kept. By default, this is a shelve database. 1068So if you just specify a name, then a shelve database with that name 1069is created. On the other hand, if you specify a tuple, then the first 1070element in the tuple specifies which type of database you want to use 1071and the second element is the address of the database. 1072 1073Example:: 1074 1075 "subject_data": "./idp.subject.db", 1076 1077or if you want to use for instance memcache:: 1078 1079 "subject_data": ("memcached", "localhost:12121"), 1080 1081*shelve* and *memcached* are the only database types that are currently 1082supported. 1083 1084 1085virtual_organization 1086"""""""""""""""""""" 1087 1088Gives information about common identifiers for virtual_organizations:: 1089 1090 "virtual_organization": { 1091 "urn:mace:example.com:it:tek": { 1092 "nameid_format": "urn:oid:1.3.6.1.4.1.1466.115.121.1.15-NameID", 1093 "common_identifier": "umuselin", 1094 } 1095 }, 1096 1097Keys in this dictionary are the identifiers for the virtual organizations. 1098The arguments per organization are 'nameid_format' and 'common_identifier'. 1099Useful if all the IdPs and AAs that are involved in a virtual organization 1100have common attribute values for users that are part of the VO. 1101 1102Complete example 1103---------------- 1104 1105We start with a simple but fairly complete Service provider configuration:: 1106 1107 from saml2 import BINDING_HTTP_REDIRECT 1108 1109 CONFIG = { 1110 "entityid": "http://example.com/sp/metadata.xml", 1111 "service": { 1112 "sp": { 1113 "name": "Example SP", 1114 "endpoints": { 1115 "assertion_consumer_service": ["http://example.com/sp"], 1116 "single_logout_service": [ 1117 ("http://example.com/sp/slo", BINDING_HTTP_REDIRECT), 1118 ], 1119 }, 1120 } 1121 }, 1122 "key_file": "./mykey.pem", 1123 "cert_file": "./mycert.pem", 1124 "xmlsec_binary": "/usr/local/bin/xmlsec1", 1125 "delete_tmpfiles": True, 1126 "attribute_map_dir": "./attributemaps", 1127 "metadata": { 1128 "local": ["idp.xml"] 1129 } 1130 "organization": { 1131 "display_name": ["Example identities"] 1132 } 1133 "contact_person": [ 1134 { 1135 "givenname": "Roland", 1136 "surname": "Hedberg", 1137 "phone": "+46 90510", 1138 "mail": "roland@example.com", 1139 "type": "technical", 1140 }, 1141 ] 1142 } 1143 1144This is the typical setup for an SP. 1145A metadata file to load is *always* needed, but it can, of course, 1146contain anything from 1 up to many entity descriptions. 1147 1148------ 1149 1150A slightly more complex configuration:: 1151 1152 from saml2 import BINDING_HTTP_REDIRECT 1153 1154 CONFIG = { 1155 "entityid": "http://sp.example.com/metadata.xml", 1156 "service": { 1157 "sp": { 1158 "name": "Example SP", 1159 "endpoints": { 1160 "assertion_consumer_service": ["http://sp.example.com/"], 1161 "single_logout_service": [ 1162 ("http://sp.example.com/slo", BINDING_HTTP_REDIRECT), 1163 ], 1164 }, 1165 "subject_data": ("memcached", "localhost:12121"), 1166 "virtual_organization": { 1167 "urn:mace:example.com:it:tek": { 1168 "nameid_format": "urn:oid:1.3.6.1.4.1.1466.115.121.1.15-NameID", 1169 "common_identifier": "eduPersonPrincipalName", 1170 } 1171 }, 1172 } 1173 }, 1174 "key_file": "./mykey.pem", 1175 "cert_file": "./mycert.pem", 1176 "xmlsec_binary": "/usr/local/bin/xmlsec1", 1177 "delete_tmpfiles": True, 1178 "metadata": { 1179 "local": ["example.xml"], 1180 "remote": [ 1181 { 1182 "url":"https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2", 1183 "cert":"kalmar2.pem", 1184 } 1185 ] 1186 }, 1187 "attribute_maps": "attributemaps", 1188 "organization": { 1189 "display_name": ["Example identities"] 1190 } 1191 "contact_person": [ 1192 { 1193 "givenname": "Roland", 1194 "surname": "Hedberg", 1195 "phone": "+46 90510", 1196 "mail": "roland@example.com", 1197 "type": "technical", 1198 }, 1199 ] 1200 } 1201 1202Uses metadata files, both local and remote, and will talk to whatever 1203IdP that appears in any of the metadata files. 1204 1205Other considerations 1206:::::::::::::::::::: 1207 1208Entity Categories 1209----------------- 1210 1211Entity categories and their attributes are defined in 1212src/saml2/entity_category/<registrar-of-entity-category>.py. 1213We can configure Entity Categories in pysaml2 in two ways: 1214 12151. Using the configuration options *entity_category_support* or 1216 *entity_category*, to generate the appropriate EntityAttribute metadata 1217 elements. 12182. Using the configuration option *entity_categories* as part of the policy 1219 configuration, to make the entity category work as a filter on the 1220 attributes that will be released. 1221 1222If the entity categories are configured as metadata, as follow:: 1223 1224 'debug' : True, 1225 'xmlsec_binary': get_xmlsec_binary([/usr/bin/xmlsec1']), 1226 'entityid': '%s/metadata' % BASE_URL, 1227 1228 # or entity_category: [ ... ] 1229 'entity_category_support': [ 1230 edugain.COCO, # "http://www.geant.net/uri/dataprotection-code-of-conduct/v1" 1231 refeds.RESEARCH_AND_SCHOLARSHIP, 1232 ], 1233 1234 'attribute_map_dir': 'data/attribute-maps', 1235 'description': 'SAML2 IDP', 1236 1237 'service': { 1238 'idp': { 1239 ... 1240 1241In the metadata we'll then have:: 1242 1243 <md:Extensions> 1244 <mdattr:EntityAttributes> 1245 <saml:Attribute Name="http://macedir.org/entity-category-support" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> 1246 <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> 1247 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://refeds.org/category/research-and-scholarship</saml:AttributeValue> 1248 </saml:Attribute> 1249 </mdattr:EntityAttributes> 1250 1251If the entity categories are configurated in the policy section, they will act 1252as filters on the released attributes. 1253 1254Example:: 1255 1256 "policy": { 1257 "default": { 1258 "lifetime": {"minutes": 15}, 1259 # if the SP is not conform to entity_categories 1260 # the attributes will not be released 1261 "entity_categories": ["refeds",], 1262