Create an Attribute Manipulation

Workflow

Create an Attribute Manipulation test file.
Create an Attribute Manipulation file.
Add Attribute Manipulation to ServiceRegistry.
Set the Attribute Release Policy (ARP).
Check related Metadata fields.

Requirements

Input specification - Which attributes are provided and what is the format of the values
Output specification - Which attributes (or NameID) are to be send to the SP (in case of SP Attribute Manipulation) or Engine (in case of an IdP Attribute Manipulation)

Actions

Create a Attribute Manipulation test file

Since ServiceRegistry does not provide a option for testing the Attribute Manipulation and to protect OpenConext, first create a test case in PHP for the Attribute Manipulation.

The following instructions are to create a simple Attribute Manipulation test 'environment'. It is possible to create a test-case with PHPunit.

Create a new folder
Create a new PHP-file with name: test.php
Insert the following code in test.php:

<?php

echo 'start test ' . PHP_EOL;
$subjectId = null;
$attributes = array (
  'urn:mace:dir:attribute-def:uid' => array ( 'john'),
  'urn:mace:dir:attribute-def:mail' => array ('[email protected]'),
  'urn:mace:terena.org:attribute-def:schacHomeOrganization' => array ('test.nl'),
);
require('manipulation.php');
echo 'Subject=' . $subjectId . PHP_EOL;
echo PHP_EOL;
echo 'Attributes returned:' . PHP_EOL;
var_dump($attributes);

?>

Update the the attributes array with the attributes specified in the input specification.

Before the Attribute Manipulation an ARP has been applied.

Create a new php file with name: manipulation.php

The name of the file might be different, but this is also used for the file based Attribute Manipulation)

Insert the following code in manipulation.php:

<?php

Test the empty manipulation by running the test.php file via Command Line:

php test.php

Create Attribute Manipulation file

Before placing the Attribute Manipulation in ServiceRegistry (JANUS) it is wise to first create and test it in a separate file (see above).

The following variables can be used and/or altered. These are:

variable	type
$subjectId	String	The internal variable to be used for NameID within the SAML Response (Response->Assertion->Subject->NameID).
$attributes	Array of Arrays of String	Contains all the attributes provided by the IdP after applying the ARP.
$response	Array	The response is given in EngineBlock / Corto XmlToArray format.
$idpMetadata	Array, read only, [Example](idpMetadata Example)	The metadata of the IdP.
$spMetadata	Array, read only, [Example](spMetadata Example)	The metadata of the SP.

Changing the $subjectID

When changing the $subjectId the Metadata NameIDFormat must be set to urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified. Otherwise the NameID field will be overwritten with the persistent or transient value.

Static:

$subjectId = 'test-account';


* With first value of mail-attribute:

  ```php
$subjectId = $attributes['urn:mace:dir:attribute-def:mail'][0];

Chaining the $attributes Array

An example of the attributes (Array of Arrays of String):

$attributes = array (
    'urn:mace:dir:attribute-def:uid' => array ( 'john'),
    'urn:mace:dir:attribute-def:mail' => array ('[email protected]','[email protected]'),
    'urn:mace:terena.org:attribute-def:schacHomeOrganization' => array ('test.nl'),
);

It is possible to completely modify, add and delete the $attributes array:

modify:

$attributes['urn:mace:dir:attribute-def:mail'] = array('[email protected]');


* add:

  ```php
$attributes['urn:mace:dir:attribute-def:eduPersonEntitlement'] = array('urn:surf.nl:test.nl:entitlement:wiki-admin');

delete:

unset($attributes['urn:mace:dir:attribute-def:mail']);


When using a value make sure the value is available. The code is directly executed within Engine and any exception with the manipulator-code will result in an exception during the login-sequence for the IdP or SP.  An example is (set $subjectId to first email-address):

```php
if (isset($attributes) and ($attributes !== FALSE)) {
    if (!empty($attributes['urn:mace:dir:attribute-def:mail'][0])) {
            $subjectId = $attributes['urn:mace:dir:attribute-def:mail'][0];
    }
}

Changing the $reponse

Small example of a manipulation of a response to create a 'Transparant NameID':

$response['__']['CustomNameId'] = $response['__']['OriginalResponse']['__']['OriginalNameId'];

In this example the NameID from the provider is injected in the response for the SP.

More information for the $response is left out of scope, this can be found at https://github.com/SURFconext/SURFConext-attribute-manipulations/blob/master/RESPONSEFORMAT.md

Other examples:

[Check entitlement](AM-Check entitlement) (including Custom Error)
[Example $idpMetadata](idpMetadata Example) (Attribute Manipulations)
[Example $spMetadata](spMetadata Example)a (Attribute Manipulations)
[Google Apps based on EPPN](AM-Google Apps based on EPPN)
[Google Apps based on uid](AM-Google Apps based on uid)
[Google Apps for the VU](AM-Google Apps for the VU) (complex example)
[Recover UID and schacHomeOrganization from ePPN](AM-Recover UID and schacHomeOrganization from ePPN)
[Removal of all Attributes](AM-Removal of all Attributes)
[Removal of not specified attributes](AM-Removal of not specified attributes) (like ARP)
[Transparant Name ID](AM-Transparant Name ID)

Add Attribute Manipulation to ServiceRegistry

Log into Serviceregistry and open the IdP/SP entity (edit).
Go to tab 'Manipulation'
Copy/Paste the contents of the manipulations.php file into text-box.
Add revision note (at the bottom of the page)
Remember the revision number (on the top of the page)
Click 'Save' (at the bottom of the page)
Check if revision number has been increased, this implies the save was successful.

The syntax of the content must be correct, if not the following error appears: Parse error: syntax error, unexpected $end on line 1

##Set ARP

Irrelevant for IdP attribute manipulations

Be sure to release all the attributed needed for the attribute manipulation and also the required attributes for the SP.

When an attribute is needed for the manipulation but may not be released to the SP the attribute can be deleted (unset) from $attributes.

The consent-page is only based on the ARP. The user must provide consent for all attributes in the ARP even when the attribute is to be deleted during the attribute manipulation. This is the same for the SelfService-portal.

Check related Metadata fields