openstack/deb-python-pysaml2
Code Issues Proposed changes

Updated documentation

Browse Source
This commit is contained in:
Roland Hedberg
2010-04-09 14:42:55 +02:00
parent 0579ac6bea
commit 2619c947ea
3 changed files with 205 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

286
doc/howto/config.rst
View File

@@ -12,34 +12,53 @@ The configuration is written as a python dictionary which means that the
directives are the top level keys. directives are the top level keys.
.. note:: You can build metadata files directly from the configuration. .. note:: You can build metadata files directly from the configuration.
The make_metadata.py script in the pySAML2 tools directory will do it The make_metadata.py script in the pySAML2 tools directory will do that
for you. for you.
Configuration directives Configuration directives
------------------------ ------------------------
attribute_maps attribute_map_dir
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
Format:: Format::
attribute_maps: ["attribute.map"] attribute_map_dir: "attribute-maps"
Points to simple files that, most commonly, contains the unique Points to a directory which has subdirectories, one per name-format you
name of attributes, their friendly names and their type separated by a blank, expect to support. So a typical tree would be.::
one attribute per line::
urn:oid:2.5.4.4 surName urn:oasis:names:tc:SAML:2.0:attrname-format:uri attribute-maps
urn:oid:2.5.4.42 givenName urn:oasis:names:tc:SAML:2.0:attrname-format:uri |
urn:oid:2.5.4.12 title urn:oasis:names:tc:SAML:2.0:attrname-format:uri +-- urn:oases:names:tc:SAML:2.0:name-format:basic
urn:oid:0.9.2342.19200300.100.1.1 uid urn:oasis:names:tc:SAML:2.0:attrname-format:uri | |
urn:oid:0.9.2342.19200300.100.1.3 mail urn:oasis:names:tc:SAML:2.0:attrname-format:uri | +-- fro
urn:oid:1.3.6.1.4.1.5923.1.1.1.1 eduPersonAffiliation urn:oasis:names:tc:SAML:2.0:attrname-format:uri | +-- to
urn:oid:1.3.6.1.4.1.5923.1.1.1.7 eduPersonEntitlement urn:oasis:names:tc:SAML:2.0:attrname-format:uri |
+-- 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::
To be used by a SP or an IdP when translating back and forth between {
user friendly names and universally unique names. '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 *to*/*fro* and it will
automatically create the other.
cert_file cert_file
^^^^^^^^^ ^^^^^^^^^
@@ -48,30 +67,30 @@ Format::
cert_file: ["cert.pem"] cert_file: ["cert.pem"]
A file that contains CA certificates that the service will use in This is the public part of the service private/public key pair.
HTTPS sessions to verify the server certificate.
*cert_file* must be a PEM formatted certificate chain file. *cert_file* must be a PEM formatted certificate chain file.
contact_person contact_person
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
This is only used by make_metadata.py when it constructs the metadata for This is only used by *make_metadata.py* when it constructs the metadata for
the service descibed by the configuration file. the service described by the configuration file.
This is where you descibed the persons can be contacted if questions arises This is where you described who can be contacted if questions arises
about the service or if support is needed:: about the service or if support is needed. The possible types are according to
the standard technical, support, administrative, billing, and other.::
contact_person: [{ contact_person: [{
"givenname": "Derek", "givenname": "Derek",
"surname": "Jeter", "surname": "Jeter",
"company": "Example Co.", "company": "Example Co.",
"mail": "jeter@example.com", "mail": "jeter@example.com",
"type": "Technical", "type": "technical",
},{ },{
"givenname": "Joe", "givenname": "Joe",
"surname": "Girardi", "surname": "Girardi",
"company": "Example Co.", "company": "Example Co.",
"mail": "girardi@example.com", "mail": "girardi@example.com",
"type": "Management", "type": "administrative",
}] }]
debug debug
@@ -100,7 +119,7 @@ Format::
key_file: ["key.pem"] key_file: ["key.pem"]
*key_file* is the name of a PEM formatted file that contains the private key *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 assertions and as of the service. This is presently used both to encrypt/sign assertions and as
client key in a HTTPS session. client key in a HTTPS session.
metadata metadata
@@ -115,15 +134,16 @@ a file accessible on the server the service runs on or somewhere on the net.::
], ],
"remote": [ "remote": [
{ {
"url":"https://kalmar2.org/aggregator/?id=kalmarcentral&set=saml2", "url":"https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2",
"cert":"kalmar.cert" "cert":"kalmar2.cert"
}], }],
}, },
When the metadata is to be picked from the net. there is the possibility to The above configuration means that the service should read two local
specify a certificate that is to be used to verify that the metadata is as metadata files and on top of that load one from the net. To verify the
produced by the other party. This certificate must be acquired by some authenticity of the file downloaded from the net the local copy of the
out-of-band method. public key should be used.
This public key must be acquired by some out-of-band method.
organization organization
^^^^^^^^^^^^ ^^^^^^^^^^^^
@@ -138,7 +158,7 @@ Where you describe the organization responsible for the service.::
} }
.. note:: You can specify the language of the name, or the language used on .. note:: You can specify the language of the name, or the language used on
the wewbpage, by entering a tuple, instead of a simple string, the webpage, by entering a tuple, instead of a simple string,
where the second part is the language code. where the second part is the language code.
service service
@@ -147,8 +167,8 @@ service
Which services the server will provide, those are combinations of "idp","sp" Which services the server will provide, those are combinations of "idp","sp"
and "aa". and "aa".
So if one server is supposed to be both Service Provider (SP) and So if one server is supposed to be both Service Provider (SP) and
Attribute Authority (AA) then the configuration could look something like Attribute Authority (AA), which is rather unlikely, then the configuration
this:: could look something like this::
"service": { "service": {
"aa":{ "aa":{
@@ -163,12 +183,13 @@ this::
There are two options common to all services: 'name' and 'url'. With the There are two options common to all services: 'name' and 'url'. With the
obvious meanings. obvious meanings.
There also exists special option for SPs namely: 'idp', 'optional_attributes' The remaining options are specific to one or the other of the service types.
and 'required_attributes'. Which one is specified along side the name of the option
Both IdPs and AAs can have the option 'assertions'
assertions (idp/aa) -------
"""""""""""""""""""
*policy* (idp/aa)
"""""""""""""""""
If the server is an IdP and/or an AA then there might be reasons to do things 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. differently depending on who is asking; this is where that is specified.
@@ -178,60 +199,78 @@ no default and only SP entity identifiers as keys, then the server will only
except connections from the specified SPs. except connections from the specified SPs.
An example might be:: An example might be::
"assertions": { "service": {
"default": { "idp": {
"lifetime": {"minutes":15}, "policy": {
"attribute_restrictions": None # means all I have "default": {
}, "lifetime": {"minutes":15},
"urn:mace:umu.se:saml:roland:sp": { "attribute_restrictions": None, # means all I have
"lifetime": {"minutes": 5}, "name_form": "urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
"attribute_restrictions":{ },
"givenName": None, "urn:mace:example.com:saml:roland:sp": {
"surName": None, "lifetime": {"minutes": 5},
"attribute_restrictions":{
"givenName": None,
"surName": None,
}
}
} }
} }
} }
*lifetime* is the maximum amount of time before the information should be *lifetime*
regarded as stale. In an Assertion this is represented in the NotOnOrAfter is the maximum amount of time before the information should be
attribute. regarded as stale. In an Assertion this is represented in the NotOnOrAfter
By default there is no restrictions as to which attributes should be attribute.
return. Instead all the attributes and values that is gathered by the *attribute_restrictions*
database backends will be returned if nothing else is stated. By default there is no restrictions as to which attributes should be
In the example above the SP with the entity identifier return. Instead all the attributes and values that is gathered by the
"urn:mace:umu.se:saml:roland:sp" database backends will be returned if nothing else is stated.
has an attribute restriction: only the attributes In the example above the SP with the entity identifier
'givenName' and 'surName' are to be returned. There is no limitations as to "urn:mace:umu.se:saml:roland:sp"
what values on these attributes that can be returned. 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 If restrictions on values are deemed necessary those are represented by
regular expressions.:: regular expressions.::
"assertions": { "service": {
"urn:mace:umu.se:saml:roland:sp": { "aa": {
"lifetime": {"minutes": 5}, "policy": {
"attribute_restrictions":{ "urn:mace:umu.se:saml:roland:sp": {
"mail": [".*.umu.se$"], "lifetime": {"minutes": 5},
"attribute_restrictions":{
"mail": [".*.umu.se$"],
}
}
} }
} }
} }
Here only mail addresses that ends with ".umu.se" will be returned. Here only mail addresses that ends with ".umu.se" will be returned.
idp (sp) *idp* (sp)
"""""""" """"""""""
Defines the set of IdPs that this SP is allowed to use. If there is metadata 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 loaded, and not all the IdPs in the metadata is allowed, then the value is
expected to be a dictionary with entity identifiers as expected to be a dictionary with entity identifiers as
keys and possibly the IdP url as values. If the url is not defined then an 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. attempt is made to pick it out of the metadata.
A typical configuration, when metadata is present and the allowed set of A typical configuration, when metadata is present and the allowed set of
IdPs are limited, would look something like this:: IdPs are limited, would look something like this::
"idp": { "service": {
"urn:mace:umu.se:saml:roland:idp": None, "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 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 you are using SAML for services within one organization. At configuration
@@ -242,9 +281,13 @@ 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 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:: metadata might be overkill so this construct can be used instead::
"idp": { "service": {
"" : "https://example.com/saml2/idp/SSOService.php", "sp": {
}, "idp": {
"" : "https://example.com/saml2/idp/SSOService.php",
},
}
}
Since the user is immediately sent to the IdP the entity identifier of the IdP Since the user is immediately sent to the IdP the entity identifier of the IdP
is immaterial. In this case the key is expected to be the user friendly is immaterial. In this case the key is expected to be the user friendly
@@ -255,34 +298,47 @@ There is a third choice and that is to leave the configuration blank, in
which case all the IdP present in the metadata which case all the IdP present in the metadata
will be regarded as eligible services to use. :: will be regarded as eligible services to use. ::
"idp": { "service": {
}, "sp": {
"idp": {},
}
}
optional_attributes (sp) *optional_attributes* (sp)
"""""""""""""""""""""""" """"""""""""""""""""""""""
Attributes that this SP would like to receive from IdPs. Attributes that this SP would like to receive from IdPs.
Example:: Example::
"optional_attributes": ["title"], "service": {
"sp": {
"optional_attributes": ["title"],
}
}
Since the attribute values used here are user friendly an attribute map Since the attribute values used here are user friendly an attribute map
must exist, so that the server can use the full name when communicating must exist, so that the server can use the full name when communicating
with other servers. with other servers.
required_attributes (sp) *required_attributes* (sp)
"""""""""""""""""""""""" """"""""""""""""""""""""""
Attributes that this SP demands to receive from IdPs. Attributes that this SP demands to receive from IdPs.
Example:: Example::
"required_attributes": ["surName", "givenName", "mail"], "service": {
"sp": {
"required_attributes": ["surname", "givenName", "mail"],
}
}
Again as for *optional_attributes* the names given are expected to be Again as for *optional_attributes* the names given are expected to be
the user friendly names. the user friendly names.
--------
subject_data subject_data
^^^^^^^^^^^^ ^^^^^^^^^^^^
@@ -293,12 +349,26 @@ Example::
"subject_data": "./idp.subject.db", "subject_data": "./idp.subject.db",
timeslack
^^^^^^^^^
If your computer and another computer that are communicating 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 xmlsec_binary
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Presently xmlsec1 binaries are used for all the signing and encryption stuff. Presently xmlsec1 binaries are used for all the signing and encryption stuff.
This option defines where the binary is situated. This option defines where the binary is situated.
Example::
"xmlsec_binary": "/usr/local/bin/xmlsec1",
valid_for valid_for
^^^^^^^^^ ^^^^^^^^^
@@ -326,10 +396,10 @@ The arguments per organization is 'nameid_format' and 'common_identifier'.
Useful if all the IdPs and AAs that are involved in a virtual organization 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. have common attribute values for users that are part of the VO.
Example Complete example
------- ----------------
We start with a simple Service provider configuration:: We start with a simple but fairly complete Service provider configuration::
{ {
"entityid" : "urn:mace:example.com:saml:roland:sp", "entityid" : "urn:mace:example.com:saml:roland:sp",
@@ -337,20 +407,15 @@ We start with a simple Service provider configuration::
"sp":{ "sp":{
"name" : "Rolands SP", "name" : "Rolands SP",
"url" : "http://www.example.com:8087/", "url" : "http://www.example.com:8087/",
"required_attributes": ["surName", "givenName", "mail"],
"optional_attributes": ["title"],
"idp": { "idp": {
"urn:mace:example.com:saml:roland:idp": None, "urn:mace:example.com:saml:roland:idp": "http://idp.example.com",
}, },
} }
}, },
"key_file" : "./mykey.pem", "key_file" : "./mykey.pem",
"cert_file" : "./mycert.pem", "cert_file" : "./mycert.pem",
"xmlsec_binary" : "/usr/local/bin/xmlsec1", "xmlsec_binary" : "/usr/local/bin/xmlsec1",
"metadata" : { "attribute_map_dir": "./attributemaps",
"local": ["metadata.xml", "vo_metadata.xml"],
},
"attribute_maps": ["attribute.map"],
"organization": { "organization": {
"display_name":["Rolands identiteter"] "display_name":["Rolands identiteter"]
} }
@@ -362,3 +427,40 @@ We start with a simple Service provider configuration::
}] }]
} }
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",
"url" : "http://lingon.ladok.umu.se:8087/",
}
},
"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 identiteter"]
}
"contact_person": [{
"givenname": "Roland",
"surname": "Hedberg",
"phone": "+46 90510",
"mail": "roland@example.com",
}]
}
Uses metadata files, both local and remote, and will talk to whatever
IdP that appears in any of the metadata files.

