510 lines
16 KiB
ReStructuredText
510 lines
16 KiB
ReStructuredText
.. _howto_config:
|
|
|
|
Configuration of pySAML2 entities
|
|
=================================
|
|
|
|
Whether you plan to run a pySAML2 Service Provider, Identity provider or an
|
|
attribute authority you have to configure it. The format of the configuration
|
|
file is the same disregarding which type of service you plan to run.
|
|
What differs is some of the directives.
|
|
Below you will find a list of all the used directives in alphabetic order.
|
|
The configuration is written as a python dictionary which means that the
|
|
directives are the top level keys.
|
|
|
|
.. note:: You can build the entities metadata file directly from the configuration.
|
|
The make_metadata.py script in the pySAML2 tools directory will do that
|
|
for you.
|
|
|
|
|
|
Configuration directives
|
|
------------------------
|
|
|
|
attribute_map_dir
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
Format::
|
|
|
|
attribute_map_dir: "attribute-maps"
|
|
|
|
Points to a directory which has subdirectories, one per name-format you
|
|
expect to support. So a typical tree would be.::
|
|
|
|
attribute-maps
|
|
|
|
|
+-- urn:oases:names:tc:SAML:2.0:name-format:basic
|
|
| |
|
|
| +-- fro
|
|
| +-- to
|
|
|
|
|
+-- urn:oases:names:tc:SAML:2.0:name-format:uri
|
|
|
|
|
+-- fro
|
|
+-- to
|
|
|
|
The *to* and *fro* files then contain the mapping between the names.
|
|
The start of the urn:oases:names:tc:SAML:2.0:name-format:uri/fro file
|
|
for instance looks like this::
|
|
|
|
{
|
|
'urn:oid:1.3.6.1.4.1.5923.1.1.1.2': 'eduPersonNickname',
|
|
'urn:oid:1.3.6.1.4.1.5923.1.1.1.9': 'eduPersonScopedAffiliation',
|
|
'urn:oid:1.3.6.1.4.1.5923.1.1.1.11': 'eduPersonAssurance',
|
|
'urn:oid:1.3.6.1.4.1.5923.1.1.1.10': 'eduPersonTargetedID',
|
|
'urn:oid:1.3.6.1.4.1.5923.1.1.1.4': 'eduPersonOrgUnitDN',
|
|
'urn:oid:1.3.6.1.4.1.5923.1.1.1.1': 'eduPersonAffiliation',
|
|
|
|
As you see the format is again a python dictionary where the key is the
|
|
name to convert from and the value is the name to convert to.
|
|
|
|
Since *to* in most cases are the inverse of the *fro* file, the
|
|
software allowes you to only specify one of them and it will
|
|
automatically create the other.
|
|
|
|
cert_file
|
|
^^^^^^^^^
|
|
|
|
Format::
|
|
|
|
cert_file: "cert.pem"
|
|
|
|
This is the public part of the service private/public key pair.
|
|
*cert_file* must be a PEM formatted certificate chain file.
|
|
|
|
contact_person
|
|
^^^^^^^^^^^^^^
|
|
|
|
This is only used by *make_metadata.py* when it constructs the metadata for
|
|
the service described by the configuration file.
|
|
This is where you described who can be contacted if questions arises
|
|
about the service or if support is needed. The possible types are according to
|
|
the standard **technical**, **support**, **administrative**, **billing**
|
|
and **other**.::
|
|
|
|
contact_person: [{
|
|
"givenname": "Derek",
|
|
"surname": "Jeter",
|
|
"company": "Example Co.",
|
|
"mail": ["jeter@example.com"],
|
|
"type": "technical",
|
|
},{
|
|
"givenname": "Joe",
|
|
"surname": "Girardi",
|
|
"company": "Example Co.",
|
|
"mail": "girardi@example.com",
|
|
"type": "administrative",
|
|
}]
|
|
|
|
debug
|
|
^^^^^
|
|
|
|
Format::
|
|
|
|
debug: 1
|
|
|
|
Whether debug information should be sent to the log file.
|
|
|
|
entityid
|
|
^^^^^^^^
|
|
|
|
Format::
|
|
|
|
entityid: "http://saml.example.com/sp"
|
|
|
|
The globally unique identifier of the entity.
|
|
|
|
.. note:: There is a recommendation that the entityid should point to a real
|
|
webpage where the metadata for the entity can be found.
|
|
|
|
key_file
|
|
^^^^^^^^
|
|
|
|
Format::
|
|
|
|
key_file: "key.pem"
|
|
|
|
*key_file* is the name of a PEM formatted file that contains the private key
|
|
of the service. This is presently used both to encrypt/sign assertions and as
|
|
client key in a HTTPS session.
|
|
|
|
metadata
|
|
^^^^^^^^
|
|
|
|
Contains a list of places where metadata can be found. This can be either
|
|
a file accessible on the server the service runs on or somewhere on the net.::
|
|
|
|
"metadata" : {
|
|
"local": [
|
|
"metadata.xml", "vo_metadata.xml"
|
|
],
|
|
"remote": [
|
|
{
|
|
"url":"https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2",
|
|
"cert":"kalmar2.cert"
|
|
}],
|
|
},
|
|
|
|
The above configuration means that the service should read two local
|
|
metadata files and on top of that load one from the net. To verify the
|
|
authenticity of the file downloaded from the net the local copy of the
|
|
public key should be used.
|
|
This public key must be acquired by some out-of-band method.
|
|
|
|
organization
|
|
^^^^^^^^^^^^
|
|
|
|
Only used by *make_metadata.py*.
|
|
Where you describe the organization responsible for the service.::
|
|
|
|
"organization": {
|
|
"name": [("Example Company","en"), ("Exempel AB","se")],
|
|
"display_name": ["Exempel AB"],
|
|
"url": [("http://example.com","en"),("http://exempel.se","se")],
|
|
}
|
|
|
|
.. note:: You can specify the language of the name, or the language used on
|
|
the webpage, by entering a tuple, instead of a simple string,
|
|
where the second part is the language code. If you don't specify a
|
|
language the default is "en" (English).
|
|
|
|
service
|
|
^^^^^^^
|
|
|
|
Which services the server will provide, those are combinations of "idp","sp"
|
|
and "aa".
|
|
So if a server is a Service Provider (SP) then the configuration
|
|
could look something like this::
|
|
|
|
"service": {
|
|
"sp":{
|
|
"name" : "Rolands SP",
|
|
"endpoints":{
|
|
"assertion_consumer_service": ["http://localhost:8087/"],
|
|
"single_logout_service" : [("http://localhost:8087/slo",
|
|
'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect')],
|
|
},
|
|
"required_attributes": ["surname", "givenname", "edupersonaffiliation"],
|
|
"optional_attributes": ["title"],
|
|
"idp": {
|
|
"urn:mace:umu.se:saml:roland:idp": None,
|
|
},
|
|
}
|
|
},
|
|
|
|
There are two options common to all services: 'name' and 'endpoints'.
|
|
The remaining options are specific to one or the other of the service types.
|
|
Which one is specified along side the name of the option
|
|
|
|
-------
|
|
|
|
*policy* (idp/aa)
|
|
"""""""""""""""""
|
|
|
|
If the server is an IdP and/or an AA then there might be reasons to do things
|
|
differently depending on who is asking; this is where that is specified.
|
|
The keys are 'default' and SP entity identifiers, default is used whenever
|
|
there is no entry for a specific SP. The reasoning is also that if there is
|
|
no default and only SP entity identifiers as keys, then the server will only
|
|
except connections from the specified SPs.
|
|
An example might be::
|
|
|
|
"service": {
|
|
"idp": {
|
|
"policy": {
|
|
"default": {
|
|
"lifetime": {"minutes":15},
|
|
"attribute_restrictions": None, # means all I have
|
|
"name_form": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
|
|
},
|
|
"urn:mace:example.com:saml:roland:sp": {
|
|
"lifetime": {"minutes": 5},
|
|
"attribute_restrictions":{
|
|
"givenName": None,
|
|
"surName": None,
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
*lifetime*
|
|
is the maximum amount of time before the information should be
|
|
regarded as stale. In an Assertion this is represented in the NotOnOrAfter
|
|
attribute.
|
|
*attribute_restrictions*
|
|
By default there is no restrictions as to which attributes should be
|
|
return. Instead all the attributes and values that is gathered by the
|
|
database backends will be returned if nothing else is stated.
|
|
In the example above the SP with the entity identifier
|
|
"urn:mace:umu.se:saml:roland:sp"
|
|
has an attribute restriction: only the attributes
|
|
'givenName' and 'surName' are to be returned. There is no limitations as to
|
|
what values on these attributes that can be returned.
|
|
*name_form*
|
|
Which name-form that should be used when sending assertions.
|
|
|
|
If restrictions on values are deemed necessary those are represented by
|
|
regular expressions.::
|
|
|
|
"service": {
|
|
"aa": {
|
|
"policy": {
|
|
"urn:mace:umu.se:saml:roland:sp": {
|
|
"lifetime": {"minutes": 5},
|
|
"attribute_restrictions":{
|
|
"mail": [".*\.umu\.se$"],
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
Here only mail addresses that ends with ".umu.se" will be returned.
|
|
|
|
*idp* (sp)
|
|
""""""""""
|
|
|
|
Defines the set of IdPs that this SP is allowed to use. If there is metadata
|
|
loaded, and not all the IdPs in the metadata is allowed, then the value is
|
|
expected to be a dictionary with entity identifiers as
|
|
keys. The IdP url which normally is the value can be omitted.
|
|
If the url is not defined then an
|
|
attempt is made to pick it out of the metadata.
|
|
A typical configuration, when metadata is present and the allowed set of
|
|
IdPs are limited, would look something like this::
|
|
|
|
"service": {
|
|
"sp": {
|
|
"idp": {
|
|
"urn:mace:umu.se:saml:roland:idp": None,
|
|
},
|
|
}
|
|
}
|
|
|
|
In this case the SP has only one IdP it can use, a typical situation when
|
|
you are using SAML for services within one organization. At configuration
|
|
time the url of the IdP might not be know so the evaluation of it is left
|
|
until a metadata file is present. If more than one IdP can be used then
|
|
the WAYF function would use the metadata file to
|
|
find out the names, to be presented to the user, for the different IdPs.
|
|
On the other hand if the SP only uses one specific IdP then the usage of
|
|
metadata might be overkill so this construct can be used instead::
|
|
|
|
"service": {
|
|
"sp": {
|
|
"idp": {
|
|
"" :{"single_signon_service":
|
|
["https://example.com/idp/SSOService.php"],
|
|
"single_logout_service":
|
|
[("https://example.com/idp/SLS",
|
|
'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect')],
|
|
},
|
|
},
|
|
}
|
|
}
|
|
|
|
Apart from *single_signon_service* and *single_logout_service*, the following
|
|
service type specifications can be used
|
|
|
|
* artifact_resolution_service
|
|
* manage_name_id_service
|
|
* name_id_mapping_service
|
|
* assertion_id_request_service
|
|
|
|
Since the user is immediately sent to the IdP the entity identifier of the IdP
|
|
is immaterial. If not the key is expected to be the user friendly
|
|
name of the IdP. Which again if no WAYF is used is immaterial, since the
|
|
user will never see the name.
|
|
|
|
There is a third choice and that is to leave the configuration blank, in
|
|
which case all the IdP present in the metadata
|
|
will be regarded as eligible services to use. ::
|
|
|
|
"service": {
|
|
"sp": {
|
|
"idp": {},
|
|
}
|
|
}
|
|
|
|
*optional_attributes* (sp)
|
|
""""""""""""""""""""""""""
|
|
|
|
Attributes that this SP would like to receive from IdPs.
|
|
|
|
Example::
|
|
|
|
"service": {
|
|
"sp": {
|
|
"optional_attributes": ["title"],
|
|
}
|
|
}
|
|
|
|
Since the attribute names used here are the user friendly ones an attribute map
|
|
must exist, so that the server can use the full name when communicating
|
|
with other servers.
|
|
|
|
*required_attributes* (sp)
|
|
""""""""""""""""""""""""""
|
|
|
|
Attributes that this SP demands to receive from IdPs.
|
|
|
|
Example::
|
|
|
|
"service": {
|
|
"sp": {
|
|
"required_attributes": ["surname", "givenName", "mail"],
|
|
}
|
|
}
|
|
|
|
Again as for *optional_attributes* the names given are expected to be
|
|
the user friendly names.
|
|
|
|
--------
|
|
|
|
subject_data
|
|
^^^^^^^^^^^^
|
|
|
|
The name of a database where the map between a local identifier and
|
|
a distributed identifier is kept. By default this is a shelve database.
|
|
So if you just specify name, then a shelve database with that name
|
|
is created. On the other hand if you specify a tuple then the first
|
|
element in the tuple specifise which type of database you want to use
|
|
and the second element is the address of the database.
|
|
|
|
Example::
|
|
|
|
"subject_data": "./idp.subject.db",
|
|
|
|
or if you want to use for instance memcache::
|
|
|
|
"subject_data": ("memcached", "localhost:12121"),
|
|
|
|
*shelve* and *memcached* are the only database types that are presently
|
|
supported.
|
|
|
|
timeslack
|
|
^^^^^^^^^
|
|
|
|
If your computer and another computer that you are communicating with are not
|
|
in synch regarding the computer clock. Then you here can state how big a
|
|
difference you are prepared to accept.
|
|
|
|
.. note:: This will indiscriminately effect all time comparisons.
|
|
Hence your server my accept a statement that in fact is to old.
|
|
|
|
xmlsec_binary
|
|
^^^^^^^^^^^^^
|
|
|
|
Presently xmlsec1 binaries are used for all the signing and encryption stuff.
|
|
This option defines where the binary is situated.
|
|
|
|
Example::
|
|
|
|
"xmlsec_binary": "/usr/local/bin/xmlsec1",
|
|
|
|
valid_for
|
|
^^^^^^^^^
|
|
|
|
How many *hours* this configuration is expected to be accurate.::
|
|
|
|
"valid_for": 24
|
|
|
|
This of course is only used by *make_metadata.py*.
|
|
The server will not stop working when this amount of time has elapsed :-).
|
|
|
|
virtual_organization
|
|
^^^^^^^^^^^^^^^^^^^^
|
|
|
|
Gives information about common identifiers for virtual_organizations::
|
|
|
|
"virtual_organization" : {
|
|
"urn:mace:example.com:it:tek":{
|
|
"nameid_format" : "urn:oid:1.3.6.1.4.1.1466.115.121.1.15-NameID",
|
|
"common_identifier": "umuselin",
|
|
}
|
|
},
|
|
|
|
Keys in this dictionary are the identifiers for the virtual organizations.
|
|
The arguments per organization is 'nameid_format' and 'common_identifier'.
|
|
Useful if all the IdPs and AAs that are involved in a virtual organization
|
|
have common attribute values for users that are part of the VO.
|
|
|
|
Complete example
|
|
----------------
|
|
|
|
We start with a simple but fairly complete Service provider configuration::
|
|
|
|
{
|
|
"entityid" : "urn:mace:example.com:saml:roland:sp",
|
|
"service": {
|
|
"sp":{
|
|
"name" : "Rolands SP",
|
|
"endpoints":{
|
|
"assertion_consumer_service": ["http://localhost:8087/"],
|
|
"single_logout_service" : [("http://localhost:8087/slo",
|
|
'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect')],
|
|
},
|
|
"idp": {
|
|
"urn:mace:example.com:saml:roland:idp": {
|
|
"single_signon_service": "http://idp.example.com/sso"},
|
|
},
|
|
}
|
|
},
|
|
"key_file" : "./mykey.pem",
|
|
"cert_file" : "./mycert.pem",
|
|
"xmlsec_binary" : "/usr/local/bin/xmlsec1",
|
|
"attribute_map_dir": "./attributemaps",
|
|
"organization": {
|
|
"display_name":["Rolands identities"]
|
|
}
|
|
"contact_person": [{
|
|
"givenname": "Roland",
|
|
"surname": "Hedberg",
|
|
"phone": "+46 90510",
|
|
"mail": "roland@example.com",
|
|
"type": "technical",
|
|
}]
|
|
}
|
|
|
|
This is the typical setup for a SP used within an organization.
|
|
If static configuration is OK, no metadata file is needed, instead all the
|
|
necessary information on how to find the IdP is given in the configuration.
|
|
|
|
A slightly more complex configuration::
|
|
|
|
{
|
|
"entityid" : "urn:mace:umu.se:saml:roland:sp",
|
|
"service": {
|
|
"sp":{
|
|
"name" : "Rolands SP",
|
|
"endpoints":{
|
|
"assertion_consumer_service": ["http://localhost:8087/"],
|
|
"single_logout_service" : [("http://localhost:8087/slo",
|
|
'urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect')],
|
|
},
|
|
}
|
|
},
|
|
"key_file" : "./mykey.pem",
|
|
"cert_file" : "./mycert.pem",
|
|
"xmlsec_binary" : "/usr/local/bin/xmlsec1",
|
|
"metadata" : {
|
|
"local": ["idp/idp.xml"],
|
|
"remote": [{
|
|
"url":"https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2",
|
|
"cert":"kalmar2.pem"}]
|
|
},
|
|
"attribute_maps" : "attributemaps",
|
|
"organization": {
|
|
"display_name":["Rolands identities"]
|
|
}
|
|
"contact_person": [{
|
|
"givenname": "Roland",
|
|
"surname": "Hedberg",
|
|
"phone": "+46 90510",
|
|
"mail": "roland@example.com",
|
|
"type": "technical",
|
|
}]
|
|
}
|
|
|
|
Uses metadata files, both local and remote, and will talk to whatever
|
|
IdP that appears in any of the metadata files.
|