Difference between revisions of "Simple SAML PHP"

Revision as of 18:35, 10 September 2015

About

This page enumerates some configuration methodologies for Simple SAML PHP when trying to configure for use as a GFIPM/NIEF Identity Provider.

Attributes

It is necessary to configure Simple SAML to both filter attributes correctly and to map and define GFIPM/NIEF attributes correctly. Each section below should be reviewed below and your configuration should be updated according to your requirements.

Attribute Filters

Simple SAML PHP supports filtering attributes sent to Relying Parties based on the attributes they have requested via Trust Fabric / SAML2 Metadata. This is a great feature, but by default this filtering can happen before the attributes have been derived from local attributes. To alter this behavior you need to change the filter priority. Do this by editing config/config.php updating this line within the 'authproc.idp' array:

       50 => 'core:AttributeLimit',

to have a much lower priority (higher number):

       999 => 'core:AttributeLimit',

Defining/Mapping NIEF Attributes

It is necessary to map existing attributes into NIEF/GFIPM attributes. While this can be done within the main config, it most naturally should be done within the metadata/saml20-idp-hosted.php file. All attributes are generally managed by including them as parts of the authentication processing defined within the 'authproc' array. The detailed documentation on available attribute manipulation can be found within the simplesaml documentation: [https://simplesamlphp.org/docs/stable/simplesamlphp-authproc].

A few specific examples are included below.

Static Attributes

              // Add GFIPM Static Attributes
               40 => array('class' => 'core:AttributeAdd',
                           'gfipm:2.0:user:IdentityProviderId' => array('NIEF:IDP:PhpTestIdp'),
                           'gfipm:2.0:user:EmployerName' => array('Test Identity Provider'),
                           'gfipm:2.0:user:ElectronicAuthenticationAssuranceLevelCode' => array('NISTLEVEL2'),
                           'gfipm:2.0:user:IdentityProofingAssuranceLevelCode' => array('NISTLEVEL3'),
                           'gfipm:2.0:user:EmployerStateCode' => array('GA'),
                           'gfipm:2.0:user:EmployerOrganizationGeneralCategoryCode' => array('State Government')),

Simple Conversion

               // Convert to GFIPM Attribute Names
               50 => array('class' => 'core:AttributeMap',
                           'email' => array('gfipm:2.0:user:EmailAddressText','NIEF:IDP:PhpTestIdp:USER'),
                           'gfipm28CFR' => 'gfipm:2.0:user:28CFRCertificationIndicator',
                           'cn' => 'gfipm:2.0:user:GivenName',
                           'sn' => 'gfipm:2.0:user:SurName',
                           'gfipmLEO' => 'gfipm:2.0:user:SwornLawEnforcementOfficerIndicator',
                           'gfipmCriminalHistory' => 'gfipm:2.0:user::NCICCertificationIndicator',
                           'gfipmORICode' => 'gfipm:2.0:user:EmployerORI',
                           'telephoneNumber' => 'gfipm:2.0:user:TelephoneNumber'
                           ),

Value Conversion

When a converted attributes value does not align with the NIEF definition's acceptable attribute values, you will need to perform a value conversion. This is all handled via regular expressions, but here are a few simple examples:

               // Convert TRUE -> true, FALSE -> false
               60 => array('class' => 'core:AttributeAlter',
                          'subject' => 'gfipm:2.0:user:28CFRCertificationIndicator',
                          'pattern' => '/FALSE/',
                          'replacement' => 'false'),
               61 => array('class' => 'core:AttributeAlter',
                          'subject' => 'gfipm:2.0:user:28CFRCertificationIndicator',
                          'pattern' => '/TRUE/',
                          'replacement' => 'true'),

Federation Id

The NIEF Federation Id is always constructed from the Identity Provider Id and some sort of local user identifier. Simple SAML comes with a module called SmartId that is convenient for constructing a Federation Id. To this you need to include a call to SmartID within the authproc:

               //smart id stuff
               70 => array(
                       'class' => 'smartattributes:SmartID'
               ),

Then the output of SmartID needs to be mapped to the Federation Id with another authproc (note the number on this step must be higher then the Smart ID number):

               //Create Federation Id from SmartId
               80 => array('class' => 'core:AttributeMap',
                           'smart_id' => 'gfipm:2.0:user:FederationId',),

Additionally, to do this you will need to enable the SmartId module, and add the FederationId syntax as valid for use. To enable the module create an empty file in the module directory named enable. To add FederationId syntax support to the module edit the file modules/smartattributes/lib/Auth/Process/SmartID.php and include an additional line in the array:

               'NIEF:IDP:your-idp-identifier:USER',

Finally, if you look in the example above you will see there is a step where e-mail address is mapped to an attribute with the same name as seen in the previous step. You will need to mimic that for whatever locally unique identifier you choose to use with your FederationId.

Attribute Name Format

Likely you will need to update the attribute NameFormat from unspecified or text to uri when using NIEF attributes. To do so you specify a value for 'attributes.NameFormat' within the metadata/saml20-idp-hosted.php file. Here is a sample:

       'attributes.NameFormat' => 'urn:oasis:names:tc:SAML:2.0:attrname-format:uri',

SAML Metadata / Importing New Entities

Simple SAML comes with a meta refresh module that will greatly simplify managing your trusted partners. To enable this module you will need to create an empty file names enable at this location modules/metarefresh/enable. You will need to copy the config-metarefresh.php file from the modules template folder to the main config directory. Below you will find the configuration for how to trust the NIEF Test Federation, only a few minor tweaks are necessary to trust other federations:

   <?php

   $config = array(
      'sets' => array(

               'gfipm-reffed'     => array(
                       'cron'     => array('hourly'),
                       'sources'  => array(
                               array(
                                       /*
                                        * entityIDs that should be excluded from this src.
                                        */
                                       #'blacklist' => array(
                                       #       'http://some.other.uni/idp',
                                       #),
                                       /*
                                        * Whitelist: only keep these EntityIDs.
                                        */
                                       #'whitelist' => array(
                                       #       'http://some.uni/idp',
                                       #       'http://some.other.uni/idp',
                                       #),
                                       #'conditionalGET' => TRUE,
                                       'src' => 'http://ref.gfipm.net/gfipm-signed-ref-metadata.xml',
                                       'certificates' => array(
                                               'ref-gfipm-ca.crt',
                                       ),
                                       'template' => array(
                                               'tags'  => array('gfipm-reffed'),
                                               'authproc' => array(
                                                       99 => array('class' => 'core:AttributeMap', 'oid2name'),
                                               ),
                                       ),
                               ),
                       ),
                       'expireAfter'           => 60*60*24*4, // Maximum 4 days cache time.
                       'outputDir'     => 'metadata/gfipm-reffed/',
                       /*
                        * Which output format the metadata should be saved as.
                        * Can be 'flatfile' or 'serialize'. 'flatfile' is the default.
                        */
                       'outputFormat' => 'flatfile',
               ),
       ),
   );

SAML Features

Persistent Name Identifiers

Simple SAML PHP requires a 'userid.attribute' to be defined in order to properly generate a persistent name identifier. The best place to define this value is within the metadata/saml20-idp-hosted.php file. You must specify an appropriate local attribute to use. In this example that local attribute is the ldap attribute email, but that may be a different value for your deploy:

       // userid.attribute
       'userid.attribute' => 'email',

SHA-256

Most likely your Simple SAML PHP install is already defaulting to using SHA-256, but if you need to specifically configure this, you would do so within the metadata/saml20-idp-hosted.php file, by specifying the signature algorithm to be SHA-256 like this:

       'signature.algorithm' => 'http://www.w3.org/2001/04/xmldsig-more#rsa-sha256',

Encrypting Assertions

If you wish to encrypt assertions to relying parties you do so by turning on the option assertion.encryption within the metadata/saml20-idp-hosted.php file. For example:

       // Turn on encryption of assertions...
       'assertion.encryption' => TRUE,

Unsolicited SSO (aka IDP Initiated SSO)

TBD - Link to simple saml docs about doing IDP Initiated SSO