simpleSAMLphp is a native PHP application that provides support for a number of authentication protocols/methods. Its origins lie with the SAML protocol, but it also provides support for a range of other authentication protocols (e.g. WS-Federation, OAuth, LDAP, RADIUS). It’s a very capable and robust platform that can run on a number of different web surfaces.

In this post we’ll be covering identity federation scenarios with simpleSAMLphp and our usual incumbent: AD FS, getting the two to play nicely together. We’ll look at both sides of the coin via a:

For SAML integration with AD FS, SSL certificate(s) are required to secure the IIS website(s) and the underlying simpleSAMLphp application(s). This pre-requisite stems from AD FS supporting HTTPS only. In the test configuration described here, the simpleSAMLphp instances are also published behind an AD FS Web Application Proxy (WAP). The pass-through (reverse) proxy functions of the WAP are then used to publish the simpleSAMLphp IdP/SP endpoints. On the IIS side, Server Name Indication (SNI) is also enabled.

(iv)An IIS 8.5 Web server with php loaded as an application. This hosts the simpleSAMLphp Identity Provider (IdP), Service Provider and test applications, under dedicated websites/paths.

The AD DS and AD CS instances provide authentication and the SSL certificates for the IIS web services. On the Web Application Proxy (WAP) a third-party certificate is installed. This goes somewhat against the grain with Microsoft recommendations of using the same certificate pairing on the WAP and AD FS. However, since we’re not using device management/Workplace Join in this scenario, which I believe the requirements stem from, there are no immediate issues.

On our “application server” IIS is installed. Herein, I’ve created four websites (idp1, idp2, site1 and site2), representing two simpleSAMLphp SAML 2.0 identity providers and two simpleSAMLphp service providers. The website configuration can be seen in the below graphic:

In each case the simpleSAMLphp files are unzipped to a folder per function, e.g:

In IIS Manager, we can see the folder structure of an exploded simpleSAMLphp configuration for a single instance.

In each instance, under the configfolder, a baseurlpath setting in the config.php file is set to indicate the root path for simpleSAMLphp content. By default, this is set to www. Should we wish to change this, such that the desired path to our simpleSAMLphp is say https://idp1.mydomain.com/authrather than the default https://idp1.mydomain.com/www, then we make the change to the baseurlpath from ‘www/’ to ‘auth/‘ and rename the www folder accordingly. Note the use of the trailing slash that should always be present in thebaseurlpath value.

From a simpleSAMLphp standpoint, there’s a few tweaking steps required before we get going in our test setup.

By default, a secretsalt setting is configured in the config.php file and it’s strongly recommended to change this. This should be a random string, as the salt is used to generate cryptographically secure hashes.

Also, we should consider getting logging working properly. This will reap dividends later when it comes to troubleshooting. As with other settings so far mentioned, logging settings are defined in config.php.

Firstly, debug is enabled via setting:

‘debug’ => TRUE,

By default, the logging level is set to SYSLOG. Here we’ll also switch the logging level to DEBUGand then alter the handler to file. This is done by setting the following values:

‘logging.level’ => SimpleSAML_Logger::DEBUG,

‘logging.handler’ => ‘file’,

In later sections of the CONFIG.PHPfile, the output filename is also specified. This writes to the log folder of the instance.

‘logging.logfile’ => ‘simpleSAMLphp.log’,

This log file lives under the /log folder of the simpleSAMLphp instance. However, simply specifying the file to use is not sufficient for logging under IIS to work. For that little feat, the IUSR needs to been given modify access to the simpleSAMLphp logfile.

Repeat this process for each instance of simpleSAMLphp running under IIS on your server(s), giving the IUSR account the appropriate permissions.

Once logging has been configured, we can see the benefits of verbose logging as it provides a rich level of detail. Here’s a sample:

Back in IIS, I’ve elected to employ the services of our friend Server Name Indication (SNI). This is defined on the website. Unlike with AD FS, SNI is an option under IIS J

