Updated documentation
This commit is contained in:
Roland Hedberg
209
doc/config.rst
209
doc/config.rst
@@ -1,209 +0,0 @@
|
|||||||
.. _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 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 toplevel keys.
|
|
||||||
|
|
||||||
Configuration directives
|
|
||||||
------------------------
|
|
||||||
|
|
||||||
attribute_maps
|
|
||||||
^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
A simple key value file that contains the unique name of attributes,
|
|
||||||
their friendly name and possible other names used in backend databases
|
|
||||||
in a comma separated 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
|
|
||||||
|
|
||||||
To be used by a SP if it wants to translate provided more complex unique
|
|
||||||
to more user friendly names or when an IdP/AA wants to translate attribute
|
|
||||||
names provided by a backend database into more formal names.
|
|
||||||
|
|
||||||
cert_file
|
|
||||||
^^^^^^^^^
|
|
||||||
|
|
||||||
A file that contains CA certificate that the service will use in
|
|
||||||
HTTPS sessions to verify the server certificate.
|
|
||||||
*cert_file* must be a PEM formatted certificate chain file.
|
|
||||||
|
|
||||||
debug
|
|
||||||
^^^^^
|
|
||||||
|
|
||||||
Whether debug information should be sent to the logfile.
|
|
||||||
|
|
||||||
entityid
|
|
||||||
^^^^^^^^
|
|
||||||
|
|
||||||
The identifier of the entity.
|
|
||||||
|
|
||||||
key_file
|
|
||||||
^^^^^^^^
|
|
||||||
|
|
||||||
*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
|
|
||||||
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": [
|
|
||||||
"https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral&set=saml2"
|
|
||||||
],
|
|
||||||
},
|
|
||||||
|
|
||||||
service
|
|
||||||
^^^^^^^
|
|
||||||
|
|
||||||
Which services the server will provide, those are combinations of "idp","sp"
|
|
||||||
and "aa".
|
|
||||||
So if one server is supposted to be both SP and AA (attribute authority) then
|
|
||||||
the configuration could look something like this::
|
|
||||||
|
|
||||||
"service": {
|
|
||||||
"aa":{
|
|
||||||
"name" : "VO AA",
|
|
||||||
"url": "http://localhost:8090/soap",
|
|
||||||
},
|
|
||||||
"sp":{
|
|
||||||
"name" : "VO SP",
|
|
||||||
"url" : "http://localhost:8090/sp",
|
|
||||||
}
|
|
||||||
},
|
|
||||||
|
|
||||||
There are two options common to all services: 'name' and 'url'. With the
|
|
||||||
obvious meanings.
|
|
||||||
There are exits special option for SPs namelu: 'idp', 'optional_attributes'
|
|
||||||
and 'required_attributes'.
|
|
||||||
Both IdPs and AAs can have the option 'assertions'
|
|
||||||
|
|
||||||
assertions
|
|
||||||
""""""""""
|
|
||||||
|
|
||||||
If the server is an IdP or and AA then there might be reasons to things
|
|
||||||
differently depending on how 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.
|
|
||||||
An example might be::
|
|
||||||
|
|
||||||
"assertions": {
|
|
||||||
"default": {
|
|
||||||
"lifetime": {"minutes":15},
|
|
||||||
"attribute_restrictions": None # means all I have
|
|
||||||
},
|
|
||||||
"urn:mace:umu.se:saml:roland:sp": {
|
|
||||||
"lifetime": {"minutes": 5},
|
|
||||||
"attribute_restrictions":{
|
|
||||||
"givenName": None,
|
|
||||||
"surName": None,
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
Means that the server will se not_on_or_after to be *now* + 15 minutes as
|
|
||||||
default. Hence the receivers should not use the information after 15 minutes
|
|
||||||
from *now*. 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 should be returned.
|
|
||||||
For the SP with the entityid "urn:mace:umu.se:saml:roland:sp" other rules
|
|
||||||
apply. The information is only valid for 5 minutes and only the attributes
|
|
||||||
'givenName' and 'surName' are returned. No limitations as which values for
|
|
||||||
these attributes can be returned exists.
|
|
||||||
If restrictions on values are deemed necessary those are represented by
|
|
||||||
regular expressions.::
|
|
||||||
|
|
||||||
"assertions": {
|
|
||||||
"urn:mace:umu.se:saml:roland:sp": {
|
|
||||||
"lifetime": {"minutes": 5},
|
|
||||||
"attribute_restrictions":{
|
|
||||||
"mail": [".*\.umu\.se$"],
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
Here only mailaddresses that ends with ".umu.se" will be returned.
|
|
||||||
|
|
||||||
idp
|
|
||||||
"""
|
|
||||||
|
|
||||||
Defines the set of IdPs that this SP can use. If there is a metadata loaded
|
|
||||||
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 learn it from the metadata.
|
|
||||||
A typical configuration would look something like this::
|
|
||||||
|
|
||||||
"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 (NOT IMPLEMENTED YET) would use the metadata file to
|
|
||||||
find out the names for the different IdPs.
|
|
||||||
On the other hand if the SP only uses one specific IdP then the usage of
|
|
||||||
metadata file might be overkill so this construct can be used instead::
|
|
||||||
|
|
||||||
"idp": {
|
|
||||||
"" : "https://example.com/saml2/idp/SSOService.php",
|
|
||||||
},
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
There is a third choice and that is to leave the configuration blank, that
|
|
||||||
is an empty dictionary, in which case all the IdP present in the metadata
|
|
||||||
will be regarded as eligable services to use. ::
|
|
||||||
|
|
||||||
"idp": {
|
|
||||||
},
|
|
||||||
|
|
||||||
optional_attributes
|
|
||||||
"""""""""""""""""""
|
|
||||||
|
|
||||||
Attributes that this SP would like to receive from IdPs.
|
|
||||||
|
|
||||||
required_attributes
|
|
||||||
"""""""""""""""""""
|
|
||||||
|
|
||||||
Attributes that this SP demands to receive from IdPs.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
subject_data
|
|
||||||
^^^^^^^^^^^^
|
|
||||||
|
|
||||||
The name of a shelve database where the map between a local identifier and
|
|
||||||
a distributed identifier is kept.
|
|
||||||
|
|
||||||
xmlsec_binary
|
|
||||||
^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
Presently xmlsec1 binaries are use for all the signing and encryption stuff.
|
|
||||||
This option defines where the binary is situatied.
|
|
||||||
|
|
||||||
Example
|
|
||||||
-------
|
|
||||||
|
|
||||||
@@ -1,4 +1,4 @@
|
|||||||
.. _idp:
|
.. _example_idp:
|
||||||
|
|
||||||
An extremly simple example of a SAML2 identity provider.
|
An extremly simple example of a SAML2 identity provider.
|
||||||
========================================================
|
========================================================
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
.. _example_index:
|
.. _example_index:
|
||||||
|
|
||||||
These are examples of the usage of pysaml2!
|
These are examples of the usage of pySAML2!
|
||||||
===========================================
|
===========================================
|
||||||
|
|
||||||
:Release: |version|
|
:Release: |version|
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
.. _sp:
|
.. _example_sp:
|
||||||
|
|
||||||
An extremly simple example of a SAML2 service provider.
|
An extremly simple example of a SAML2 service provider.
|
||||||
=======================================================
|
=======================================================
|
||||||
|
|||||||
@@ -1,40 +0,0 @@
|
|||||||
.. _howto:
|
|
||||||
|
|
||||||
How to use PySAML2
|
|
||||||
===================
|
|
||||||
|
|
||||||
Before you can use Pysaml2, you'll need to get it installed.
|
|
||||||
If you have done it yet, read :ref:`install`
|
|
||||||
|
|
||||||
Well, now you have it installed and you want to do something.
|
|
||||||
|
|
||||||
And I'm sorry to tell you this; but there isn't really a lot you can do with
|
|
||||||
this code on it's own.
|
|
||||||
|
|
||||||
Sure you can send a AuthenticationRequest to an IdentityProvider or a
|
|
||||||
AttributeQuery to an AttributeAuthority but in order to get what they
|
|
||||||
return you have to sit behind a Web server. Well that is not really true since
|
|
||||||
the AttributeQuery would be over SOAP and you would get the result over the
|
|
||||||
conenction you have to the AttributeAuthority.
|
|
||||||
|
|
||||||
But anyway, you get may get my point. This is middleware stuff here !
|
|
||||||
|
|
||||||
Pysaml2 is built to fit into a
|
|
||||||
`WSGI <http://www.python.org/dev/peps/pep-0333/>`_ application
|
|
||||||
|
|
||||||
There are more than one WSGI framework out there, so when I started this work
|
|
||||||
I just picked one I liked, namely `Repoze <http://repoze.org/>`_ .
|
|
||||||
Or to be more specific I choose to work within the context of
|
|
||||||
`Repoze.who <http://static.repoze.org/whodocs/>`_.
|
|
||||||
|
|
||||||
So, in order to get something up and running for you to play with, I've
|
|
||||||
put a couple of examples in this package all of them based on the use of
|
|
||||||
Pysaml2 together with Repoze.
|
|
||||||
|
|
||||||
You can easily get repoze.who from
|
|
||||||
`PyPi <http://pypi.python.org/pypi/repoze.who>`_
|
|
||||||
preferrably by uing easy_install.
|
|
||||||
|
|
||||||
And now on to the examples:
|
|
||||||
|
|
||||||
SAML2 Service provider :ref:`sp`
|
|
||||||
@@ -17,7 +17,7 @@ Contents:
|
|||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
install
|
install
|
||||||
howto
|
howto/index
|
||||||
saml2
|
saml2
|
||||||
examples/index
|
examples/index
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user