openstack/deb-python-pysaml2
Code Issues Proposed changes

Updated the documentation

Browse Source
This commit is contained in:
Roland Hedberg
2010-03-22 10:53:26 +01:00
parent b7345a5e9a
commit d79c9aef15
4 changed files with 133 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
doc/howto/config.rst
View File

@@ -18,7 +18,7 @@ directives are the top level keys.
Configuration directives
------------------------
attribute_maps
^^^^^^^^^^^^^^
@@ -26,17 +26,17 @@ Format::
attribute_maps: ["attribute.map"]
Points to simple key/value files that, most commonly, contains the unique
name of attributes and their friendly names separated by a blank, one
attribute per line::
Points to simple files that, most commonly, contains the unique
name of attributes, their friendly names and their type separated by a blank,
one attribute per line::
urn:oid:2.5.4.4, surName
urn:oid:2.5.4.42 givenName
urn:oid:2.5.4.12 title
urn:oid:0.9.2342.19200300.100.1.1 uid
urn:oid:0.9.2342.19200300.100.1.3 mail
urn:oid:1.3.6.1.4.1.5923.1.1.1.1 eduPersonAffiliation
urn:oid:1.3.6.1.4.1.5923.1.1.1.7 eduPersonEntitlement
urn:oid:2.5.4.4 surName urn:oasis:names:tc:SAML:2.0:attrname-format:uri
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: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
urn:oid:1.3.6.1.4.1.5923.1.1.1.1 eduPersonAffiliation urn:oasis:names:tc:SAML:2.0:attrname-format:uri
urn:oid:1.3.6.1.4.1.5923.1.1.1.7 eduPersonEntitlement urn:oasis:names:tc:SAML:2.0:attrname-format:uri
To be used by a SP or an IdP when translating back and forth between
user friendly names and universally unique names.
@@ -52,6 +52,28 @@ A file that contains CA certificates that the service will use in
HTTPS sessions to verify the server certificate.
*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 descibed by the configuration file.
This is where you descibed the persons can be contacted if questions arises
about the service or if support is needed::
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": "Management",
}]
debug
^^^^^
@@ -92,10 +114,33 @@ a file accessible on the server the service runs on or somewhere on the net.::
"metadata.xml", "vo_metadata.xml"
],
"remote": [
"https://kalmar2.org/aggregator/?id=kalmarcentral&set=saml2"
],
{
"url":"https://kalmar2.org/aggregator/?id=kalmarcentral&set=saml2",
"cert":"kalmar.cert"
}],
},
When the metadata is to be picked from the net. there is the possibility to
specify a certificate that is to be used to verify that the metadata is as
produced by the other party. This certificate 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 wewbpage, by entering a tuple, instead of a simple string,
where the second part is the language code.
service
^^^^^^^
@@ -118,7 +163,7 @@ this::
There are two options common to all services: 'name' and 'url'. With the
obvious meanings.
There also exits special option for SPs namely: 'idp', 'optional_attributes'
There also exists special option for SPs namely: 'idp', 'optional_attributes'
and 'required_attributes'.
Both IdPs and AAs can have the option 'assertions'
@@ -176,12 +221,13 @@ Here only mail addresses that ends with ".umu.se" will be returned.
idp (sp)
""""""""
Defines the set of IdPs that this SP can use. If there is metadata loaded
then the value is expected to be a dictionary with entity identifiers as
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 and possibly the IdP url as values. 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, would look something
like this::
A typical configuration, when metadata is present and the allowed set of
IdPs are limited, would look something like this::
"idp": {
"urn:mace:umu.se:saml:roland:idp": None,
@@ -191,7 +237,7 @@ 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 (NOT IMPLEMENTED YET) would use the metadata file to
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::
@@ -202,7 +248,8 @@ metadata might be overkill so this construct can be used instead::
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
name of the IdP. Which again if no WAYF is used is immaterial.
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
@@ -219,6 +266,10 @@ Attributes that this SP would like to receive from IdPs.
Example::
"optional_attributes": ["title"],
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
with other servers.
required_attributes (sp)
""""""""""""""""""""""""
@@ -229,6 +280,8 @@ Example::
"required_attributes": ["surName", "givenName", "mail"],
Again as for *optional_attributes* the names given are expected to be
the user friendly names.
subject_data
^^^^^^^^^^^^
@@ -243,9 +296,19 @@ Example::
xmlsec_binary
^^^^^^^^^^^^^
Presently xmlsec1 binaries are use 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.
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
^^^^^^^^^^^^^^^^^^^^
@@ -258,10 +321,10 @@ Gives information about common identifiers for virtual_organizations::
}
},
Keys are identifiers for 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 has common attribute values
for users that are part of the VO.
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.
Example
-------
@@ -283,10 +346,19 @@ We start with a simple Service provider configuration::
},
"key_file" : "./mykey.pem",
"cert_file" : "./mycert.pem",
"xmlsec_binary" : "/opt/local/bin/xmlsec1",
"xmlsec_binary" : "/usr/local/bin/xmlsec1",
"metadata" : {
"local": ["metadata.xml", "vo_metadata.xml"],
},
"attribute_maps": ["attribute.map"],
"organization": {
"display_name":["Rolands identiteter"]
}
"contact_person": [{
"givenname": "Roland",
"surname": "Hedberg",
"phone": "+46 90510",
"mail": "roland@example.com",
}]
}

