Category Archives: SAML 2.0

Interoperability scenarios with simpleSAMLphp and AD FS


Hello all and Happy New Year!

In this post we’ll look at inter-operability scenarios involving simpleSAMLphp and Active Directory Federation Services (AD FS).

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:

(a)    simpleSAMLphp Service Provider (SP) / AD FS Identity Provider (IdP) pairing.

(b)   simpleSAMLphp Identity Provider (IdP) / AD FS Service Provider (SP) pairing;


In both cases, setup is applicable to both AD FS 2.0 and AD FS 3.0/2012 R2.

For an introduction to simpleSAMLphp, start here.  It runs on a wide variety of web servers (Apache, Nginx, IIS among others).  In these scenarios we’ll use IIS as our web server for deployment.


The latest PHP libraries can be obtained through the IIS Web Platform Installer. In this setup PHP 5.5.x is used and simpleSAMLphp 1.13.x.

The latest binaries for simpleSAMLphp are available via their website (

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. 

The test setup used here comprises four virtual machines:

(i)                  An Active Directory Domain Services (AD DS) and Certificate Services (AD CS) node;

(ii)                An Active Directory Federation Services (AD FS) 2012 R2 Farm node;

(iii)               A Web Application Proxy (WAP) 2012 R2 node;

(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:

·         c:\inetpub\idp1 and c:\inetpub\idp2 for the SAML identity provider (IdP) root paths

·         c:\inetpub\web1 and c:\inetpub\web2 for the SAML server provider (SP) root paths

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


In each instance, under the config folder, 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  rather than the default, 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 the  baseurlpath 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 DEBUG and 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.PHP file, 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:


Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       <Attribute xmlns:a=”; Name=”; a:OriginalIssuer=”CLIENT CONTEXT”>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]         <AttributeValue>172.16.x.6</AttributeValue>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       </Attribute>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       <Attribute xmlns:a=”; Name=”; a:OriginalIssuer=”CLIENT CONTEXT”>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]         <AttributeValue>212.x.y.5</AttributeValue>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       </Attribute>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       <Attribute xmlns:a=”; Name=”; a:OriginalIssuer=”CLIENT CONTEXT”>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]         <AttributeValue xmlns:tn=”; xmlns:b=”; b:type=”tn:boolean”>false</AttributeValue>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       </Attribute>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       <Attribute xmlns:a=”; Name=”; a:OriginalIssuer=”CLIENT CONTEXT”>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]         <AttributeValue>/adfs/ls/</AttributeValue>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       </Attribute>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       <Attribute xmlns:a=”; Name=”; a:OriginalIssuer=”CLIENT CONTEXT”>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]         <AttributeValue>Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 6.3; WOW64; Trident/7.0; Touch; .NET4.0E; .NET4.0C; .NET CLR 3.5.30729; .NET CLR 2.0.50727; .NET CLR 3.0.30729; Tablet PC 2.0; InfoPath.3; MASEJS)</AttributeValue>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       </Attribute>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       <Attribute xmlns:a=”; Name=”uid” NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:basic” a:OriginalIssuer=””&gt;

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]         <AttributeValue>student</AttributeValue>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]       </Attribute>

Sep 19 17:30:19 simpleSAMLphp DEBUG [5805446797]     </AttributeStatement>


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:

    1. create an A record for the URL in AD DNS, e.g.
    2. create an A record for the URL in Internet/External  DNS and point this to the IP address/VIP of the Web Application Proxy.
    3. create a website in IIS for simpleSAMLphp and point the configuration to the baseurlpath, of your choice, e.g. c:\inetpub\wwwroot\idp1\www
    4. add an SSL binding on the website, with Require Server Name Indication (SNI) enabled and a host header matching the URL, e.g.
    5. publish the new website on the reverse proxy (Web Application Proxy) using a pass-through rule
    6. configure the simpleSAMLphp configuration as described later in the post
    7. 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.


External URL

Backend Server URL











No name/URL translation is performed. Servers idp1 and idp2 are SAML 2.0 identity providers, whilst web1 and web2 are SAML 2.0 service providers.

For integration testing with AD FS, we’ll run through the following scenarios:

1.       configuring AD FS as an Identity Provider and simpleSAMLphp as a service provider

2.       configuring simpleSAMLphp as an Identity Provider and AD FS as a service provider


Scenario 1 – AD FS Identity Provider (IdP) and simpleSAMLphp Service Provider (SP)

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:




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:


