Jeff.Krug: Created page with "This page enumerates some configuration methodologies for https://simplesamlphp.org/ Simple SAML PHP when trying to configure for use as a GFIPM/NIEF Identity Provider. =..."

2019-01-22T18:15:06Z

Created page with "This page enumerates some configuration methodologies for https://simplesamlphp.org/ Simple SAML PHP when trying to configure for use as a GFIPM/NIEF Identity Provider. =..."

New page

This page enumerates some configuration methodologies for [[https://simplesamlphp.org/ 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 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:your-idp-identifier'),
'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:your-idp-identifier: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 ==
There are generally two ways to handle trusted updates. One is to enable automation via remotely hosted trusted SAML2 Metadata. The second is to manually update the configuration. Frequently a single deploy will need to do both, as some trusted partners may not have their metadata available remotely in a trusted fashion.

=== Local Metadata ===
Typically in this case you will take the SAML2 Metadata provided by a trusted partner and run it through the Metadata to PHP conversion. This tool is available within the admin interface for Simple SAML PHP. Then you will take the output of this program and add it to the '''metadata/saml20-sp-remote.php'''.

=== Automation via Meta Refresh ===
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',
),
),
);

Additionally you will need to make sure the directory specified in '''outputDir''' is writeable by the process running php/web server. This varies by operating system and web server. You will likely also wish to setup an external program to invoke the meta refresh periodically. Review the simple saml php documentation for more information about this: [[https://simplesamlphp.org/docs/stable/simplesamlphp-automated_metadata https://simplesamlphp.org/docs/stable/simplesamlphp-automated_metadata]]

== 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,

=== Authentication Context Classes ===
Currently Simple SAML's handling of Authentication Context Classes seems relatively basic. It defaults to sending <code>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</code> where as within NIEF and most federated use cases the actual Authentication Context Class should be something else. Most commonly it is still username/password but over a secured channel (TLS/SSL) in which case the correct Authentication Context Class Reference is <code>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</code>. To update your configuration to default to Password Protected Transport add the following to ''''authproc'''' array within '''metadata/saml20-idp-hosted.php''':

85 => array ('class' => 'saml:AuthnContextClassRef',
'AuthnContextClassRef' => 'urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport',
),

== Unsolicited SSO (aka IDP Initiated SSO) ==
You can read about this in section 11 of the Simple SAML PHP basic setup page: [[https://simplesamlphp.org/docs/stable/simplesamlphp-idp#section_11 https://simplesamlphp.org/docs/stable/simplesamlphp-idp#section_11]].

== Troubleshooting ==
1. If you are getting strange redirects related to no sessions being established, it could be related to the temporary folder getting so full the system is unable to engage in proper session management.

Simple SAML PHP - Revision history

Jeff.Krug: Created page with "This page enumerates some configuration methodologies for https://simplesamlphp.org/ Simple SAML PHP when trying to configure for use as a GFIPM/NIEF Identity Provider. =..."