SNI allows us to run multiple web sites under IIS, using different certificates/domain combinations per website, all bound to a shared single IP address. This makes it possible in this test setup to run with numerous instances of simpleSAMLphp, in identity and service provider roles, all on the same server; without having to deal with the hassle of SSL Host Headers, listener changes, tweaking friendly names on certificates etc.

Web server setup itself is pretty straightforward. For simpleSAMLphp instances, either identity or service provider, we prep the web server with the following steps:

create an A record for the URL in AD DNS, e.g. idp1.mydomain.com

create an A record for the URL in Internet/External DNS and point this to the IP address/VIP of the Web Application Proxy.

create a website in IIS for simpleSAMLphp and point the configuration to the baseurlpath, of your choice, e.g. c:\inetpub\wwwroot\idp1\www

add an SSL binding on the website, with Require Server Name Indication (SNI) enabled and a host header matching the URL, e.g. idp1.mydomain.com

publish the new website on the reverse proxy (Web Application Proxy) using a pass-through rule

configure the simpleSAMLphp configuration as described later in the post

repeat for each additional new instance

Web Application Proxy (Optional)

In this lab, we’re using the AD FS Web Application Proxy (WAP) to reverse proxy HTTPS traffic to the various simpleSAMLphp endpoints. The following pass-through proxy rules are created.

Let’s start with simpleSAMLphp in the SAML 2.0 Service provider (SP) role.

For a basic configuration, there are a number of key simpleSAMLphp files we work with. These are:

–config.php

–authsources.php

–saml20-idp-remote.php

In the authentication sources document (authsources.php), various service provider properties are defined. A single authsources.php containing information of all setups can be used and shared across multiple environments, in our case (web1 and web2), or we may elect to store settings separately, using a unique authsources.php per environment .

For expediency, I highlight the use of a common authsources.php. Each authentication module/configuration is represented by its own section in the document.

Here’s an example of two SAML service provider configurations in a test authsources.php:

Notice the different section names (onion1-spand onion2-sp) and use of separate certificate keypairs (web1 and web2) in each section. With the entity ID/identifier set to ‘entityID’ => NULL, simpleSAMLphp will handle the naming for the (RP) identifier of that service provider * and an entity ID is generated based on the metadata URL. In the above config, using web1.mydomain.com and web2.mydomain.com as URLs, this would translate to:

* It’s also perfectly acceptable for you to choose your own identifier in the entityID section, rather than defaulting to NULL.

The IdP section refers to the entity ID (identifier in AD FS terminology) of the IdP that the service provider (SP) should contact. Like the entity ID value of NULL used for the simpleSAMLphp service provider, this can also be set to NULL for the idp value. Where multiple identity providers exist, then the user will be shown a list of available IdPs to select from.

To corroborate the identity of the service provider, we can (optionally) digitally sign requests and a certificate is required to accomplish this. Reference to this cert for a service provider (SP) is made in simpleSAMLphp by the privatekey and certificate setting values in the authsources.php.

By default, simpleSAMLphp uses the same certificate for token signing and encryption. The certificates comprising the private key (.key) and public key (.pem) will reside in a cert folder made off the SimpleSAMLphp base configuration path.

‘privatekey’ => ‘web1.key’,

‘certificate’ => ‘web1.pem’,

In this particular configuration, we’ve elected to enable the SP to sign authentication requests (redirect/post), using the the `redirect.sign` =>TRUE option.

While use of signing and encryption is generally considered an unsightly configuration overhead and an optional, use of token signing comes into play with SAML requirements for Single Logout (SLO) and where service providers request specific functionality. As an identity provider, AD FS does expect SAM 2.0 service providers (simpleSAMLphp) to sign logout requests. With this in mind, we elect to use certificates and logout requests are signed by the SP, specifying ‘sign.logout’ => TRUE.

