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 example 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_certification": [ 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 250name 251^^^^ 252 253A string value that sets the name of the PySAML2 entity. 254 255Example:: 256 257 "name": "Example IdP" 258 259description 260^^^^^^^^^^^ 261 262A string value that sets the description of the PySAML2 entity. 263 264Example:: 265 266 "description": "My IdP", 267 268verify_ssl_cert 269^^^^^^^^^^^^^^^ 270 271Specifies if the SSL certificates should be verified. Can be ``True`` or ``False``. 272The default configuration is ``False``. 273 274Example:: 275 276 "verify_ssl_cert": True 277 278key_file 279^^^^^^^^ 280 281Example:: 282 283 key_file: "key.pem" 284 285*key_file* is the name of a PEM formatted file that contains the private key 286of the service. This is currently used both to encrypt/sign assertions and as 287the client key in an HTTPS session. 288 289cert_file 290^^^^^^^^^ 291 292Example:: 293 294 cert_file: "cert.pem" 295 296This is the public part of the service private/public key pair. 297*cert_file* must be a PEM formatted file with a single certificate. 298 299tmp_cert_file 300^^^^^^^^^^^^^ 301 302Example:: 303 "tmp_cert_file": "tmp_cert.pem" 304 305*tmp_cert_file* is a PEM formatted certificate file 306 307tmp_key_file 308^^^^^^^^^^^^ 309 310Example:: 311 "tmp_key_file": "tmp_key.pem" 312 313*tmp_key_file* is a PEM formatted key file. 314 315encryption_keypairs 316^^^^^^^^^^^^^^^^^^^ 317 318Indicates which certificates will be used for encryption capabilities:: 319 320 # Encryption 321 'encryption_keypairs': [ 322 { 323 'key_file': BASE_DIR + '/certificates/private.key', 324 'cert_file': BASE_DIR + '/certificates/public.cert', 325 }, 326 ], 327 328generate_cert_info 329^^^^^^^^^^^^^^^^^^ 330 331Specifies if information about the certificate should be generated. 332A boolean value can be ``True`` or ``False``. 333 334Example:: 335 336 "generate_cert_info": False 337 338 339ca_certs 340^^^^^^^^ 341 342This is the path to a file containing root CA certificates for SSL server certificate validation. 343 344Example:: 345 346 "ca_certs": full_path("cacerts.txt"), 347 348 349metadata 350^^^^^^^^ 351 352Contains a list of places where metadata can be found. This can be 353 354* a local directory accessible on the server the service runs on 355* a local file accessible on the server the service runs on 356* a remote URL serving aggregate metadata 357* a metadata query protocol (MDQ) service URL 358 359For example:: 360 361 "metadata": { 362 "local": [ 363 "/opt/metadata" 364 "metadata.xml", 365 "vo_metadata.xml", 366 ], 367 "remote": [ 368 { 369 "url": "https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2", 370 "cert": "kalmar2.cert", 371 }, 372 ], 373 "mdq": [ 374 { 375 "url": "http://mdq.ukfederation.org.uk/", 376 "cert": "ukfederation-mdq.pem", 377 "freshness_period": "P0Y0M0DT2H0M0S", 378 }, 379 { 380 "url": "https://mdq.thaturl.org/", 381 "disable_ssl_certificate_validation": True, 382 "check_validity": False, 383 }, 384 ], 385 }, 386 387The above configuration means that the service should read two aggregate local 388metadata files, one aggregate metadata file from a remote server, and query a 389remote MDQ server. To verify the authenticity of the metadata aggregate 390downloaded from the remote server and the MDQ server local copies of the 391metadata signing certificates should be used. These public keys must be 392acquired by some secure out-of-band method before being placed on the local 393file system. 394 395When the parameter *check_validity* is set to False metadata that have expired 396will be accepted as valid. 397 398When the paramenter *disable_ssl_certificate_validation* is set to True the 399validity of ssl certificate will be skipped. 400 401When using MDQ, the `freshness_period` option can be set to define a period for 402which the metadata fetched from the the MDQ server are considered fresh. After 403that period has passed the metadata are not valid anymore and must be fetched 404again. The period must be in the format defined in 405`ISO 8601 <https://www.iso.org/iso-8601-date-and-time-format.html>`_ 406or `RFC3999 <https://tools.ietf.org/html/rfc3339#appendix-A>`_. 407 408By default, if `freshness_period` is not defined, the metadata are refreshed 409every 12 hours (`P0Y0M0DT12H0M0S`). 410 411 412organization 413^^^^^^^^^^^^ 414 415Only used by *make_metadata.py*. 416Where you describe the organization responsible for the service.:: 417 418 "organization": { 419 "name": [ 420 ("Example Company", "en"), 421 ("Exempel AB", "se") 422 ], 423 "display_name": ["Exempel AB"], 424 "url": [ 425 ("http://example.com", "en"), 426 ("http://exempel.se", "se"), 427 ], 428 } 429 430.. note:: You can specify the language of the name, or the language used on 431 the webpage, by entering a tuple, instead of a simple string, 432 where the second part is the language code. If you don't specify a 433 language, the default is "en" (English). 434 435preferred_binding 436^^^^^^^^^^^^^^^^^ 437 438Which binding should be preferred for a service. 439Example configuration:: 440 441 "preferred_binding" = { 442 "single_sign_on_service": [ 443 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 444 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 445 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact', 446 ], 447 "single_logout_service": [ 448 'urn:oasis:names:tc:SAML:2.0:bindings:SOAP', 449 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 450 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST', 451 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact', 452 ], 453 } 454 455The available services are: 456 457* manage_name_id_service 458* assertion_consumer_service 459* name_id_mapping_service 460* authn_query_service 461* attribute_service 462* authz_service 463* assertion_id_request_service 464* artifact_resolution_service 465* attribute_consuming_service 466* single_logout_service 467 468 469service 470^^^^^^^ 471 472Which services the server will provide; those are combinations of "idp", "sp" 473and "aa". 474So if a server is a Service Provider (SP) then the configuration 475could look something like this:: 476 477 "service": { 478 "sp": { 479 "name": "Rolands SP", 480 "endpoints": { 481 "assertion_consumer_service": ["http://localhost:8087/"], 482 "single_logout_service": [ 483 ( 484 "http://localhost:8087/slo", 485 'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect', 486 ), 487 ], 488 }, 489 "required_attributes": [ 490 "surname", 491 "givenname", 492 "edupersonaffiliation", 493 ], 494 "optional_attributes": ["title"], 495 "idp": { 496 "urn:mace:umu.se:saml:roland:idp": None, 497 }, 498 } 499 }, 500 501There are two options common to all services: 'name' and 'endpoints'. 502The remaining options are specific to one or the other of the service types. 503Which one is specified alongside the name of the option. 504 505accepted_time_diff 506^^^^^^^^^^^^^^^^^^ 507 508If your computer and another computer that you are communicating with are not 509in sync regarding the computer clock, then here you can state how big a 510difference you are prepared to accept. 511 512.. note:: This will indiscriminately affect all time comparisons. 513 Hence your server may accept a statement that in fact is too old. 514 515allow_unknown_attributes 516^^^^^^^^^^^^^^^^^^^^^^^^ 517 518Indicates that attributes that are not recognized (they are not configured in 519attribute-mapping), will not be discarded. 520Default to False. 521 522xmlsec_binary 523^^^^^^^^^^^^^ 524 525Currently xmlsec1 binaries are used for all the signing and encryption stuff. 526This option defines where the binary is situated. 527 528Example:: 529 530 "xmlsec_binary": "/usr/local/bin/xmlsec1", 531 532xmlsec_path 533^^^^^^^^^^^ 534 535This option is used to define non-system paths where the xmlsec1 binary can be located. 536It can be used when the xmlsec_binary option is not defined. 537 538Example:: 539 540 "xmlsec_path": ["/usr/local/bin", "/opt/local/bin"], 541 542OR:: 543 544 from saml2.sigver import get_xmlsec_binary 545 546 if get_xmlsec_binary: 547 xmlsec_path = get_xmlsec_binary(["/opt/local/bin","/usr/local/bin"]) 548 else: 549 xmlsec_path = '/usr/bin/xmlsec1' 550 551 "xmlsec_binary": xmlsec_path, 552 553 554delete_tmpfiles 555^^^^^^^^^^^^^^^ 556 557In many cases temporary files will have to be created during the 558encryption/decryption/signing/validation process. 559This option defines whether these temporary files will be automatically deleted when 560they are no longer needed. Setting this to False, will keep these files until they are 561manually deleted or automatically deleted by the OS (i.e Linux rules for /tmp). 562Absence of this option, defaults to True. 563 564 565valid_for 566^^^^^^^^^ 567 568How many *hours* this configuration is expected to be accurate.:: 569 570 "valid_for": 24 571 572This, of course, is only used by *make_metadata.py*. 573The server will not stop working when this amount of time has elapsed :-). 574 575 576metadata_key_usage 577^^^^^^^^^^^^^^^^^^^ 578 579This specifies the purpose of the entity's cryptographic keys used to sign data. 580If this option is not configured it will default to ``"both"``. 581 582The possible options for this configuration are ``both``, ``signing``, ``encryption``. 583 584If metadata_key_usage is set to ``"signing"`` or ``"both"``, and a cert_file is provided 585the value of use in the KeyDescriptor element will be set to ``"signing"``. 586 587If metadata_key_usage is set to ``"both"`` or ``"encryption"`` and a enc_cert is provided 588the value of ``"use"`` in the KeyDescriptor will be set to ``"encryption"``. 589 590Example:: 591 592 "metadata_key_usage" : "both", 593 594 595secret 596^^^^^^ 597 598A string value that is used in the generation of the RelayState. 599 600Example:: 601 602 "secret": "0123456789", 603 604crypto_backend 605^^^^^^^^^^^^^^ 606Defines the crypto backend used for signing and encryption. The default is ``xmlsec1``. 607The options are ``xmlsec1`` and ``XMLSecurity``. 608 609If set to "XMLSecurity", the crypto backend will be pyXMLSecurity. 610 611Example:: 612 613 "crypto_backend": "xmlsec1", 614 615verify_encrypt_advice 616^^^^^^^^^^^^^^^^^^^^^ 617 618Specifies if the encrypted assertions in the advice element should be verified. 619Can be ``True`` or ``False``. 620 621Example:: 622 623 def verify_encrypt_cert(cert_str): 624 osw = OpenSSLWrapper() 625 ca_cert_str = osw.read_str_from_file(full_path("root_cert/localhost.ca.crt")) 626 valid, mess = osw.verify(ca_cert_str, cert_str) 627 return valid 628 629:: 630 631 "verify_encrypt_cert_advice": verify_encrypt_cert, 632 633 634verify_encrypt_cert_assertion 635^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 636 637Specifies if the encrypted assertions should be verified. 638Can be ``True`` or ``False``. 639 640Example:: 641 642 "verify_encrypt_cert_assertion": verify_encrypt_cert 643 644 645Specific directives 646------------------- 647 648Directives that are specific to a certain type of service. 649 650idp/aa 651^^^^^^ 652 653Directives that are specific to an IdP or AA service instance. 654 655sign_assertion 656"""""""""""""" 657 658Specifies if the IdP should sign the assertion in an authentication response 659or not. Can be True or False. Default is False. 660 661sign_response 662""""""""""""" 663 664Specifies if the IdP should sign the authentication response or not. Can be 665True or False. Default is False. 666 667encrypt_assertion 668""""""""""""""""" 669 670Specifies if the IdP should encrypt the assertions. Can be ``True`` or ``False``. 671Default is ``False``. 672 673encrypted_advice_attributes 674""""""""""""""""""""""""""" 675Specifies if assertions in the advice element should be encrypted. 676Can be ``True`` or ``False``. Default is ``False``. 677 678encrypt_assertion_self_contained 679"""""""""""""""""""""""""""""""" 680 681Specifies if all encrypted assertions should have all namespaces self contained. 682Can be ``True`` or ``False``. Default is ``True``. 683 684want_authn_requests_signed 685"""""""""""""""""""""""""" 686 687Indicates that the AuthnRequest received by this IdP should be signed. Can be ``True`` or ``False``. 688The default value is ``False``. 689 690want_authn_requests_only_with_valid_cert 691"""""""""""""""""""""""""""""""""""""""" 692 693When verifying a signed AuthnRequest ignore the signature and verify the 694certificate. 695 696policy 697"""""" 698 699If the server is an IdP and/or an AA, then there might be reasons to do things 700differently depending on who is asking (which is the requesting service); the 701policy is where this behaviour is specified. 702 703The keys are SP entity identifiers, Registration Authority names, or 'default'. 704First, the policy for the requesting service is looked up using the SP entityID. 705If no such policy is found, and if the SP metadata includes a Registration 706Authority then a policy for the registration authority is looked up using the 707Registration Authority name. If no policy is found, then the 'default' is looked 708up. If there is no default and only SP entity identifiers as keys, then the 709server will only accept connections from the specified SPs. 710 711An example might be:: 712 713 "service": { 714 "idp": { 715 "policy": { 716 # a policy for a service 717 "urn:mace:example.com:saml:roland:sp": { 718 "lifetime": {"minutes": 5}, 719 "attribute_restrictions": { 720 "givenName": None, 721 "surName": None, 722 }, 723 }, 724 725 # a policy for a registration authority 726 "http://www.swamid.se/": { 727 "attribute_restrictions": { 728 "givenName": None, 729 }, 730 }, 731 732 # the policy for all other services 733 "default": { 734 "lifetime": {"minutes":15}, 735 "attribute_restrictions": None, # means all I have 736 "name_form": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri", 737 "entity_categories": [ 738 "edugain", 739 ], 740 }, 741 } 742 } 743 } 744 745*lifetime* 746 This is the maximum amount of time before the information should be 747 regarded as stale. In an Assertion, this is represented in the NotOnOrAfter 748 attribute. 749*attribute_restrictions* 750 By default, there are no restrictions as to which attributes should be 751 returned. Instead, all the attributes and values that are gathered by the 752 database backends will be returned if nothing else is stated. 753 In the example above the SP with the entity identifier 754 "urn:mace:umu.se:saml:roland:sp" 755 has an attribute restriction: only the attributes 756 'givenName' and 'surName' are to be returned. There are no limitations as to 757 what values on these attributes that can be returned. 758*name_form* 759 Which name-form that should be used when sending assertions. 760 Using this information, the attribute name in the data source will be mapped to 761 the friendly name, and the saml attribute name will be taken from the uri/oid 762 defined in the attribute map. 763*nameid_format* 764 Which nameid format that should be used. Defaults to 765 `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`. 766*entity_categories* 767 Entity categories to apply. 768*sign* 769 Possible choices: "response", "assertion", "on_demand" 770 771If restrictions on values are deemed necessary, those are represented by 772regular expressions.:: 773 774 "service": { 775 "aa": { 776 "policy": { 777 "urn:mace:umu.se:saml:roland:sp": { 778 "lifetime": {"minutes": 5}, 779 "attribute_restrictions": { 780 "mail": [".*\.umu\.se$"], 781 } 782 } 783 } 784 } 785 } 786 787Here only mail addresses that end with ".umu.se" will be returned. 788 789scope 790""""" 791 792A list of string values that will be used to set the ``<Scope>`` element 793The default value of regexp is ``False``. 794 795Example:: 796 797 "scope": ["example.org", "example.com"], 798 799 800ui_info 801"""""""" 802 803This determines what information to display about an entity by 804configuring its mdui:UIInfo element. The configurable options include; 805 806*privacy_statement_url* 807 The URL to information about the privacy practices of the entity. 808*information_url* 809 Which URL contains localized information about the entity. 810*logo* 811 The logo image for the entity. The value is a dictionary with keys 812 height, width and text. 813*display_name* 814 The localized name for the entity. 815*description* 816 The localized description of the entity. The value is a dictionary with keys 817 text and lang. 818*keywords* 819 The localized search keywords for the entity. The value is a dictionary with keys 820 lang and text. 821 822Example:: 823 824 "ui_info": { 825 "privacy_statement_url": "http://example.com/saml2/privacyStatement.html", 826 "information_url": "http://example.com/saml2/info.html", 827 "logo": { 828 "height": "40", 829 "width" : "30", 830 "text": "http://example.com/logo.jpg" 831 }, 832 "display_name": "Example Co.", 833 "description" : {"text":"Exempel Bolag","lang":"se"}, 834 "keywords": {"lang":"en", "text":["foo", "bar"]} 835 } 836 837 838name_qualifier 839"""""""""""""" 840 841A string value that sets the ``NameQualifier`` attribute of the ``<NameIdentifier>`` element. 842 843Example:: 844 845 "name_qualifier": "http://authentic.example.com/saml/metadata", 846 847 848session_storage 849""""""""""""""" 850 851Example:: 852 853 "session_storage": ("mongodb", "session") 854 855domain 856"""""" 857 858Example:: 859 860 "domain": "umu.se", 861 862sp 863^^ 864 865Directives specific to SP instances 866 867authn_requests_signed 868""""""""""""""""""""" 869 870Indicates if the Authentication Requests sent by this SP should be signed 871by default. This can be overridden by application code for a specific call. 872 873This sets the AuthnRequestsSigned attribute of the SPSSODescriptor node 874of the metadata so the IdP will know this SP preference. 875 876Valid values are True or False. Default value is True. 877 878Example:: 879 880 "service": { 881 "sp": { 882 "authn_requests_signed": True, 883 } 884 } 885 886 887want_response_signed 888"""""""""""""""""""" 889 890Indicates that Authentication Responses to this SP must be signed. If set to 891True, the SP will not consume any SAML Responses that are not signed. 892 893Valid values are True or False. Default value is True. 894 895Example:: 896 897 "service": { 898 "sp": { 899 "want_response_signed": True, 900 } 901 } 902 903 904force_authn 905""""""""""" 906 907Mandates that the identity provider MUST authenticate the presenter directly 908rather than rely on a previous security context. 909 910Example:: 911 912 "service": { 913 "sp": { 914 "force_authn": True, 915 } 916 } 917 918 919name_id_policy_format 920""""""""""""""""""""" 921 922A string value that will be used to set the ``Format`` attribute of the 923``<NameIDPolicy>`` element of an ``<AuthnRequest>``. 924 925Example:: 926 927 "service": { 928 "sp": { 929 "name_id_policy_format": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", 930 } 931 } 932 933 934name_id_format_allow_create 935""""""""""""""""""""""""""" 936 937A boolean value (``True`` or ``False``) that will be used to set the ``AllowCreate`` 938attribute of the ``<NameIDPolicy>`` element of an ``<AuthnRequest>``. 939 940Example:: 941 942 "service": { 943 "sp": { 944 "name_id_format_allow_create": True, 945 } 946 } 947 948 949name_id_format 950"""""""""""""" 951 952A list of string values that will be used to set the ``<NameIDFormat>`` element of the 953metadata of an entity. 954 955Example:: 956 957 "service": { 958 "sp": { 959 "name_id_format": [ 960 "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent", 961 "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", 962 ] 963 } 964 } 965 966 967allow_unsolicited 968""""""""""""""""" 969 970When set to true, the SP will consume unsolicited SAML Responses, i.e. SAML 971Responses for which it has not sent a respective SAML Authentication Request. 972 973Example:: 974 975 "service": { 976 "sp": { 977 "allow_unsolicited": True, 978 } 979 } 980 981hide_assertion_consumer_service 982""""""""""""""""""""""""""""""" 983 984When set to true the AuthnRequest will not include the 985AssertionConsumerServiceURL and ProtocolBinding attributes. 986 987Example:: 988 989 "service": { 990 "sp": { 991 "hide_assertion_consumer_service": True, 992 } 993 } 994 995This kind of functionality is required for the eIDAS SAML profile. 996 997> eIDAS-Connectors SHOULD NOT provide AssertionConsumerServiceURL. 998 999.. note:: 1000 This is relevant only for the eIDAS SAML profile. 1001 1002 1003sp_type 1004""""""" 1005 1006Sets the value for the eIDAS SPType node. By the eIDAS specification the value 1007can be one of *public* and *private*. 1008 1009Example:: 1010 1011 "service": { 1012 "sp": { 1013 "sp_type": "private", 1014 } 1015 } 1016 1017.. note:: 1018 This is relevant only for the eIDAS SAML profile. 1019 1020 1021sp_type_in_metadata 1022""""""""""""""""""" 1023 1024Whether the SPType node should appear in the metadata document 1025or as part of each AuthnRequest. 1026 1027Example:: 1028 1029 "service": { 1030 "sp": { 1031 "sp_type_in_metadata": True, 1032 } 1033 } 1034 1035.. note:: 1036 This is relevant only for the eIDAS SAML profile. 1037 1038 1039requested_attributes 1040"""""""""""""""""""" 1041 1042A list of attributes that the SP requires from an eIDAS-Service (IdP). 1043Each attribute is an object with the following attributes: 1044 1045* friendly_name 1046* name 1047* required 1048* name_format 1049 1050Where friendly_name is an attribute name such as *DateOfBirth*, name is the 1051full attribute name such as 1052*http://eidas.europa.eu/attributes/naturalperson/DateOfBirth*, required 1053indicates whether this attributed is required for authentication, and 1054name_format indicates the name format for that attribute, such as 1055*urn:oasis:names:tc:SAML:2.0:attrname-format:uri*. 1056 1057It is mandatory that at least name or friendly_name is set. 1058By default attributes are assumed to be required. 1059Missing attributes are inferred based on the attribute maps data. 1060 1061Example:: 1062 1063 "service": { 1064 "sp": { 1065 "requested_attributes": [ 1066 { 1067 "name": "http://eidas.europa.eu/attributes/naturalperson/PersonIdentifier", 1068 }, 1069 { 1070 "friendly_name": "DateOfBirth", 1071 "required": False, 1072 }, 1073 ], 1074 } 1075 } 1076 1077.. note:: 1078 This is relevant only for the eIDAS SAML profile. 1079 1080 This option is different from the required_attributes and 1081 optional_attributes parameters that control the requested 1082 attributes in the metadata of an SP. 1083 1084 1085idp 1086""" 1087 1088Defines the set of IdPs that this SP is allowed to use; if unset, all listed 1089IdPs may be used. If set, then the value is expected to be a list with entity 1090identifiers for the allowed IdPs. 1091A typical configuration, when the allowed set of IdPs are limited, would look 1092something like this:: 1093 1094 "service": { 1095 "sp": { 1096 "idp": ["urn:mace:umu.se:saml:roland:idp"], 1097 } 1098 } 1099 1100In this case, the SP has only one IdP it can use. 1101 1102optional_attributes 1103""""""""""""""""""" 1104 1105Attributes that this SP would like to receive from IdPs. 1106 1107Example:: 1108 1109 "service": { 1110 "sp": { 1111 "optional_attributes": ["title"], 1112 } 1113 } 1114 1115Since the attribute names used here are the user-friendly ones an attribute map 1116must exist, so that the server can use the full name when communicating 1117with other servers. 1118 1119required_attributes 1120""""""""""""""""""" 1121 1122Attributes that this SP demands to receive from IdPs. 1123 1124Example:: 1125 1126 "service": { 1127 "sp": { 1128 "required_attributes": [ 1129 "surname", 1130 "givenName", 1131 "mail", 1132 ], 1133 } 1134 } 1135 1136Again as for *optional_attributes* the names given are expected to be 1137the user-friendly names. 1138 1139want_assertions_signed 1140"""""""""""""""""""""" 1141 1142Indicates if this SP wants the IdP to send the assertions signed. This 1143sets the WantAssertionsSigned attribute of the SPSSODescriptor node 1144of the metadata so the IdP will know this SP preference. 1145 1146Valid values are True or False. Default value is False. 1147 1148Example:: 1149 1150 "service": { 1151 "sp": { 1152 "want_assertions_signed": True, 1153 } 1154 } 1155 1156want_assertions_or_response_signed 1157"""""""""""""""""""""""""""""""""" 1158 1159Indicates that *either* the Authentication Response *or* the assertions 1160contained within the response to this SP must be signed. 1161 1162Valid values are True or False. Default value is False. 1163 1164This configuration directive **does not** override ``want_response_signed`` 1165or ``want_assertions_signed``. For example, if ``want_response_signed`` is True 1166and the Authentication Response is not signed an exception will be thrown 1167regardless of the value for this configuration directive. 1168 1169Thus to configure the SP to accept either a signed response or signed assertions 1170set ``want_response_signed`` and ``want_assertions_signed`` both to False and 1171this directive to True. 1172 1173Example:: 1174 1175 "service": { 1176 "sp": { 1177 "want_response_signed": False, 1178 "want_assertions_signed": False, 1179 "want_assertions_or_response_signed": True, 1180 } 1181 } 1182 1183discovery_response 1184"""""""""""""""""" 1185 1186This configuration allows the SP to include one or more Discovery Response Endpoints. 1187The discovery_response can be the just the URL:: 1188 1189 "discovery_response":["http://example.com/sp/ds"], 1190 1191or it can be a 2 tuple of the URL+Binding:: 1192 1193 from saml2.extension.idpdisc import BINDING_DISCO 1194 1195 "discovery_response": [("http://example.com/sp/ds", BINDING_DISCO)] 1196 1197ecp 1198""" 1199 1200This configuration option takes a dictionary with the ecp client IP address as the 1201key and the entity ID as the value. 1202 1203Example:: 1204 1205 "ecp": { 1206 "203.0.113.254": "http://example.com/idp", 1207 } 1208 1209requested_attribute_name_format 1210""""""""""""""""""""""""""""""" 1211 1212This sets the NameFormat attribute in the ``<RequestedAttribute>`` element. 1213The name formats are defined in saml2.saml.py. If not configured the default is ``NAME_FORMAT_URI`` 1214which corresponds to ``urn:oasis:names:tc:SAML:2.0:attrname-format:uri``. 1215 1216Example:: 1217 1218 from saml2.saml import NAME_FORMAT_BASIC 1219 1220:: 1221 1222 "requested_attribute_name_format": NAME_FORMAT_BASIC 1223 1224 1225requested_authn_context 1226""""""""""""""""""""""" 1227 1228This configuration option defines the ``<RequestedAuthnContext>`` for an AuthnRequest by 1229a client. The value is a dictionary with two fields 1230 1231- ``authn_context_class_ref`` a list of string values representing 1232 ``<AuthnContextClassRef>`` elements. 1233 1234- ``comparison`` a string representing the Comparison xml-attribute value of the 1235 ``<RequestedAuthnContext>`` element. Per the SAML core specificiation the value should 1236 be one of "exact", "minimum", "maximum", or "better". The default is "exact". 1237 1238Example:: 1239 1240 "service": { 1241 "sp": { 1242 "requested_authn_context": { 1243 "authn_context_class_ref": [ 1244 "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport", 1245 "urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient", 1246 ], 1247 "comparison": "minimum", 1248 } 1249 } 1250 } 1251 1252 1253idp/aa/sp 1254^^^^^^^^^ 1255 1256If the configuration is covering both two or three different service types 1257(like if one server is actually acting as both an IdP and an SP) then in some 1258cases you might want to have these below different for the different services. 1259 1260endpoints 1261""""""""" 1262 1263Where the endpoints for the services provided are. 1264This directive has as value a dictionary with one or more of the following keys: 1265 1266* artifact_resolution_service (aa, idp and sp) 1267* `assertion_consumer_service <https://wiki.shibboleth.net/confluence/display/CONCEPT/AssertionConsumerService>`_ (sp) 1268* assertion_id_request_service (aa, idp) 1269* attribute_service (aa) 1270* manage_name_id_service (aa, idp) 1271* name_id_mapping_service (idp) 1272* single_logout_service (aa, idp, sp) 1273* single_sign_on_service (idp) 1274 1275The value per service is a list of endpoint specifications. 1276An endpoint specification can either be just the URL:: 1277 1278 ”http://localhost:8088/A" 1279 1280or it can be a 2-tuple (URL+binding):: 1281 1282 from saml2 import BINDING_HTTP_POST 1283 (”http://localhost:8087/A”, BINDING_HTTP_POST) 1284 1285or a 3-tuple (URL+binding+index):: 1286 1287 from saml2 import BINDING_HTTP_POST 1288 (”http://lingon.catalogix.se:8087/A”, BINDING_HTTP_POST, 1) 1289 1290If no binding is specified, no index can be set. 1291If no index is specified, the index is set based on the position in the list. 1292 1293Example:: 1294 1295 "service": 1296 "idp": { 1297 "endpoints": { 1298 "single_sign_on_service": [ 1299 ("http://localhost:8088/sso", BINDING_HTTP_REDIRECT), 1300 ], 1301 "single_logout_service": [ 1302 ("http://localhost:8088/slo", BINDING_HTTP_REDIRECT), 1303 ], 1304 }, 1305 }, 1306 }, 1307 1308only_use_keys_in_metadata 1309""""""""""""""""""""""""" 1310 1311If set to False, the certificate contained in a SAML message will be used for 1312signature verification. 1313Default True. 1314 1315validate_certificate 1316"""""""""""""""""""" 1317 1318Indicates that the certificate used in sign SAML messages must be valid. 1319Default to False. 1320 1321logout_requests_signed 1322"""""""""""""""""""""" 1323 1324Indicates if this entity will sign the Logout Requests originated from it. 1325 1326This can be overridden by application code for a specific call. 1327 1328Valid values are True or False. Default value is False. 1329 1330Example:: 1331 1332 "service": { 1333 "sp": { 1334 "logout_requests_signed": False, 1335 } 1336 } 1337 1338 1339signing_algorithm 1340""""""""""""""""" 1341 1342Default algorithm to be used. Example:: 1343 1344 "service": { 1345 "sp": { 1346 "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512", 1347 "digest_algorithm": "http://www.w3.org/2001/04/xmlenc#sha512", 1348 } 1349 } 1350 1351 1352digest_algorithm 1353""""""""""""""""" 1354 1355Default algorithm to be used. Example:: 1356 1357 "service": { 1358 "idp": { 1359 "signing_algorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512", 1360 "digest_algorithm": "http://www.w3.org/2001/04/xmlenc#sha512", 1361 } 1362 } 1363 1364 1365logout_responses_signed 1366""""""""""""""""""""""" 1367 1368Indicates if this entity will sign the Logout Responses while processing 1369a Logout Request. 1370 1371This can be overridden by application code when calling ``handle_logout_request``. 1372 1373Valid values are True or False. Default value is False. 1374 1375Example:: 1376 1377 "service": { 1378 "sp": { 1379 "logout_responses_signed": False, 1380 } 1381 } 1382 1383 1384subject_data 1385"""""""""""" 1386 1387The name of a database where the map between a local identifier and 1388a distributed identifier is kept. By default, this is a shelve database. 1389So if you just specify a name, then a shelve database with that name 1390is created. On the other hand, if you specify a tuple, then the first 1391element in the tuple specifies which type of database you want to use 1392and the second element is the address of the database. 1393 1394Example:: 1395 1396 "subject_data": "./idp.subject.db", 1397 1398or if you want to use for instance memcache:: 1399 1400 "subject_data": ("memcached", "localhost:12121"), 1401 1402*shelve* and *memcached* are the only database types that are currently 1403supported. 1404 1405 1406virtual_organization 1407"""""""""""""""""""" 1408 1409Gives information about common identifiers for virtual_organizations:: 1410 1411 "virtual_organization": { 1412 "urn:mace:example.com:it:tek": { 1413 "nameid_format": "urn:oid:1.3.6.1.4.1.1466.115.121.1.15-NameID", 1414 "common_identifier": "umuselin", 1415 } 1416 }, 1417 1418Keys in this dictionary are the identifiers for the virtual organizations. 1419The arguments per organization are 'nameid_format' and 'common_identifier'. 1420Useful if all the IdPs and AAs that are involved in a virtual organization 1421have common attribute values for users that are part of the VO. 1422 1423Complete example 1424---------------- 1425 1426We start with a simple but fairly complete Service provider configuration:: 1427 1428 from saml2 import BINDING_HTTP_REDIRECT 1429 1430 CONFIG = { 1431 "entityid": "http://example.com/sp/metadata.xml", 1432 "service": { 1433 "sp": { 1434 "name": "Example SP", 1435 "endpoints": { 1436 "assertion_consumer_service": ["http://example.com/sp"], 1437 "single_logout_service": [ 1438 ("http://example.com/sp/slo", BINDING_HTTP_REDIRECT), 1439 ], 1440 }, 1441 } 1442 }, 1443 "key_file": "./mykey.pem", 1444 "cert_file": "./mycert.pem", 1445 "xmlsec_binary": "/usr/local/bin/xmlsec1", 1446 "delete_tmpfiles": True, 1447 "attribute_map_dir": "./attributemaps", 1448 "metadata": { 1449 "local": ["idp.xml"] 1450 } 1451 "organization": { 1452 "display_name": ["Example identities"] 1453 } 1454 "contact_person": [ 1455 { 1456 "givenname": "Roland", 1457 "surname": "Hedberg", 1458 "phone": "+46 90510", 1459 "mail": "roland@example.com", 1460 "type": "technical", 1461 }, 1462 ] 1463 } 1464 1465This is the typical setup for an SP. 1466A metadata file to load is *always* needed, but it can, of course, 1467contain anything from 1 up to many entity descriptions. 1468 1469------ 1470 1471A slightly more complex configuration:: 1472 1473 from saml2 import BINDING_HTTP_REDIRECT 1474 1475 CONFIG = { 1476 "entityid": "http://sp.example.com/metadata.xml", 1477 "service": { 1478 "sp": { 1479 "name": "Example SP", 1480 "endpoints": { 1481 "assertion_consumer_service": ["http://sp.example.com/"], 1482 "single_logout_service": [ 1483 ("http://sp.example.com/slo", BINDING_HTTP_REDIRECT), 1484 ], 1485 }, 1486 "subject_data": ("memcached", "localhost:12121"), 1487 "virtual_organization": { 1488 "urn:mace:example.com:it:tek": { 1489 "nameid_format": "urn:oid:1.3.6.1.4.1.1466.115.121.1.15-NameID", 1490 "common_identifier": "eduPersonPrincipalName", 1491 } 1492 }, 1493 } 1494 }, 1495 "key_file": "./mykey.pem", 1496 "cert_file": "./mycert.pem", 1497 "xmlsec_binary": "/usr/local/bin/xmlsec1", 1498 "delete_tmpfiles": True, 1499 "metadata": { 1500 "local": ["example.xml"], 1501 "remote": [ 1502 { 1503 "url":"https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2", 1504 "cert":"kalmar2.pem", 1505 } 1506 ] 1507 }, 1508 "attribute_maps": "attributemaps", 1509 "organization": { 1510 "display_name": ["Example identities"] 1511 } 1512 "contact_person": [ 1513 { 1514 "givenname": "Roland", 1515 "surname": "Hedberg", 1516 "phone": "+46 90510", 1517 "mail": "roland@example.com", 1518 "type": "technical", 1519 }, 1520 ] 1521 } 1522 1523Uses metadata files, both local and remote, and will talk to whatever 1524IdP that appears in any of the metadata files. 1525 1526Other considerations 1527:::::::::::::::::::: 1528 1529Entity Categories 1530----------------- 1531 1532Entity categories and their attributes are defined in 1533src/saml2/entity_category/<registrar-of-entity-category>.py. 1534We can configure Entity Categories in PySAML2 in two ways: 1535 15361. Using the configuration options *entity_category_support* or 1537 *entity_category*, to generate the appropriate EntityAttribute metadata 1538 elements. 15392. Using the configuration option *entity_categories* as part of the policy 1540 configuration, to make the entity category work as a filter on the 1541 attributes that will be released. 1542 1543If the entity categories are configured as metadata, as follow:: 1544 1545 'debug' : True, 1546 'xmlsec_binary': get_xmlsec_binary([/usr/bin/xmlsec1']), 1547 'entityid': '%s/metadata' % BASE_URL, 1548 1549 # or entity_category: [ ... ] 1550 'entity_category_support': [ 1551 edugain.COCO, # "http://www.geant.net/uri/dataprotection-code-of-conduct/v1" 1552 refeds.RESEARCH_AND_SCHOLARSHIP, 1553 ], 1554 1555 'attribute_map_dir': 'data/attribute-maps', 1556 'description': 'SAML2 IDP', 1557 1558 'service': { 1559 'idp': { 1560 ... 1561 1562In the metadata we'll then have:: 1563 1564 <md:Extensions> 1565 <mdattr:EntityAttributes> 1566 <saml:Attribute Name="http://macedir.org/entity-category-support" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"> 1567 <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> 1568 <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://refeds.org/category/research-and-scholarship</saml:AttributeValue> 1569 </saml:Attribute> 1570 </mdattr:EntityAttributes> 1571 1572If the entity categories are configurated in the policy section, they will act 1573as filters on the released attributes. 1574 1575Example:: 1576 1577 "policy": { 1578 "default": { 1579 "lifetime": {"minutes": 15}, 1580 # if the SP is not conform to entity_categories 1581 # the attributes will not be released 1582 "entity_categories": ["refeds",], 1583