6.4. Customizing SAML Assertions

Home Prev	EasyAccess 4.3 Getting Started Guide	Next

In federation scenarios, each service provider may expect specific user data to be included in the SAML assertion created by EasyAccess and the included data may also need a specific attribute name in the assertion. The data itself may also need to be processed in some way, for instance converted from binary to a string, or possibly changed to all uppercase.

Such specific requirements can be met by including a set of custom valves in the execution flow for a scenario.

Below is a an example of such a customization:

An LDAPSearchValve will always be used to retrieve data for a specific user. The attributes property of the valve must specify all the data items that will be used later when creating assertions for different service providers.

{
  "name": "LDAPSearchValve",
  "enabled": "true",
  "config": {
    "connection_ref": "bbd7198c-0a6c-43aa-b62b-cd7552c8b4cf",
    "base_dn": "DC=maso,DC=lan",
    "scope": "SUB",
    "size_limit": "0",
    "filter_template": "samAccountName={{request.username}}",
    "attributes": "objectGUID,samAccountName,sn,mail,givenName",
    "binary_attrs": "objectGUID"
  }
},

One or more subsequent PropertyCopyValve instances can now be used in the scenario's execution flow to copy over user data to new attribute names that are required by the service provider in the SAML assertion. For example, the following valve will copy the sn attribute value fetched by the LDAPSearchValve above into a new attribute called last_name.
```
{
  "name": "PropertyCopyValve",
  "enabled": "true",
  "config": {
    "proceed_on_error": "false",
    "source": "sn",
    "dest": "last_name"
  }
},
```

Similarly, the givenName can be copied into a new attribute called first_name.

{
  "name": "PropertyCopyValve",
  "enabled": "true",
  "config": {
    "proceed_on_error": "false",
    "source": "givenName",
    "dest": "first_name"
  }
},

Various other valve types are available to perform a variety of data conversions where the service provider expects user data in a given form. For example, the following GUIDBinaryToStringValve will convert the binary objectGUID value to a string that is assigned to the assertion property called userid.
```
{
  "name": "PropertyGUIDBinaryToStringValve",
  "enabled": "true",
  "config": {
    "proceed_on_error": "false",
    "source": "objectGUID",
    "dest": "userid"
  }
},
```
Note that the objectGUID can be a very useful object to pass in an assertion because it will not change, even if the username does.
The valve called PropertyToUpperValve could then be used to make sure that the new string property called userid is all uppercase.
```
{
  "name": "PropertyToUpperValve",
  "enabled": "true",
  "config": {
    "proceed_on_error": "false",
    "source": "userid"
  }
},
```
An AuthnRequestDecoder will need to be included if there are multiple service providers and therefore multiple AssertionProvider valves when each valve is testing the issuer property. No customization of this valve is required and its default values are listed below.
```
{
  "name": "AuthnRequestDecoder",
  "enabled": "true",
  "config": {
    "proceed_on_error": "false"
   }
 },
```
Add an AssertionProvider for each service provider so that different values for the additionalAttributes property can be specified in the SAML assertion created for that provider.

For example, the following assertion would only be used in the execution flow if the service provider is called MyExampleSP. This provider requires the additional properties of userid, mail and givenName in the SAML assertion given to it.
```
{
  "name": "AssertionProvider",
  "enabled": "true",
  "config": {
    "targetEntityID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
    "nameIDAttribute": "sAMAccountName",
    "additionalAttributes": "userid,mail,givenName",
    "exec_if_expr": "flow.property('issuer').equals('MyExampleSP')"
  }
},
```
Note that the targetEntityValue for all assertions must be the ID value of the scenario's identity provider.

A second AssertionProvider can now be added for a second service provider called MyOtherExampleSP that requires the last_name and first_name data.

{
  "name": "AssertionProvider",
  "enabled": "true",
  "config": {
    "exec_if_expr": "flow.property('issuer').equals('myOtherEaxampleSP')",
    "targetEntityID": "f1dab3a5-02a0-43c6-afef-9d8e39323eb3",
    "nameIDAttribute": "sAMAccountName",
    "additionalAttributes": "last_name,first_name,mail",
  }
},