To satisfy the above requirements, when creating the token signing/encryption certificate(s) for simpleSAMLphp, OpenSSL is used here to generate a certificate using the SHA2 signing algorithm. Here’s an example (2 year validity).

If you’re not up to date on this and as the help text in the configuration files explain, SHA-1 as a signing algorithm is largely being supplanted by use of stronger schemes.

At this point we have the makings of a basic setup authentication-wise. Additionally, simpleSAMLphp needs to be made aware of the AD FS identity provider configuration. This is collected from federation metadata belonging to the AD FS IdP and then stored in the saml20-idp-remote.php file, located in the metadata folder. This file contains configuration details for all remote SAML 2.0 Identity Providers (IdP) known to that service provider.

As we’ll see, the process for pruning metadata and converting it into a simpleSAMLphp friendly format is useable for both service providers and identity providers, thereby applicable for Scenario 2.

Getting the AD FS metadata into a simpleSAMLphp-friendly format is aided by using tools found under the installation page simpleSAMLphp (matching the baseurlpath path). Browsing to the service provider URL, e.g. https://web1.mydomain.com/www shows the simpleSAMLphp installation page.

It’s a good idea to password protect this page. This can be done by editing settings in the config.phpfile. The settings described therein protect the main admin page and the ensuing metadata pages.

‘auth.adminpassword’ => ‘adminpasswordtobeset’,

‘admin.protectindexpage’ => true,

‘admin.protectmetadata’ => false,

In the above, the installation page is protected and metadata left unprotected to allow automated exchange.

The installation pages allow us to perform a number of tests to prepare and configure the installation.

Use the built-in tools to parse federation metadata from identity or service providers, e.g. AD FS, subject to role, using the XML to simpleSAMLphp metadata converter.

Validate the configuration by testing configured authentication sources (applies to both identity and service provider roles) via the authentication tab

Observe federation metadata endpoints configured and exposed simpleSAMLphp (valid for both identity and service provider configurations)

The Federation tab on the installation page provides useful information relating to metadata and tools for assisting in the setup of federation trusts. At the foot of the federation screen, note the XML to simpleSAMLphp metadata converter.

Use this to convert federation metadata from remote sources into a simpleSAMLphp friendly format.

Here the metadata from the AD FS SAML 2.0 Identity Provider (IdP) needs to be converted for consumption by the simpleSAMLphp service provider. Download the metadata from AD FS and save it to a text file. Metadata is reachable at:

Since AD FS is the identity provider in this scenario, then we require Option (b). In the converted metadata section of the page, find the section relating to saml20-idp-remote.phpand copy the text to clipboard. Open the saml20-idp-remote.phpfile found in the metadata folder of the IdP configuration, paste the contents, appending the parsed metadata into this file and save it.

NB: I’ve read on the simpleSAMLphp forums that it’s also possible to save files to the metadata folder and reference these in your configuration directly. I’ve not tested this, but if interested it’s worth checking out the simpleSAMLphp github on how this can be done.

Back at the installation page, the federation tab is also worth checking out. It shows the SAML 2.0 SP metadata endpoint information needed to configure the simpleSAMLphp relying party on the AD FS side. Here’s an example of a shared configuration file (authsources.php) representing multiple service providers.

If the simpleSAMLphp URL is reachable by the AD FS IdP, then automatic exchange of metadata is possible. Where the metadata page is password protected, then file exchange of metadata can be performed.

Here our endpoint is reachable across the “Internet” so we can automatically configure the RP by consuming the metadata of the service provider concerned. We create our relying party and simply take the URL mentioned above, parse it into the wizard and AD FS consumes the remote XML document automatically. Should this not be possible, say where the metadata document is password protected, or policies at the SP state otherwise, we can import the file using the AD FS wizard as mentioned earlier.

In the Issuance Transform rules on the Relying Party (RP), we can mine the claims from AD (as our claims provider), to populate the simpleSAMLphp requirements. In this example we:

–use the Send LDAP attributes as claims rule to send E-Mail Address and sAMaccountName as uid and mail, required by this relying party

–use a transform rule to send a Name Identifier in the transient format

As can be seen from the above graphic, we’re using E-Mail Address and sAMAccountName to use as incoming claims to populate in our outgoingSAML assertion as mail and uid respectively.

Incidentally, when initiating federated logon with the SAML 2.0 protocol, a name identifier is typically used. AD FS as an identity provider, does not send name identifier information in the format expected by simpleSAMLphp. By default, simpleSAMLphp expects a nameid format using the transient identifier (urn:oasis:names:tc:SAML:2.0:nameid-format:transient).

A quick way to get this going, albeit not conforming to SAML specs, is to transform an incoming claim rule, extracted from our AD provider, to populate as an outgoing name identifier.

In the above UI example an incoming UPN claim is transformed into a transient identifier.

Using the claims rule language, the two rules can be expressed as issuance transform rules on the simpleSAMLphp relying party as:

Verifying the RP configuration, we should see both token signing and encryption certificates represented in the appropriate tabs on the relying party, populated among other settings as part of the metadata exchange.

Above, the public key of the token signing certificate, on the Signature tab of the RP.

And on the encryption tab, the public key of the encryption certificate from simpleSAMLphp.

On the Advanced tab, the secure hash algorithm should be set to SHA-256

We’re now good to go for testing the configuration within simpleSAMLphp.

As part of the logon process the appropriate user credentials are posted to AD FS, in this case user mylo. Sent back in the SAML response is also the e-mail address of the user, read from the mail attribute in Active Directory, with a value of nomail@accessonionfor this user. The resultant SAML assertion can be seen in simpleSAMLphp.

Note that the name identifier is not visible on the installation page, although its presence is mandatory.

Click on Logout to check that Single Logout is also functioning and that the two federation partners are configured correctly, signing algorithms are in synch etc.

And we’re logged out, token extinguished/gone.

This is a barebones configuration. Should you wish to employ more expansive configurations, incorporating simpleSAMLphp into the PHP code of your web application (Drupal/Moodle/Joomla etc.), then refer to the simpleSAMLphp website, where there are examples to illustrate this.

Quick note on Name Identifiers

With respect to the earlier comment on the SAML protocol and NameID, when passing a name identifiers of a transient sort, it’s preferable to use an opaque identifier commuted between relying parties that doesn’t reveal the identity of the individual concerned. To get a better insight into this with respect to AD FS and SAML, I’d suggest reading this MSDN article, as it provides examples on how privacy-bearing claims can be used.

If we wish to use an opaque reference, borrowing from the aforementioned article:

Rule 1: generate a session ID value that can be used as a transient identifier. Add this rule to the claims pipeline.

In the identity provider (IdP) capacity, simpleSAMLphp supports a number of authentication methods. These include:

·Local authentication

·Single LDAP/AD

·Multi-LDAP

·RADIUS

·SQL

·OpenID (FB/Twitter etc.)

·Yubikey

That’s quite a diverse set of authentication mechanisms. There are also a number of additional custom modules developed within the community that support even more refined use cases.

We’ll look at a basic setup utilizing local authentication; namely, username/passwords stored in a flat file in the authsources.php file of the simpleSAMLphp IdP. As unglamorous as this might sound, it’s a good starting point for getting a working configuration up and running before mixing it with other more complex setups involving LDAP/RADIUS/SQL etc.

There are a number of files we work with in the identity provider configuration. These are:

–config.php

–authsources.php

–saml20-idp-hosted.php

–saml20-sp-remote.php

On the SAML SP side, AD FS will be using simpleSAMLphp as a claims (identity) provider. We’ll also reuse the simpleSAMLphp SAML 2.0 service provider from Scenario 1 as a relying party (behind AD FS) to illustrate attribute flow.

Here’s the basic logon flow:

1.User browses to the simpleSAMLphp Relying Party.

2.User selects the AD FS authentication source and is redirected to AD FS.

3.Rules logic on the AD FS determines that the user should be directly sent to the simpleSAMLphp claims provider, without showing a realm discovery page.

4.User is redirected to simpleSAMLphp identity provider for logon where they log on as student

5.User logs on with local identity (from authsources.php)

6.User is redirected to AD FS for processing

7.Claims provider rules are evaluated on the AD FS pipeline

8.Relying Party rules are evaluated on the AD FS pipeline

9.User is redirected to the simpleSAMLphp relying party

With all working swimmingly, we’ll end up on the simpleSAMLphp relying party page.

In this logon scenario, we’re using AD FS as Relying Party Security Token Service (RP-STS) in a “headless” capacity. It (AD FS) is not responsible for authentication but must still handle routing of the authentication request to the simpleSAMLphp relying party / test web application.

In a multiple claims provider scenario, when sending requests via AD FS, we would normally be presented with the Home Realm Discovery (HRD) screen.

As can be seen from the above graphic, with AD FS (via AD) enabled as a claims provider, the “Access Onion” claims provider AND the simpleSAMLphp identity provider are both visible as authentication sources. For this scenario we want to exclusively send logon requests to the simpleSAMLphp identity provider, so the (home) realm selection needs to be suppressed for the simpleSAMLphp relying party/test web application. As mentioned in previous “First Look” posts on AD FS 2012 R2, this can be achieved by declaring the claims provider of choice for the relying party to use for logon in PowerShell.

The saml20-idp-hosted.php file in the metadata folder is key for configuring the identity provider. Here’s an example (in bold) calling a local (simpleSAMLphp) authentication method known as example-userpass.

You may recognize common aspects of the configuration from the SP scenario applied previously in the authsources.php. Similarly these can be applied to our identity provider configuration in the saml20-idp-hosted.php file.

The identity provider calls the example-userpass authentication scheme from the saml20-idp-hosted.php file.

The authentication element, expressed as ‘auth’ => ‘example-userpass’, cross-references the appropriate section of the authsources.php file, containing therein a list of users.

‘example-userpass’ => array(

‘exampleauth:UserPass’,

// Give the user an option to save their username for future login attempts

// And when enabled, what should the default be, to save the username or not

//’remember.username.enabled’ => FALSE,

//’remember.username.checked’ => FALSE,

‘student:pa$$st@dent’ => array(

‘uid’ => array(‘student’),

‘mail’ => array(‘student@nomail.com’),

‘eduPersonAffiliation’ => array(‘member’, ‘student’),

),

’employee:3mployEEP&ss’ => array(

‘uid’ => array(’employee’),

‘mail’ => array(’employee@nomail.com’),

‘eduPersonAffiliation’ => array(‘member’, ’employee’),

),

),

There are two test users: student and employee, with attributes uidand mail populated. As with Scenario 1, to build a federation trust with AD FS, information must be gathered via exchange of metadata to make the trust possible. For the simpleSAMLphp identity providers, extrapolated metadata from the remote AD FS service provider is stored in the saml20-sp-remote.php file in the metadata folder. On the AD FS side, we need to create a relying party trust for our test web application. We’ll re-use the service provider/relying party created in Scenario 1.

To populate the identity provider with the relevant information, the AD FS metadata file needs to be imported to the simpleSAMLphp identity provider (IdP) instance.

Open the installation page of the identity provider, e.g. https://idp1.mydomain.com/www, authenticating where necessary, and select the federation tab.

Download the AD FS federation metadata from the metadata endpoint and save it to text file.

Given that our identity provider prefers the transient format, this can be altered using Powershell by specifying the required NameID format. More on this in a moment….

