[[ucc_saml-push]]
SAML PUSH support
-----------------

=== Introduction

UCC supports the "SAML PUSH" mode of authentication. In this mode, the user is authenticated 
by an attribute assertion signed by a trusted third party. The third party is a 
Virtual Organisation (VO), SAML 2.0 server such as UVOS or VOMS.

=== Basic usage

First, retrieve an attribute assertion from VO server, scoped for a particular group you are in, 
and save it into a file.

----
ucc save-attributes -J https://uvos.example.com:2443 -G /vo/group -O assertion.xml
----

If the VO server has been registered in the registry, you may use "auto" instead of server's URL 
(this is possible only in case of UVOS).

----
ucc save-attributes -J auto -G /vo/group -O assertion.xml
----

Then, you may use this assertion to get access to the server. Most UCC commands support this, for 
example you may connect to the server using this assertion.

----
ucc connect -A assertion.xml
----

You also may combine those two steps into one:

----
ucc connect -J https://uvos.example.com:2443 -G /vo/group
----

or assuming that UVOS server is in the registry:

----
ucc connect -J auto -G /vo/group
----

However note that using <<<-A>>> option is faster: attributes are read from a file, while in the combined
scenario the attributes are fetched from a remote VO server prior to invocation of the intended UCC command.

=== Attribute filtering

You might want to obtain an assertion with only handful of attributes and their values. This is 
done by using attribute filters. 

UCC can display a list of all attributes. Names, scopes, values and descriptions (if available) will be displayed.

----
ucc list-attributes -J auto
----

The last column (F) contains a letter Y next to all attribute values, that pass through attribute filters. 
There are two kinds of filters: inclusive filters (which specify what attributes should pass) 
and exclusive filters (which specify what attributes should be filtered out). 
If not specified, the default inclusive filter approves of all attributes and their values, and the default 
exclusive filter does not reject anything.

In this example an inclusive filter choose only those attributes, whose name contains the word "xlogin".

----
ucc list-attributes -J auto -I ".*xlogin.*"
----

The value for the <<<-I>>> option is a list of semicolon-separated Java regular expressions. 
The expressions that contain the equal sign are called name-value filters, 
those which do not are called name filters.

For example, you may choose all attributes with names that contain the word "login", and the "admin" value of all 
attributes containing the word "role" in their name.

----
ucc list-attributes -J auto -I ".*xlogin.*;.*role.*=admin"
----

You may also exclude attributes. For example, the following filter 
chooses all attributes but those ending with an "a".

----
ucc list-attributes -J auto -Q ".*a"
----

If you are content with the results of filtering, you can obtain an assertion only with the filtered attributes.

----
ucc save-attributes -J auto -G /vo/group -O assertion.xml -I ".*xlogin.*;.*role.*=admin" -Q ".*a"
----

You can also use it directly.

----
ucc connect -J auto -G /vo/group -I ".*xlogin.*;.*role.*=admin" -Q ".*a"
----

Rules for multiple filters
~~~~~~~~~~~~~~~~~~~~~~~~~~

Each attribute is considered as a set of name-value pairs, containing the name of attribute and the value of attribute. 

A pair matches a name filter (i.e. a filter defined using a regular expression without equals sign) 
if the name of the attribute matches the regular expression.

A pair matches a name-value filter (i.e. a filter defined using a regular expression with equals sign) 
if the name of the attribute matches the left hand of the regular expression, and the value matches the right hand.

For each pair, the following steps are performed:

 * if there is a matching exclusive name-value filter, the pair is rejected

 * otherwise, if there is a matching inclusive name-value filter, the pair passes

 * otherwise, if there is a matching exclusive name filter, the pair is rejected

 * otherwise, if there is a matching inclusive name filter, or there are no inclusive name filters, the pair passes

 * otherwise, the pair is rejected

The result of filtering are the attributes, containing only those values which passed (after filtering, 
empty attributes are discarded).