10
doc/howto/sp.rst
View File

@@ -10,7 +10,7 @@ A SP handles authentication, by the use of an Identity Provider, and possibly
attribute aggregation. attribute aggregation.
Both of these functions can be seen as parts of the normal Repoze.who Both of these functions can be seen as parts of the normal Repoze.who
setup. Namely the Challenger, Identifier and MetadataProvider parts so that setup. Namely the Challenger, Identifier and MetadataProvider parts so that
is how it is thought to be implemented. is also how it is implemented.
Normal for Repoze.who Identifier and MetadataProvider plugins are that Normal for Repoze.who Identifier and MetadataProvider plugins are that
they place information they gather in environment variables. The convention is they place information they gather in environment variables. The convention is
@@ -19,7 +19,7 @@ to place identity information in the environment under the key
The information is structured as a dictionary with keys like *login*, and The information is structured as a dictionary with keys like *login*, and
*repoze.who.userid*. *repoze.who.userid*.
The SP follows this pattern and places the information gathered from This SP follows this pattern and places the information gathered from
the Identity Provider that handled the authentication and possible extra the Identity Provider that handled the authentication and possible extra
information received from attribute authorities in the above mentioned information received from attribute authorities in the above mentioned
dictionary under the key *user*. dictionary under the key *user*.
@@ -39,7 +39,7 @@ If a WAYF is going to be used, then the pattern is the following:
unauthenticated user + no IdP selected unauthenticated user + no IdP selected
In this case, if there is a WAYF page specified in the In this case, if there is a WAYF page specified in the
SP part of the repoze.who configuration file, SP part of the repoze.who configuration file,
the user is redirected to that page. If no page is known an exception the user is redirected to that page. If no WAYF page is known an exception
is raised. is raised.
unauthenticated user + selected IdP unauthenticated user + selected IdP
@@ -116,12 +116,12 @@ Other information
----------------- -----------------
The SP keeps tabs on all outstanding authentication requests it has. The SP keeps tabs on all outstanding authentication requests it has.
This is kept in the local variable *outstanding_authn*. This is kept in the local variable *outstanding_queries*.
Presently if an authentication reponse is received that does not match an Presently if an authentication reponse is received that does not match an
outstanding request the reponse is ignored. This is going to change in the outstanding request the reponse is ignored. This is going to change in the
future. future.
The format of *outstanding_auth* is a dictionary with the session IDs as The format of *outstanding_queries* is a dictionary with the session IDs as
keys and which URL that was accessed that triggered the SP to send the keys and which URL that was accessed that triggered the SP to send the
request. request.

10
doc/install.rst
View File

@@ -10,8 +10,8 @@ Install Pysaml2
--------------- ---------------
For all this to work you need to have Python installed. For all this to work you need to have Python installed.
The development has been done using 2.6, but it might work with earlier The development has been done using 2.6.
versions. There is no 3.X version yet. There is no 3.X version yet.
Prerequisites Prerequisites
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
@@ -38,7 +38,9 @@ will install the basic code.
After this you ought to be able to run the tests without an hitch. After this you ought to be able to run the tests without an hitch.
The tests are based on the pypy test environment, so:: The tests are based on the pypy test environment, so::
py.test tests cd tests
py.test
is what you should use. If you don't have py.test, get it ! It's good ! is what you should use. If you don't have py.test, get it !
It's really good !