6
doc/howto/idp.rst
View File

@@ -7,7 +7,7 @@ To make an SAML2 identity provider is a bit tricker than doing a service
provider, mainly because you have to divide the functionality between
the application and the plugins.
Now, to do that you have to understand how repoze.who works.
Basically on every request; the ingress plugins first gets to do there stuff,
Basically on every request; the ingress plugins first gets to do their stuff,
then the application and finally the egress plugins.
So in broad terms this is what happens:
@@ -45,8 +45,8 @@ So in broad terms this is what happens:
environment variable ('s2repoze.qinfo').
If the login and password was correct a cookie is issued. If there is
a mdprovider plugin defined it will now add extra information about
the individual. After this the control is passed on to the
application.
the individual from some external source.
After this the control is passed on to the application.
2.2 The function that is bound to the path of the IdP now gets to act.
This is just the main outline:

2
doc/howto/index.rst
View File

@@ -7,7 +7,7 @@ How to use PySAML2
:Date: |today|
Before you can use Pysaml2, you'll need to get it installed.
If you have done it yet, read the :ref:`install`
If you have not done it yet, read the :ref:`install`
Well, now you have it installed and you want to do something.

32
doc/howto/sp.rst
View File

@@ -34,7 +34,19 @@ like this::
user_info = environ["repoze.who.identity"]["user"]
If a WAYF is going to be used, then the pattern is the following:
unauthenticated user + no IdP selected
In this case, if there is a WAYF page specified in the
SP part of the repoze.who configuration file,
the user is redirected to that page. If no page is known an exception
is raised.
unauthenticated user + selected IdP
This is after the WAYF has been used, the entity ID of the selected IdP
is expected to be in the environment variable *s2repose.wayf_selected*.
If so the user is redirected to that IdP.
The set up
----------
@@ -66,6 +78,9 @@ cache
remember information received from IdPs and AAs. If a file name
is given that file will be used for persistent storage of the cache.
wayf
The webpage where the WAYF service is situated.
An example::
[plugin:saml2sp]
@@ -75,10 +90,11 @@ An example::
virtual_organization=urn:mace:umu.se:vo:it-enheten:cms
debug = 1
cache = /tmp/sp.cache
wayf = wayf.html
Once you have configured the plugin you have to tell the server to use the
plugin in different ingress and egress operations as specified in
`Middleware responsibilities <http://docs.repoze.org/who/narr.html>`_ ::
`Middleware responsibilities <http://docs.repoze.org/who/narr.html>`_
A typical SP configuration would be to use it in all aspects::
@@ -95,3 +111,17 @@ A typical SP configuration would be to use it in all aspects::
[mdproviders]
plugins = saml2sp
Other information
-----------------
The SP keeps tabs on all outstanding authentication requests it has.
This is kept in the local variable *outstanding_authn*.
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
future.
The format of *outstanding_auth* is a dictionary with the session IDs as
keys and which URL that was accessed that triggered the SP to send the
request.