openstack/deb-python-pysaml2

Files

rhoerbe 47806dfbac finally manage to fix the hyperlink syntax

2014-07-03 18:35:31 +02:00

17 KiB

Raw Blame History

How to use SAML2test

Release
Date

Before you can use SAML2test, you must get it installed. If you have not done so yet, read Install.

When you want to test a SAML2 entity with this tool you need following things:

The Test Driver Configuration, an example can be found in tests/idp_test/config.py
Attribute Maps mapping URNs, OIDs and friendly names
Key files for the test tool
A metadata file representing the tool
The Test Target Configuration file describes how to interact with the entity to be tested. The metadata for the entity is part of this file. An example can be found in tests/idp_test/test_target_config.py.

These files should be stored outside the saml2test package to have a clean separation between the package and a particular test configuration. To create a directory for the configuration files copy the saml2test/tests including its contents.

(1) Test Driver Configuration

This is a normal PySAML2 configuration file. You can have more than one and then chose which one to use at run time by supplying the test script with an argument. If no configuration is explicitly provided than tests/ipd_test/config.py is provided as a default.

This configuration mostly contains the test tool’s metadata structured as a Python dictionary. It doesn't vary a lot between testing different IdPs, except for the value of BASE, and optionally these control options:

In addition to the configuration directives documented for the PySAML2 configuration file these may be used:

accepted_time_diff

Default: 60

logger

Specify the logging options for the test run.

only_use_keys_in_metadata

If true it ignore the validation path of signing keys. As of V0.4.0, this does not apply to TLS keys (which does not conform to [SAML MetaIOP]. If false it does validate the signing certificate against the default CA keys of pysaml2. Add the directory to python path, like: export PYTHONPATH=/some_path/saml2test.conf # Remember: no trailing slash in PYTHONPATH

secret

Not being used currently

You could also change organization and contact information if you'd like to.

(2) Attribute Mapping

Attributes that may be contained in a SAML assertion must be defined in the attribute mapping as documented in the PySAML2 config guide. If the ‚to‘ and ‚fro‘ mappings are exactly the same just one of them is required. But sometimes it is necessary to have both "to" and "from" because translation isn't symmetric. Like having "sn" and "surname" mapping to the same urn.

You may copy the default mapping into your test configuration directory: cp -pr saml2test/tests/attributemaps .

There must be one file per attribute namespace, i.e. attrname-format:basic needs to go into basic.py, and attrname-format:uri needs to go into saml_uri.py.

(3) Key Files

The test tool’s metadata needs key files, both a private key and a certificate. The default files are provided in same2test/tests/keys as: mykey.pem mycert.pem To change file names, the references in the Tool Configuration need be be changed as well.

(4) Test Tool Metadata

The test tool’s metadata is generated from the contents of the Tool Configuration, e.g.: make_metadata.py config.py > testdrv_metadata.xml

The resulting SAML2 metadata needs to be imported to the test target.

(5) Test Target Configuration File

This configuration is contained in the "info" Python dictionary.

The keys are:

entity_id

entity_id is really only necessary if there is more than one entity represented in the metadata. If not provided and if the metadata only describes one entity that entity's entityID is used.

start_page

URL for the initial request the test driver issues when executing an SP test.

args

Contains a Python dictionary controlling some aspects of an Authnentication Response" with following structure:

"AuthnResponse": {
    "sign_assertion": True,
    "authn":  {"class_ref": AUTHN_PASSWORD_PROTECTED, # Authentication Context Class Reference
               "authn_auth": "http://authnservice.example.com/login"}  # Authenticating Authority
},

identity

Contains a list of key-value pairs with attribute names and values, that the embedded IDP will include in assertions. Attribute Names in this context are friendly names, not URNs/OIDs. To obtain these attributes from the IDP there are three options: #. include an EntityCategory in the EntityDescriptor of the SP. The EntityCategory must be defined in pysaml2. #. include RequestedAttributes in the EntityDescriptor of the SP. #. include RequestedAttributes in the AuthnRequest. These methods work additive. Attributes must be registered in the attribute map.

userid

The UserID used as a base for the Assertion/Subject/NameID.

interaction

The really hard part is the interaction part. This is where the the script is told how to fake that there is a human behind the keyboard.

It consists of a lists of dictionaries with the keys: matches, page-type and control.

The idea is to use matches to activated a corresponding set of controls.

matches

matches is used to identify a page or a form within a page. There are four different things that can be used to match the page:

url : The action url
title : The title of the page, substring matching is used.
content: Something in the page, again substring matching is used, and finally
class: (currently not used)

Normally the front-end will pick out the necessary information by using a users interaction with the entity. If you are running this directly from the prompt then you have to provide the information. You can build this information by using the fact that the script will dump any page it doesn't know what to do with.

An example:

{
    "matches": {
        "url": "http://localhost:8088/login",
        "title": 'IDP test login'
    },
    "page-type": "login",
    "control": {
        "type": "form",
        "set": {"login": "roland", "password": "dianakra"}
    }
}

The action here is to set the control login to 'roland' and the control password to 'dianakra' and then post the form.

Or if the server uses HTTP Post binding:

{
    "matches": {
        "url": "http://localhost:8088/sso/redirect",
        "title": "SAML 2.0 POST"
    },
    "control": {
        "type": "response",
        "pick": {"form": {"action":"http://localhost:8088/acs"}}
    }
},

Here the action is just to post the form, no information is added to the form.

page-type

page-type is used to mark the page as login or user-consent. This is used in specific conversation where one or the other is expected in certain circumstances.

control

control specifies what the script should enter where and which button to press.

metadata

This is then the metadata for the entity to be tested. As noted previously the metadata can actually describe more than one entity. In this case the entity_id must be specified explicitly.

Running the script testing an IDP

Synopsis:

$ idp_testdrv.py --help
usage: idp_testdrv.py [-h] [-d] [-H] [-C CA_CERTS] [-J TT_CONFIG_FILE] [-m] [-l]
                 [-c TD_CONFIG]
                 [oper]

positional arguments:
  oper                 Which test to run

optional arguments:
  -C CA_CERTS            CA certs to use to verify HTTPS server certificates, if
                         HTTPS is used and no server CA certs are defined then
                         no cert verification will be done. For a generic validation you may use the ca_bundle.crt
                         file that comes with Mozilla.
  -c TD_CONFIG, --config Test driver configuration module at the current directory or the path specified
                         with the -P option. Do not use relative paths or the .py filename extension
  -d, --debug            Print debug information to stderr
  -H, --prettyprint      Human readable status output
  -h, --help             show this help message and exit
  -J TT_CONFIG_FILE      Test target configuration in JSON format
  -L, --log              Print HTTP log information # TODO: update documentation
  -l, --list             List all the test operations as a JSON object
  -m, --metadata         Return the SP metadata
  -O, --operations       Operations module (generated from Repository as idp_saml2base.py)
  -P, --configpath       Path to the configuration file for the SP
  -t, --testpackage      Module describing tests (e.g. idp_samlbase.py generated from repository)
  -Y, --pysamllog        Print pySAML2 logs to stderr

Remember to generate the

Running the script testing an SP