‘onion1-sp’ => array(



              ‘entityID’ => NULL,

‘idp’ => NULL,

              ‘discoURL’ => NULL,


              ‘redirect.sign’ => TRUE,

              ‘assertion.encryption’ => TRUE,

              ‘sign.logout’ => TRUE,

              ‘privatekey’ => ‘web1.key’,

              ‘certificate’ => ‘web1.pem’,




       ‘attributes’ => array(




       ‘signature.algorithm’ => ‘;,





‘onion2-sp’ => array(



‘entityID’ => NULL,

              ‘idp’ => NULL,

              ‘discoURL’ => NULL,


              ‘redirect.sign’ => TRUE,

              ‘assertion.encryption’ => TRUE,

              ‘sign.logout’ => TRUE,

              ‘privatekey’ => ‘web2.key’,

              ‘certificate’ => ‘web2.pem’,



       ‘attributes’ => array(




       ‘signature.algorithm’ => ‘;,





Notice the different section names (onion1-sp and 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 and 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).

openssl req -x509 -nodes -sha256 -days 730 -newkey rsa:2048 -keyout my.key -out my.pem


If we’re not satisfied with simply signing tokens, then we can also require the content of the token to be encrypted, by requesting encryption using ‘assertion.encryption’ => TRUE.


Our SP is expecting that the AD FS identity provider will provide the attributes uid and mail attributes in the SAML response, as expressed by:


‘attributes’ => array(





A SHA2 (SHA256) algorithm is used to sign messages generated by the service provider. 


‘signature.algorithm’ => ‘;


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. 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.php file. 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.

    1. Review the simpleSAMLphp configuration, installed/enabled modules, PHP versions etc.
    2. 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.
    3. Validate the configuration by testing configured authentication sources (applies to both identity and service provider roles) via the authentication tab
    4. 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:

https://<YOUR FEDERATION SERVICE URL/FederationMetadata/2007-06/FederationMetadata.xml

Open the file in Notepad, copy the contents to the Metadata parser in the browser and then click on the Parse button. This will convert metadata into two formats:

(a)    saml20-sp-remote.php used where AD FS is a remote SAML 2.0 Service Provider

(b)   saml20-idp-remote.php used where AD FS is a remote SAML 2.0 Identity Provider

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.php and copy the text to clipboard. Open the saml20-idp-remote.php file 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.

Let’s jump to AD FS now. We’ll add the SP instance, utilizing the “default-sp” label as our SAML 2.0  relying party of interest.


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:

c:[Type == “;, Issuer == “AD AUTHORITY”]

 => issue(store = “Active Directory”, types = (“mail”, “uid”), query = “;mail,sAMAccountName;{0}”, param = c.Value);


c:[Type == “”%5D

 => issue(Type = “;, Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties[“”%5D = “urn:oasis:names:tc:SAML:2.0:nameid-format:transient”);


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.

Here I select the Test configured authentication sources on the authentication tab.



Then choose to test the default-sp configuration.


If the idp value for the service provider in authsources.php is set to NULL, then a drop-down list of identity providers will  be presented (otherwise we’re routed automatically to AD FS)

Here’s an example of a drop-down dialog with the Access Onion identity provider selection.


This particular identity provider is running AD FS 3.0/2012 R2. Connecting from the Internet, we’re routed to the Access Onion AD FS instance (behind the Web Application Proxy) and presented with a logon form.


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@accessonion  for 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.

c1:[Type == “”] && c2: [Type == “”]=> add (store = “_OpaqueIdStore”, types = (“”), query = “{0};{1};{2};{3};{4}”, param = “useEntropy”, param = c1.Value, param = c1.OriginalIssuer, param = “”, param = c2.Value);

Rule 2:  Using the previously generated session ID, map this to the outgoing claim type  as Name ID using the transient identifier and issue the claim.

c:[Type == ””] => issue(Type=””, Issuer = c.Issuer, OriginalUser = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties[“”]=”urn:oasis:names:tc:SAML2.0:nameid-format:transient”);

Now let’s look at a sample scenario where AD FS is the SAML 2.0 Servicer Provider (SP) and simpleSAMLphp is the SAML 2.0 Identity Provider (IdP)

Scenario 2 – simpleSAMLphp Identity Provider (IdP) and AD FS Service Provider (SP)

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:





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.

Set-AdfsRelyingPartyTrust -TargetName “My Relying Party” -ClaimsProviderName @(“SimpleSAMLphp”)

This effectively takes the Access Onion Active Directory out of the mix for logon.

Back to simpleSAMLphp, we begin by enabling the SAML 2.0 identity provider functionality in config\config.php for our identity provider ( instance.

‘enable.saml20-idp’ => true,

Assigning true to this option enables the SAML 2.0 Identity Provider capability in this instance.

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.


$metadata[‘__DYNAMIC:1__’] = array(

    ‘host’ => ‘__DEFAULT__’,

    ‘privatekey’ => ‘idp1.key’,

    ‘certificate’ => ‘idp1.pem’,

    ‘auth’ => ‘example-userpass’,

    ‘signature.algorithm’ => ‘;,

    ‘authproc’ => array(1 => array(‘class’ => ‘saml:TransientNameID’,),),


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(


      // 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(‘’),

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


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

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

             ‘mail’ => array(’’),

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




There are two test users: student and employee, with attributes uid and 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., authenticating where necessary, and select the federation tab.  

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

https://<YOUR FEDERATION SERVICE URL/FederationMetadata/2007-06/FederationMetadata.xml

Open the AD FS metadata file in Notepad, copy the content to the clipboard and then launch the XML to simpleSAMLphp metadata converter on the federation tab.


Paste the contents to the Metadata parser form in the browser and then click on the Parse button.


Scroll down to the saml20-sp-remote.php section of the web page


Copy this section of text to clipboard.


In the identity provider configuration, open the saml20-sp-remote.php file found in the metadata folder and append the parsed metadata held in clipboard to this file. Save the file.

As a SAML service provider, during passive SSO logons, AD FS makes use of a default name identifier of emailaddress. This can be seen from the metadata screenshot (circled in green):

‘NameIDFormat’ => ‘urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress’,


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 ( 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.


Set-AdfsClaimsProviderTrust -TargetName “simpleSAMLphp Identity Provider” -RequiredNameIDFormat “urn:oasis:names:tc:SAML:2.0:nameid-format:transient”


The following SAML attributes, expressed as claims rules on the claims provider handler, are defined:


1.       Transient Name identifier

c:[Type == “;, Properties[“”%5D == “urn:oasis:names:tc:SAML:2.0:nameid-format:transient”]

 => issue(claim = c);

2.       uid

c:[Type == “uid”]

 => issue(claim = c);

3.       mail

c:[Type == “mail”]

 => issue(claim = c);


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.


ClaimType Value _60b434c232f5cc7048fb85d80ea4c8775d38489f90 ValueType Issuer OriginalIssuer Property[] urn:oasis:names:tc:SAML:2.0:nameid-format:transient Property[] ClaimType uid Value student ValueType Issuer OriginalIssuer Property[] urn:oasis:names:tc:SAML:2.0:attrname-format:basic ClaimType mail Value ValueType Issuer OriginalIssuer Property[] urn:oasis:names:tc:SAML:2.0:attrname-format:basic ClaimType eduPersonAffiliation Value member ValueType Issuer OriginalIssuer Property[] urn:oasis:names:tc:SAML:2.0:attrname-format:basic Value student Property[] urn:oasis:names:tc:SAML:2.0:attrname-format:basic 


Wonderful J


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(‘’),

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


      ’employee:employeepass’ => array(

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

             ‘mail’ => array(’’),

              ‘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:

c:[Type == “;, Issuer == “AD AUTHORITY”]

 => issue(store = “Active Directory”, types = (“mail”, “uid”), query = “;mail,sAMAccountName;{0}”, param = c.Value);


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 uid and 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.


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


Note the additional claims such as client IP, forwarded (NAT) client IP, user agent etc.

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.

1.       Name Identifier

c:[Type == “;, Properties[“”%5D == “urn:oasis:names:tc:SAML:2.0:nameid-format:transient”, Issuer == “”%5D => issue(claim = c);

2.       uid

c:[Type == “uid”, Issuer == “”%5D

 => issue(claim = c);

3.       mail

c:[Type == “mail”, Issuer == “”%5D

=> issue(claim = c);

Here we see the difference from the simpleSAMLphp relying party/web application in terms of claims/attributes emitted in the SAML response.


OK.. that’s it for this post. Feel free to post questions and and I’ll get back to you as soon as possible.

As ever: test, play and test a little more Smile



Step-up Authentication Scenarios with AD FS 2.0 Part II

With the R2 preview of AD FS in Windows Server 2012 out and the large number of changes that are taking place in the new release, I’m going to be bring this post to a quick end; more an abridged version than was originally intended.

In Part I we looked at weaker authentication schemes for step-up scenarios. In Part II, we move onto two-factor/multi-factor authentication (2FA/MFA) use cases.

There’s no real guided approach for doing this in AD FS 2.0, with solutions invariably becoming customized ones, according to the desired use case.  Whether AD FS is the authentication provider or occupying a hybrid/broker role, the use of authentication contexts, types and URIs provided by the supported SAML and WS-Federation protocols, become triggers for step-up.  Where a context is stipulated, in protocol terms, each is interpreted differently.

SAML supported authentication methods

Authentication Method Authentication Context Class URI
Username/Password urn:oasis:names:tc:SAML:2.0:ac:classes:Password
Password Protected Transport urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
Transport Layer Security (TLS) Client urn:oasis:names:tc:SAML:2.0:ac:classes:TLSClient
X.509 Certificate urn:oasis:names:tc:SAML:2.0:ac:classes:X509
Integrated Windows Authentication urn:federation:authentication:windows
Kerberos urn:oasis:names:tc:SAML:2.0:classes:Kerberos

As we saw in the previous post, forcing authentication in SAML logon scenarios provides support for step-up, but at the expense of single sign-on. In passive federation scenarios, if we don’t specify an authentication method in the request, AD FS will apply authentication according to its own supported methods, attempting to match those against the local authentication types section of the web.config on the AD FS node.

AD FS handles the SAML authentication in order of strength, lowest to highest, from top to bottom  as seen in the table: in the default configuration Kerberos is seen as the strongest method. The precedence of the authentication method can be adjusted using the Set-ADFSProperties –AuthenticationContextOrder command to ensure the order meets the requirement we need. The SAML comparison attribute can be used to also influence the authentication method chosen. with AD FS defaulting to a comparison=exact attribute.. As stated in the MSDN article Authentication Handler Overview, if the comparison attribute is set to “better”, “minimum”, or “maximum”, the method of authentication must be stronger than, at least as strong as, or no stronger than one of the specified authentication classes.  This gives us some latitude for using it to invoke the desired authentication method through customization of the sign-in process. With SAML the authentication reference is encoded in the SAML request, and to access and to use the information therein, in order to relay the authentication request to our third-party IdP,  we need to customize our sign-in process  so that the incoming SAML (AuthnContextClassRef) request is decoded. The information we then need needs to be extrapolated so that we can then make the correct routing decision, sending the client to the correct provider. Examples provided on Codeplex hint at how this can be done, by assigning a authentication methods to a relying party using FBA and IWA.

On the other side, let’s look at an example using a WS-Federation based setup.

WS-Federation Passive Profile supported authentication methods

Authentication Method Authentication Context (wauth) URI
Username/Password urn:oasis:tc:SAML:1.0:am:password
Transport Layer Security (TLS) Client urn:ietf:rfc:2246
Integrated Windows Authentication urn:federation:authentication:windows

With the WS-Federation passive requester profile, the authentication type (wauth) parameter is specified in the query string of the browser or can be specified from the relying party application itself. The whr parameter is used to indicate the claims provide to use for logon.

    MFA Step-Up Scenario

    Let’s look at a step-up scenario using WS-Federation with an MFA provider.


    In the above graphic, we have a third-party MFA provider handling the authentication requests for internal access.. I’ve not included the AD FS Proxy for external access, but should we wish to do so,  we could adopt our AD FS proxy configuration and:

    – remove the local authentication handlers from the <localAuthenticationTypes> section  of web.config to ensure that MFA is always used in external access scenarios;

    – follow the same methods used for internal authentication described below;

    Internal access step-up scenarios imply the use of the default Integrated Windows Authentication (IWA) handler and the step-up mechanism. With a third-party multi-factor authentication provider, the (MFA) solution is configured within AD FS 2.0 as a claims provider.  I’ll use the example of the WIF-based STS from PointSharp which I mentioned in previous posts.

    In a step-up context, the STS needs to be able to process the required authentication request and pass this back to AD FS and the RP.   With WS-Federation we can do this via the browser as a query string, or, from the web application make use of the wauth and whr parameters to set the authentication method. 

    Step-Up at the Relying Party Application

    Using the WIF 3.5 SDK samples for our relying party, we modify the web.config to specify the desired authentication type.   I’ve chosen the X509 certificate handler. For our WIF application this corresponds to an authentication method value of urn:ietf:rfc:2246

      <wsFederation passiveRedirectEnabled="true" issuer= realm= requireHttps="true" authenticationType="urn:ietf:rfc:2246"
      homeRealm= <cookieHandler requireSsl="true" />

The homeRealm value is used to specify the claims provider we want to call for step-up, otherwise AD FS itself will attempt to handle the logon, treating as an authentication request for an x509 certificate.

On AD FS we configure the IP-STS as a claims provider.


On the IP-STS, we configure AD FS as a relying party


For convenience, both the STS and AD FS are sharing the same identity store (AD) and I’ve created a test user called demo in Active Directory and a security group called OTP, whom our user is a member of. We’ll use membership of that group on the PointSharp STS as a means of emitting an authentication method claim that corresponds to the expected authentication type. The claims value, urn:ietf:rfc:2246, is returned when a user logs on using MFA (e.g. OTP+password).

The user demo points their browser to the RP URL and with the web.config modifications, the access request is redirected to AD FS and then to the PointSharp STS as the Windows home realm (whr).

On the PointSharp STS during logon, the back-end PointSharp ID services handles the MFA logon request.  At the initial prompt, the user enters their user ID and AD password:


They’re challenged to enter an OTP response (hardware/software token or SMS)


Once authenticated, the STS then processes the matching claims rules.


Above, demo is a member of the group OTP, as seen in the claims rule pattern, so a claims type of  http://schemas/ is generated. This is used to match the expected reply of the RP with a value urn:ietf:rfc:2246. and this claims is then passed back to AD FS.

In our test web app we see the appropriate authentication method and values being returned. No claims rules on the claims provider or relying parties (at this point) have been done.


Our MFA provider may also support multiple authentication types (AD password, SMS, tokens etc), so the fact that we logon at the STS is not necessarily indicative of a sufficient logon.With  AD FS as the RP-STS, we can also block requests that don’t emit the correct authentication method at the STS on the relying party claims pipeline.

c:[Type == "", Value =~ "^(?i)http://schemas\.microsoft\.com/ws/2008/06/identity/authenticationmethod/tlsclient$"]
=> issue(Type = "", Value = "PermitUsersWithClaim");


With the authorization rule in place, another user, demo2, that is not a member of the OTP group, when accessing the RP,  logs on at the PointSharp STS, but gets the following error at AD FS:


This translates in the event log to an access denied message:

The Federation Service could  not authorize token issuance for caller ”. The caller is not authorized to request a token for the relying party ‘https://rp……..’. Please see event 501 with the same instance id for caller identity.


While we can block in this fashion, it makes more sense to enforce and evaluate a more fine-grained access at the application itself. If the app is intended as an internal-only application though, we can also block access from the AD FS proxy via an access rule.

exists([Type == "”]) => issue(Type = “”, Value = “true”);

Step-Up within the Application

The previous steps described step-up at the web application (relying party), rather than within the application itself. The WIF 3.5/4.0 SDK provides samples for step-up authentication using an example of a low-value and a high-value resource within a given application. Here we’re leveraging step-up against a particular resource within an application.


Low-value resources are protected using normal Windows logon credentials (IWA), whereas high-level resources trigger step-up through the use of the certificate handler.


This allows us to add in step-up authentication within the application itself, according to the value of the resource.

A note on Virtual Smart Cards

I mentioned in the last post about virtual smart cards (or VSCs).  As an authentication provider, they are available during Windows logon as a credential provider. Given that we wish to expressly enforce step-up at the application, then some sort of adjustment is equired.  It may be possible to suppress the use of the VSC as a credential provider and make it available post-logon for application-only access, something that I’ve not tried, but one could argue that this is a case of the tail wagging the dog. We could also use an alternate account as described in Part I or disable single sign-on in the web.config on the AD FS farm to enforce logon between relying parties. The fact that we’re using IWA for normal logon masks somewhat the behaviour of revisiting the AD FS server when switching between IWA-based relying parties.

As ever, please extensively test before considering doing this sort of thing in a production environment.


What’s been discussed so far relates to solutions that are on the “direct” authentication path from an identity federation standpoint. There are also MFA solutions that involve indirect authentication using multi-factor authentication. When I refer to Indirect MFA, Í mean some other component outside of the federation logon process that handles the strong authentication aspects of logon. Diagrams always help to illustrate the cause Smile…  

      1. Via a non-federation capable proxy or gateway component. This component does not integrate with AD FS, but can provide an MFA capability. All connections to the RP are through the proxy. Post-logon, the proxy does some form of credential delegation to the back-end AD FS service. Here’s an example of a logon scenario with Forefront UAG 2010 on a non-federated trunk. While UAG does support federated trunks (as a relying party), MFA on a federated trunk is not (to my knowledge) possible unless we use an upstream claims provider.


      2.  Via an MFA web agent running on the ADFS proxy as an ISAPI filter or module. This follows the traditional web access management approach of logon via a web agent, with the filter intercepting the call.  The user must logon using the stronger form of authentication before the web application, in this case the AD FS proxy pages are exposed. While functionally “integrated”, the two operate technologically independent of one another.


        3. Via customization of the AD FS sign-in pages, allowing authentication to a MFA provider through web services. Of the three, this is (in my mind) is the most technically plausible, but handling step-up in such cases would also be complex and I’ll refer to that in a moment.


          None of the above mechanisms are particularly well suited to step-up because the MFA logon process wraps around normal AD FS logon process, rather than integrating with it. While they may be valid in other access scenarios, i.e. the logon request is intercepted by a handler that doesn’t understand federated logon.

          Option 3 is interesting as, via a slight modification, it supports illustrating where MFA is going in the next release of AD FS in Windows Server 2012 R2.

          Windows Server 2012 R2


            In AD FS R2, Microsoft are making available an MFA API for vendors to plug-in to and integrate with the federation service directly, allowing for a more rich logon experience. This also extends the concept of using multi-factor authentication not only at a protocol and application level, but at a policy level too, whereby policy per relying party for authentication is achievable. It also suggests that the redirect method via claims providers is being eschewed by Microsoft in favour of a more AD FS centric approach. I suspect the aim here is to provide a more level playing field for integrating external authentication providers with AD FS rather than placing the burden on the vendor and heavy use of customization to support scenarios described..

            What this means for step-up scenarios we shall see. I’ll be looking at this raft of new features with AD FS R2 in future posts.

          Step-Up Authentication Scenarios with AD FS 2.0 Part I

          This post refers to additional logon schemes that can be supported in AD FS by forcing users to re-authenticate or step-up/step-down authentication to federated web applications. It was prompted by a  recent request from a customer :

          “We wish to connect a SAML 2.0 Service Provider (SP) to AD FS. For security reasons,  we require our internal users to logon (again) when connecting to this web application. All users connecting through the AD FS proxy should be prohibited access.”

          Whether we choose to call this process re-authentication or step-up authentication really depends on the access case.  To meet the requirement, we’ll be breaking single sign-on (SSO) when accessing the web application above by sending parameterised requests from the web application to AD FS, specifying how to handle authentication uniquely for this app.

          Some folks may have pre-conceived ideas about what constitutes step-up, perhaps because it is often associated with multi-factor authentication. While the two do complement one another nicely, step-up is not necessarily multi-factor.  Rather, use of step-up as an access mechanism, is governed by the strength of authentication we wish to accrue to access, at a level commensurate with requirements for protecting that resource. We can use weaker (single factor) authentication where this is deemed sufficient or appropriate.  As an example, a customer may employ two-factor authentication on the outside/edge for all users and then elect to use the AD password, as an additional step-up mechanism for corporate users only to gain access to internal resources.  In authentication strength terms, this is step-down authentication, but in functional terms, it’s designed as a step-up method.

          I make the above point, because in the examples described here, we have users logging onto their workstations either using weak (username/password) or strong (two-factor) authenticating against other federated web applications with these credentials.  In each case, we plan on forcing users to logon again when they access this particular SAML 2.0 web application to “step-up” security.

          This is an internal only access scenario for the enterprise, meaning that users connecting via the AD FS Proxy should be denied access. Since AD FS Rollup 1, we’ve been able to specify Issuance Authorization Rule on the relying party (SAML 2.0 SP) pipeline that allows requests sourced from the AD FS Proxy to be identified and acted on via the claim description:

          Accordingly, we’ll create a deny Issuance Authorization Rule on our SAML web application so that users connecting through the proxy will be blocked.

          exists([Type == “”]) => issue(Type = “”, Value = “true”);

          Sample Scenario

          In a default AD FS farm setup, a domain-joined Windows machine internal user connects to the AD FS farm and authenticates via the Integrated Windows Authentication (IWA) handler using Kerberos/NTLM.  To alter this behaviour, for a given application, and force the user to re-authenticate, we must ignore the existing session cookie.

          With WS-Federation, we can do this at AD FS, via a smart link, by specifying the wauth parameter:


          For a relying party using the WS-Federation Passive Requester Profile (WS-PRP) we can also specify the request in the query string or within application code also via wauth.

          This is a SAML 2.0-based use case though. As a backgrounder, I suggest reading about SAML Authentication Context Classes and Strengths with AD FS. Within the SAML 2.0 protocol, SAML service provider (SP) can emits certain values in the SAML request that ensures that the required authentication method from the SP is honoured by AD FS. From an SAML 2.0 protocol standpoint, this may be accomplished by:

          1. Setting an Authentication Context Class Reference (AuthnContextClassRef) in the requested authentication context from the Service Provider;
          2. Specifying the use of Force Authentication (ForceAuthn) in the request set to a value of true;
          3. Use of a Comparison rule that is set to exact to expressly set the authentication method. Other settings are also possible (which AD FS supports) but are not covered in this post.

          Let’s look at the farm-connected conventions mentioned above in a bit more detail.

          Authentication Context Class Reference

          In Windows SSO logon scenarios, the AD FS integrated handler uses the SAML  AuthnContextClassRef of urn:federation:authentication:windows. On our SAML 2.0 web application, we’ll request a authentication context class reference of urn:oasis:names:tc:SAML:2.0:ac:classes:Password, so that the forms handler (in AD FS) is targeted as the desired authentication handler.

          Force Authentication

          The specification of ForceAuthn=true in the initial SAML request from the service provider specifies that the Identity Provider (IdP) should force re-authentication of the user, even if they possess a valid session with AD FS.

          Comparison Rule

          The SAML 2.0 protocol supports the use of a comparison rule to determine the level of precision to be accorded to the authentication request. If none is specified, AD FS will assume that the attribute is set to exact, meaning that authentication should conform exactly to the AuthnContextClassRef request and is passed to the appropriate handler.

          Configuring Service Providers

          I’ve used two examples here:

          • OpenAM
          • SimpleSAMLphp

          I also planned on including Shibboleth, but hosed my configuration in the process, by reverting the wrong Snapshot of my VM during testing.. *cough*… sorry about that Smile 


          Using OpenAM as a SAML SP example, we’ll invoke SP-initiated sign-on through the spSSOInit.jsp page.  In the query string we’re specifying the authentication context and the desired force authentication.

 &ForceAuthn=true&AuthnContextClassRef=urn:oasis:names:tc:SAML:2.0:ac:classes:Password &idpEntityID=

          Note: The above syntax is valid but watch out for white spaces in the example above, not to mention your own domain name.  I’ve added spaces to make the text more legible.

          AD FS will parse the request based on the emboldened items in the query string and ask the user to re-authenticate via forms sign-in.


          In SimpleSAMLphp, we can set the necessary settings in the configuration file authsources.php, specifying the authentication context and force authentication requirement.

          ‘ForceAuthn’ => TRUE,
          ‘AuthnContextClassRef’ => ‘urn:oasis:names:tc:SAML:2.0:ac:classes:Password’,

          Authentication Options

          How we choose to implement our step-up/re-authentication component depends on the question of sufficiency and what is an acceptable method to choose.  For this exercise, this could mean:

          1. re-using the Windows logon identity (re-authenticate);
          2. using an alternate identity from within the same AD forest (step-up);
          3. using an alternate identity residing in a connected forest (step-up);
          4. using an alternate authentication service; a third-party application that provides stronger forms of authentication

          Option 1 – Re-Authentication

          The  simplest option  sees the the user replaying their AD credentials, logging on again via the AD FS form, before gaining access to the web application. This is clearly not step-up and doesn’t afford any significant additional protection, , but may fulfil compliance/auditing requirements for access.

          Advantages Disadvantages
          Simple (uses same identity) Re-authentication not step-up authentication (same password policy)
          Protects against inadvertent access to the application if the user is already logged on (e.g. where user fails to lock OS)

          Security gain is nominal. Requires claims authorization rules on the relying party to differentiate between valid/invalid users.

          Option 2 – Step-Up Same Forest (username/password)

          Option 2 uses another set of credentials held within the same AD FS forest. Access to the SaaS application is limited to those users using these credentials (i.e. their “step-up” identity) and an authorization rule to supplement this.



          Advantages Disadvantages
          Authentication is stepped using another identity besides the corporate logon More complex. Requires additional identity to represent users (user management)
          Supports use of stronger password policies on the second identity

          Security gain is moderate.  Same factor (username / password) for step-up identity

            Less user friendly (extra identity)
            Shared authentication sources between identities (no isolation)

          Option 3 – Step-Up Connected Forest (username/password)

          A more complex rendition of this using multiple forests with a single AD FS instance (Option 3):image

          In the above setup we have an account forest for our corporate users and a resource forest, where the AD FS server lives (with the AD FS application pool account running in the account forest). A one way forest trust between the two exists. In this option, the step-up identities reside in the resource forest.

          Advantages Disadvantages
          Authentication is stepped using another identity besides the current logon

          More complex. Requires additional identity / shadow account represented in the  remote forest  (user management)

          Supports use of stronger password policies on the alternate identity

          Security gain is moderate. Same factor (username/ password)  for step-up identity

          Shadow account can use same sAMAccountName in remote forest Less user friendly (extra identity)
          Greater isolation / independence of action from account forest (supports selective authentication) More complex to manage

          For Options 2 and 3, we can also provide further refinement by using AD fine-grained password policies to implement a stronger password policy / account lockout policy applicable to our web application, that exceeds the ordinary password policy levels used for for corporate AD users.

          In all above cases, we should consider further restraining access by passing custom claims on the relying party, to assist in determining whether the user in question should have access.

          From an AD FS standpoint, there are no configuration changes required in the cases described thus far.  You may note, however, that I’ve not yet mentioned IdP-Initiated Sign-On methods. SHAME! Well, there’s a couple of reasons for this, by which I’ll conveniently recuse myself Smile with tongue out 

          1. Firstly, there a nice solution posted on CodePlex, that works similar to the actions described in this post, albeit by customizing the AD FS sign-in pages instead. It allows assigning the use of forms logon logic to relying parties and also covers IdP-Initiated Sign-On and WS-Federation.    Relying parties registered to use the forms logon are registered in AD FS web.config file, thereby bound to the forms handler.
          2. Also, some customers may be unwilling to modify their default AD FS setup because of a fear that it will throw them outside the realms of Microsoft support. However, if you do wish to support IdP-Initiated sign-on scenarios using the methods above (AuthnContextClassRef and ForceAuthn),  then I’m afraid you don’t have much choice as customization of the  code-behind page for  idpinitiatedsignon.aspx.cs is required. Without these changes, sign-on, either via  logintoRP or relaystate  query parameters, will fail as the desired authentication context (AuthnContextClassRef) has not been set and is not passed by the IdP to the service provider. I used the following MSDN article as a reference to customize the  idpinitiatedsignon.aspx.cs and then tested this using logintoRP parameter, with the query string example below.


          In Part II, we’ll look at step-up options with stronger / multi-factor authentication methods (aka Option 4). See ya!

          Release Notes for AD FS 2.0 RU3 updated

          Working with a customer recently, we ran into problems with RU3 and the sharing of SAML signing certificates between RPs in their test environment. After applying RU3, as mentioned in the previous post, additional manual actions are required. However, it turns out, following a nice long troubleshooting call with those lovely folks at support, that there are is more to this tale:

          1. The PostReleaseSchemaChanges.ps1 script applies only to AD FS Windows Internal Database (WID) configurations. The script is provided with the RU3 update under the SQL sub-folder.

          2. AD FS SQL database configurations need to run a script locally on a SQL Server node. This file is known as RelaxedRequestSigningCertsv2.sql  and is available via a newly updated article on the support site (KB 2790338) or directly via the following link:

          The updated release notes for RU3 can be found here:

          Please read, share and alert your fellow AD FS brethren Smile

          SAML 2.0 IdP-Initiated Sign-On with RelayState in ADFS 2.0

          Ýet another riveting title Smile Dispensing with WS-Federation, we’ll move onto looking at SAML 2.0 integration with AD FS, in particular IdP-Initiated sign-on. In the last few posts we’ve looked at how AD FS 2.0 admins can manipulate the use of the whr function to assist in the realm discovery process as part of sign-in to AD FS using WS-Federation. With AD FS 2.0 and SAML 2.0, a long-awaited feature has been support for SAML 2.0 RelayState. With Rollup 2, the AD FS team have come up with the goods. Like whr on the WS-Federation side, the use of RelayState allows us to support IdP-Initiated login from a SAML 2.0 identity provider (IdP).

          Before we look at some examples, here’s a few useful tools to aid building and debugging the use of RelayState.

          1. The excellent SAML Tracer plugin for Firefox (

          2. A relay state generator for AD FS 2.0 to aid us in building the necessary call-back to AD FS. (

          3. A URL Encoder/Decoder to validate the syntax used for constructing the Relaystate query string. I used this one..

          To get started, there’s a nice article on the Directory Services blog at Microsoft, as a backgrounder to understanding what’s going on via Rollup 2 and RelayState.

          Let’s have a look at how these scenarios may pan out. Putting my rudimentary skills in Visio 2013 to the test, here are three examples:


          EXAMPLE 1: Remote SAML 2.0 Identity Provider

          In the above example, our user needs to connect, via the Internet, to a remote web application that is configured as a SAML 2.0 Service Provider. This service provider is engaged in a federation trust with AD FS. AD FS as a Relying Party Security Token Service (RP-STS) has the SAML 2.0 Identity Provider (IdP), in the home realm of the user, configured as a claims provider (CP).


          EXAMPLE 2 : Remote SAML 2.0 Identity Provider and Service Provider

          In the above scenario, both the service provider (SP) and the identity provider (IdP) are remote to the organization. This could be a cloud / SaaS application that the RP-STS organization provides access to to both its users and the remote identity provider organization.


          EXAMPLE 3 : Remote SAML 2.0 Service Provider

          In the above example, the Identity Provider (IdP) and AD FS are part of the same organization.  The IdP could be an Access Management platform such as OpenAM, a remote access gateway such as a Juniper SA, or an Extranet ADFS instance with the AD FS RP-STS acting as a broker.

          Access Scenario

          Let’s look at some of the pre-requisites on the AD FS side:

          1. Install AD FS 2.0 Rollup 2 on all instances where AD FS is involved: proxies, farm members and also third-party organizations if AD FS is installed there.

          2. Add the following change to <microsoft.identityServer.web> section of the IIS web.config of all participating AD FS instances, under the /adfs/ls path.

             <useRelayStateForIdpInitiatedSignOn enabled=”true” />

          In this example we’ll evaluate ADFS in a SAML 2.0 Identity Provider (IdP) role within a third party Organization, called Fie, and also as a Relying Party Security Token Service (RP-STS) within the resource organization (Foo).  Fie Users may click on a hyperlink or a bookmark that kicks off the logon process with their IdP, and through the use of RelayState, via the parameterized Relying Party Identifiers provided to the IdP and RP-STS ADFS instances, the user is sent to the service provider application.

          For our web application and SAML 2.0 SP, I’m going to use cloud provider OneLogin. This will act as an application portal. Once logged on via the IdP, the user is sent to the OneLogin portal thru the RP-STS of Foo. Referring to the diagrams above, this access scenario probably best fits Figure 2. Since the web application belongs to Foo, we’re using an indirect trust involving the Foo ADFS instance as an RP-STS. Fie is a claims provider (CP) to the Foo organization ADFS and the web application is a SAML 2.0 Service Provider (SP) that trusts the ADFS instance as an Identity Provider (IdP).

          Here are the service endpoints and relying party identifiers that we need to use to build the appropriate link.

          Using the new notation provided in Rollup 2, two relying party identifiers (RPID) are required in order for the relay to the web application to work correctly. The RPID in ADFS terms is the identifier. For a SAML 2.0 SP, this is the Entity ID of the web application. In some scenarios the entity ID may not be sufficient and additional parameters required. Refer to the Microsoft article mentioned earlier on how this may be further encapsulated into the RelayState. I’ve included the URL encoded and decoded syntax below to give you an idea the syntax we’re forming.

          Here’s the URL Decoded link, broken into three parts:

          1. &RelayState=RPID=
          2. &RelayState=RPID=

          Part 1 is the URL of the Identity Provider, Part 2 the query string and RelayState for the RP-STS, and Part 3 state for the SAML 2.0 SP.

          Users logon on at Fie IdP, either through the AD FS proxy using forms-logon, when connecting externally or with their Windows logon ID thru the ADFS farm.  Once we’ve encoded the link, it looks like this:

          And we hit the OneLogin portal:


          I began the post with a smiley, so I’ll end with one.. nice feature Smile..

          ADFS – SAML 2.0 Identity Provider and SaaS Service Providers

          Under ADFS 2.0, Microsoft support the SAML 2.0 IdP Lite and SP Lite modes described in the Liberty Alliance/Kanatara Initiative interop program and eGov Profile 1.5, covering the essentials for identity federation.  From a configuration perspective, we often come across issues in the federation setup phase that can trip up ADFS and the administrator. Sometimes this is the case when dealing with SaaS applications, where there may be minimal customization possible from the vendor standpoint, with the application living in a multi-tenant environment. Tweaking “their side” may not be possible or something that the vendor is comfortable or capable of doing.

          In this post, we’ll look at some of the integration issues one may experience when integrating ADFS as an IdP with SAML 2.0 SP web applications using the SAML 2.0 POST profile. There are a number of useful debugging aids/tools that can assist in the troubleshooting process.

          All of the above are useful to lean on and gather problem-solving information during troubleshooting.

          Scenarios covered here are using ADFS 2.0 as an Identity Provider (IdP).

          ADFS Configuration

          There are some common gotchas when configuring the relying party in ADFS in the UI.

          Issuer / Identifier

          Based on the SAML specs, the <samlp:AuthnRequest> must include a <saml:Issuer> including the EntityID of the Service Provider. If you’re creating the relying party manually, double check that the relying party identifier you specify matches that of the EntityID specified in the XML file provided by the Service Provider.

          <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
          <EntityDescriptor entityID= xmlns="urn:oasis:names:tc:SAML:2.0:metadata">

          If there’s a mismatch then this may trigger an error:

          Exception details:
          Microsoft.IdentityServer.Service.Policy.PolicyServer.Engine.ScopeNotFoundPolicyRequestException: MSIS3020: The relying party trust with identifier ‘
’ could not be located.

          In the above example, the expected identifier is was mis-configured in the UI by yours truly with an identifier of .. back into the UI to correct…



          Certificates deserve an entirely separate post, but not today Smile…… a few caveats though.. for token signing, the requirement for signing of SAML sign-in requests by the RP is optional. Should you wish to enforce this it is configurable via Powershell … besides importing the requisite token signing certificates and handling the lifecycle management of your certificates in a diligent fashion, bear in mind that if you also want to employ encryption (and possess an encryption certificate) ADFS will sign assertions by default. Moreover, it will use AES-256 for encryption. This can cause issues with service providers that support weaker algorithms. If you experience this issue, then you may be forced to disable claims encryption for that relying party. This can be accomplished through Powershell (set-ADFSRelyingPartyTrust). I’ve not found a way to tweak this in a more refined fashion than on/off…

          Another problem to be wary of is certificate revocation checking… if a Certifcate  Distribution Point (CDP) is referenced in the signing or encryption certificate of one of the federation partners, then the corresponding party must be able to reach that CDP in order to determine the validity of the certificate. This can be problematic, for example, if your security policy blocks connections from servers to the Internet or if the counterpart does not publish it over the Internet. 

          Secure Hash Algorithm

          A common problem when connecting to relying parties, ADFS defaults to the more secure but less well known hash algorithm of SHA-256. SHA-1 is more widely used with the majority of  cryptographic libraries. If you’re getting an error such as this:

          SAML request is not signed with expected signature algorithm. SAML request is signed with signature algorithm . Expected signature algorithm is

          Flip the secure hash algorithm over to SHA-1 on the Advanced tab in the Relying Party trust to fix this.

          SAML Integration

          Contained within are some SAML integration issues experienced that I wanted to share.

          NameIDPolicy Format URIs

          Normally contained with an authentication request is the NameID Policy and format attribute(s). There are numerous ways in which intended or unintended settings can trip up the federation process. When troubleshooting, start with the ADFS event logs as these can be quite revealing.

          Here are a couple of sample problem cases.

          EXAMPLE 1

          PROBLEM: A federation trust has been setup between Organization A and SaaS Provider B. Users attempt to access their SaaS application via SP-initiated logon. After logging on an at ADFS, the SAML redirect returns them to the web application where it fails with a generic HTTP 500 error at the web application.

          The SAML authentication request had a NameID Policy that could not be satisfied.

          Name identifier format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient
          Exception details: 
          MSIS1000: The SAML request contained a NameIDPolicy that was not satisfied by the issued token. Requested NameIDPolicy: AllowCreate: True Format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient SPNameQualifier: . Actual NameID properties: Format: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified, NameQualifier:  SPNameQualifier: , SPProvidedId: .

          Looking at the ADFS logs we find MSIS1000 errors. As the above message indicates, the requester is expecting a format of Transient, but we’re sending a format of Unspecified.  Oops…

          SOLUTION: The Event Log message also reported that “Use the AD FS 2.0 Management snap-in to configure the configuration that emits the required name identifier.” In other words, fix the identifier… our mismatched name identifier in this case can be fixed by creating a transform Rule and setting the NameID format to what the relying party expects -  transient. In the example below, we take the incoming claim of Common Name and pass it to the Name Identifier in Transient form.

          c:[Type == ""]
          => issue(Type = "", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties[""] = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient");

          Note that the use of transient and persistent formats in identifiers are intended to provide privacy-preserving pseudonyms to protect the identity of the subject. Persistent assumes that the identifier assigned to the identity remains the same each time the user logs on, whereas Transient properties are per session. If you want to create opaque identifiers during logon, I suggest reading the following useful article:

          In my case, the application I was using involved personalization and rendered this approach unsuitable. Also, by transforming Common Name into Transient on the claims pipeline, we are also circumventing the privacy-preserving methods that Persistent/Transient were intended for, as the name is no longer obfuscated. Token encryption can be used to overcome this, but that brings its own caveats.

          EXAMPLE 2

          PROBLEM: A federation trust has been setup between Organization A and SaaS Provider B. Users are attempting to access the SaaS application via an SP-initiated logon process. After logging on an at ADFS, the SAML redirect sends them to the web application where it fails with a generic HTTP 500 error at the web application.

          The SAML authentication request had a NameID Policy that could not be satisfied.

          Name identifier format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient

          Exception details:
          MSIS1000: The SAML request contained a NameIDPolicy that was not satisfied by the issued token. Requested NameIDPolicy: AllowCreate: True Format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient SPNameQualifier:
 Actual NameID properties: Format: urn:oasis:names:tc:SAML:2.0:nameid-format:transient, NameQualifier:  SPNameQualifier: , SPProvidedId: .

          Looking at the ADFS logs we see MSIS1000 errors. In this scenario, ADFS is not providing an expected NameQualifier and SPNameQualifier to the Service Provider in the SAML Response.


          Via a claims rule we can insert the relevant information that the service provider is seeking to satisfy the authentication request.

          c:[Type == ""] => issue(Type = "",
          Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["
          = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient", Properties["
"] = "",
"] = "");

          Authentication Context

          Authentication contexts allow the service provider (SP) to augment in the assertion, the type  and strength of authentication desired. To increase the chance of (successful) interoperability the <samlp:AuthnRequest> should not include a <samlp:RequestedAuthnContext> element. This recommendation bears out in testing with ADFS. The support for different authentication context classes vary and the semantics often interpreted differently. When processing a SAML authentication request, the interpretation of the relative strengths of the different authentication context classes is up to the responder and AD FS 2.0, by default, interprets the relative strength of these different authentication context classes in its own order. By default, this is:


          When the service provider is requesting this information, you may find that out-of-the-box it doesn’t work… let’s have a look at some examples …

          EXAMPLE 1

          PROBLEM : A federation trust has been setup between Organization A and SaaS Provider B. Users are able to logon to the SaaS application via the ADFS Proxy from home or remotely using form-based logon. When they logon internally,  via the ADFS farm, the same users are not able to do so and get an HTTP error. 

          <samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Comparison="minimum"><saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef></samlp:RequestedAuthnContext>

          In the above SAML authentication request, the Service Provider (SP) is specifying that the expected authentication context  from ADFS is  urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport. Users doing an integrated windows logon are not emitting this authentication context and instead they transmit urn:federation:authentication:windows in the authentication context to the RP and it may trigger an exception.


          There are a couple of ways to tackle this problem:

          (a) the service provider may be able to submit the additional authentication context for Windows authentication (urn:federation:authentication:windows) to their configuration.  
          (b) if the service provider does not support this change, we can provide the appropriate value in the relying party response by checking for the presence of NameID and then parsing urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport in the response. For example:
          exists([Type == ""]) => issue(Type = "", Value = "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport");

          EXAMPLE 2

          PROBLEM: A federation trust has been setup between Organization A and SaaS Provider B. Domain-joined users expecting single sign-on through ADFS are being presented with the forms logon handler when accessing the SaaS application internally. They then have to manually enter their credentials per session.

          <samlp:NameIDPolicy  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent" AllowCreate="true"></samlp:NameIDPolicy>
          <samlp:RequestedAuthnContext xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" Comparison="exact"><saml:AuthnContextClassRef xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml:AuthnContextClassRef></samlp:RequestedAuthnContext> </samlp:AuthnRequest>

          The service provider was, by specifying a comparison of "exact", forcing the authentication context for all users to be set to PasswordProtectedTransport, inadvertently telling ADFS to downgrade authentication for domain-joined clients to forms logon, thus defeating/breaking SSO for internal clients.

          SOLUTION: Ensure that the SP sets the RequestedAuthnContext comparison to minimum.


          That’s it for the moment…… I’ll add to this when new scenarios crop up or via  input from other contributors..