From the identity provider (https://idp1.mydomain.com/www) installation page of simpleSAMLphp, the metadata endpoint information is visible on the federation tab. This corresponds to the Entity ID of the identity provider. This URL is used to configure the claims provider on the AD FS side.

Should the simpleSAMLphp IdP endpoints be visible to support online exchange of metadata with AD FS, then the claims provider can be configured automatically. Where metadata is password protected, or the published path of the endpoint is not reachable (for security reasons), then manual exchange of metadata via file will be necessary.

We now have sufficient information to create the claims provider on the AD FS side. In the Add Claims Provider Trust wizard, the above-mentioned URL is used.

As always I recommend the use of PowerShell over the UI for automating this process. While the initial learning curve/overhead is somewhat higher, it will reduce the margin for human error and also provides documented evidence and a path on how installations/configurations are performed.

Since we are hand-waving authentication to simpleSAMLphp as claims provider, any incoming attributes will need to be processed by AD FS as part of the logon process at both the claims provider and relying party.

Firstly, we’ll override the default AD FS behavior of using SAML 1.1 name identifiers (mail) in favor of the transient identifiers mentioned earlier. To do this the expected name identifier required by the identity provider (simpleSAMLphp) can be stated in PowerShell.

In a completed configuration, if we were to enable debug and analytics on the AD FS server, we can see the claims processed via Event ID 1000 in the AD FS Debug tracing logs. Note the transient name identifier claim type value of _60b434c232f5cc7048fb85d80ea4c8775d38489f90 being passed when logging on using a test (student) user.

Meanwhile, we need to ensure on the relying party/test web application, our simpleSAMLphp relying party from Scenario 1, that the appropriate rules are applied to ensure that claims originating from the issuer (simpleSAMLphp Identity Provider) are evaluated.

The two test users defined in config.php of the identity provider will emit two SAML attributes of interest for AD FS to process (uid and mail):

‘student:studentpass’ => array(

‘uid’ => array(‘student’),

‘mail’ => array(‘student@nomail.com’),

‘eduPersonAffiliation’ => array(‘member’, ‘student’),

),

’employee:employeepass’ => array(

‘uid’ => array(’employee’),

‘mail’ => array(’employee@nomail.com’),

‘eduPersonAffiliation’ => array(‘member’, ’employee’),

To reiterate, we wish to pass identity-specific information originating from a SAML 2.0 identity provider (simpleSAMLphp), via AD FS as a SAML 2.0 Service Provider (RP-STS), to our test SAML 2.0 Service Provider/Relying Party (simpleSAMLphp).

For the relying party, the fact that I’m using simpleSAMLphp (from Scenario 1) is merely for expediency. The application/relying party concerned may well be another application, i.e. a Cloud/SaaS or on-premise offering. However, the attributes mentioned above need to be passed by the identity provider through AD FS to the relying party application. For those not experienced with using claims providers with AD FS, this can sometimes be a little confusing.

In Scenario 1, we created a simpleSAMLphp relying party that surfaced claims from the local Active Directory as the claims provider (identity provider) using the Send LDAP Attributes as Claims claim ruleset. This particular ruleset is not applicable to claims emitted for our simpleSAMLphp claims provider. Let’s look at the custom claims rule again:

Note the reference to AD AUTHORITY. This is specifically targeting the local home Active Directory as the issuer for the claim. When authentication is handled through the simpleSAMLphp identity provider, this rule is ignored.

Our test application (the same one used in Scenario 1) is expecting attributes uidand mail to be passed from AD FS. We could add a single rule that states passing all claims rules to be processed by the relying party, covering the claims from the identity provider described above.

c:[]

=> issue(claim = c);

This satisfies the requirement of passing the name identifier, uid and mail attributes from the simpleSAMLphp identity provider, but it also passes additional information from the AD FS RP-STS to the relying party.

Alternatively, we could define three pass-through rules, expressly bound to the simpleSAMLphp identity provider through the issuer value. Instead of sending all claims values, we only emit claims specific to that identity provider for the attributes concerned on the relying party rules.