by [Lewis](https://www.lewisroberts.com/author/ljr/) · Sat 5th September, 2015
In my last mammoth post, I posted an update/re-write to an article originally written on the Azure website that used some libraries provided by Microsoft to enable custom PHP applications to sign-on to Azure AD using WS-Federation. In that post I described a method for installing and configuring SimpleSAMLphp to IIS that enables it to be used by any number of sites on the same server, all that’s required is to add a simple Virtual Directory to each site. If you want to configure SimpleSAMLphp on IIS, check that post out.
The intention with this post is to do away with Microsoft’s libraries altogether and use only SimpleSAMLphp in a more integrated way. The purpose is to avoid having to re-write a lot of functionality already provided by SimpleSAMLphp that’s likely to be missing from Microsoft’s libraries, and of course open up access to SimpleSAMLphp’s documented API.
I will assume you have configured SimpleSAMLphp already using the method documented in the last post. In order to proceed in this post, you also need to have configured an application within Azure Active Directory. Again, you can find instructions for that included in the previous post.
The largest difference with this post is, as I mentioned, better integration with SimpleSAMLphp – as such, there’s more configuration to complete within SimpleSAMLphp than there was in the previous post.
* We’ll import federation data from our Azure application in to SimpleSAMLphp.
* We’ll configure SimpleSAMLphp as a Service Provider.
* We’ll create a little code to get us authenticating.
# <a name="more-1489"></a>Pre-requisites
1. As mentioned, we need SimpleSAMLphp set up on the server as per my previous post. In _this_ post, I’ve created a new website called <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">sso.lewisroberts.com</font></font> and configured the Virtual Directory. It’s all documented in the previous post so you can use that to get to this stage.
2. We need an application configured in Azure Active Directory just as per my previous post. In this post, I’ve created a new application I’ve called <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">sso.lewisroberts.com</font></font>. There’s no special configuration required for the application.
3. Using your favourite browser, navigate to the location and save the metadata document. How you do this doesn’t really matter, as long as it’s just the XML you save.
4. Open the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">federationmetadata.xml</font></font> file in a text editor, select the entire contents (Ctrl+A) and then copy it to the clipboard.
5. Open a browser and navigate to <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">https://sso.lewisroberts.com/simplesaml</font></font>_(Actually, you’ll obviously navigate to your own PHP application’s website, not mine_._)_ Once there, click the **Federation** tab.
7. Paste the entire <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">federationmetadata.xml</font></font> file’s contents in to the field and click the **Parse** button.
8. The page should return almost immediately with some information similar to the following under the Converted metadata section. Copy the contents of the **saml20-idp-remote** field to your clipboard, or a file, it’s your choice.
9. Navigate to your SimpleSAMLphp installation folder and find the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">metadata</font></font> folder.
11. Now copy the converted metadata contents in to the file. I’ve highlighted where this was pasted in to my own version of the file. Do note however that obviously the converted metadata extends beyond the bottom of the visible screen I show here. It should be a simple matter of pasting in the converted metadata. Save the file.
1. Navigate to your SimpleSAMLphp installation folder and open the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">config</font></font> folder.
3. There are a number of authentication sources preconfigured (but commented out) however the one we’re interested in (or rather, its general format) is <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">default-sp</font></font>. I’ve shown this (actually, the interesting bits) in its default state, below.
4. In order to achieve compatibility with Azure AD, we need to make some small changes to default-sp. We _could_ just create another authsource called something else but it’s easier to show what it looks like initially and then edited if we change default-sp. The next few steps will show where we make edits.
5. Firstly, change the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">entityID</font></font> value to reflect the name or URL of your Azure application.
6. Next, enter the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">idp</font></font> value. Where did I get this from? The very first line of the converted metadata actually gives you the IdP (Identity Provider) – in this case, Azure AD.
2. We’re complete editing <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">authsources.php</font></font> so save and close the file.
# Testing authentication
Now that configuration of SimpleSAMLphp is complete, we can use SimpleSAMLphp to test authentication works as expected, without actually writing any code but we’ll get to that in a second.
1. Navigate to <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">https://sso.lewisroberts.com/simplesaml</font></font> (remember, your own app, not mine, this is an example.) and then click the **Authentication** tab.
3. We should see only two options<fontface="Courier New"><fontstyle="font-size: 10pt"size="2">, admin</font></font> and <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">default-sp</font></font>. These were the only two authentication sources defined in <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">authsources.php</font></font>. Click **default-sp**.
4. You will likely receive an error that looks as follows. This means that the **Reply URL** sent by SimpleSAMLphp to Azure AD as part of the authentication attempt isn’t one that is accepted by the application. So it’s not very happy. To fix this, we need to quickly visit the Azure Management portal and add this **Reply URL** to our application.
5. First, copy the URL from the error. In this case, the URL is: <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">https://sso.lewisroberts.com/simplesaml/module.php/saml/sp/metadata.php/default-sp
6. In the Azure Management portal, find the application, scroll to **Single Sign-On** and add it to the list of **Reply URLs**. Save the configuration change but leave the management portal open in case you must make any more edits.
9. We should now be able to sign in without error and get redirected back to SimpleSAMLphp and shown a list of the claims that were sent along with the authentication.
So, all this configuration was just to get us to the point where we can create our own application code that allows us to authenticate with Azure AD. The reality is that our PHP “application” can be a single page.
## index.php
Generally, the application will require an <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">index.php</font></font> file – the code for which is below. I’ll give a very brief breakdown of the first few lines, the rest is obvious.
This file will require authentication so, on line 2, it calls SimpleSAMLphp’s autoloader from the main installation of SimpleSAMLphp.
On line 3, we create a new object from the SimpleSAML_Auth_Simple class but notice here we specify the authsource <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">default-sp</font></font> – that’s correct, we’re associating this application with the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">default-sp</font></font> auth source we created.
On line 4, we use the object and tell it we require authentication. If the user is authenticated, the script will proceed to the next line, if not however, they will begin the authentication process and be redirected to Azure AD to sign in. Once signed in, they will be redirected back to this page.
On line 6, we pull the attributes from the SAML token and store them in the $attributes array. These are then used later (line 21) to show the user their claims.
On line 25 we get a logout URL from the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">$as</font></font> object and send that back to the interface so the user can click a link to log out.
1. The user navigates to the web application. Given they’re not logged in, they’re automatically redirected to the Azure AD sign in page.
3. The user logs in with a valid Azure AD account.
_Notice as well that the page also says_ _<fontface="Courier New"><fontstyle="font-size: 10pt"size="2">sso.lewisroberts.com</font></font>_ _– a bit of free branding._
One thing I’ve wondered while doing all this was whether we could get additional claims through rather than just those few that are shown in the screenshots. Something like groups would be great. As it turns out, that feature was introduced at the back end of 2014. I’ll run through it very quickly in the context of our application but for more details (and how to handle users who might be members of more than 150 groups (in SAML)) you really should [visit the blog of Dushyant Gill](http://www.dushyantgill.com/blog/2014/12/10/authorization-cloud-applications-using-ad-groups/).
1. In the Windows Azure management portal, navigate to your application and click **Manage Manifest** then **Download Manifest**.
3. Open the file in any decent text editor. I’ve chosen to do it in Visual Studio code. Locate the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">groupMembershipClaims</font></font> value.
4. Change this to one of <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">SecurityGroup</font></font> or <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">All</font></font>.
* <font face="Courier New"><font style="font-size: 10pt" size="2">SecurityGroup</font></font> – The <font face="Courier New"><font style="font-size: 10pt" size="2">groups</font></font> claim will contain the identifiers of all security groups that the user is a member of.
* <font face="Courier New"><font style="font-size: 10pt" size="2">All</font></font> – The <font face="Courier New"><font style="font-size: 10pt" size="2">groups</font></font> claim will contain the identifiers of all security groups and distribution lists that the user is a member of.
5. I’ve chosen to just enable <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">SecurityGroup</font></font> option in the screenshot below. Save the file.
8.**Dushyant’s post goes on to mention that you should grant additional permissions in the application. This is only really required****_if_****you are going to be dealing with “overage” scenarios which means users who are members of more than 150 groups, since these can’t be included in the SAML token. Read [his blog post for more info](http://www.dushyantgill.com/blog/2014/12/10/authorization-cloud-applications-using-ad-groups/). For our demo app purposes, our user is a member of only one group.**
9. So, I’ve created a group in my Azure AD and added the user to it. Note the **Object ID**, this is the value that will be shown in the claim.
10. Now if we re-try our authentication (and without making any code changes to our <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">index.php</font></font> file) we see that the <fontface="Courier New"><fontstyle="font-size: 10pt"size="2">groups</font></font> claim is carried through in to the application. Of course this means you can use it for security trimming etc. within your custom app.
_**Note**__: I noticed that there was another group id in the claim – I’m assuming this is related to this user’s status as a Global Administrator since if I authenticate as a user who is purely a member of the LocalAzureAD group, the only groups claim attribute is the Object ID of the LocalAzureAD group._
So, another not insignificant post ends and hopefully you’ve learned a little something along the way. Seeing that it’s possible to pull group claims through in to the application opens a lot of possibilities for developers of bespoke PHP applications and I’m sure it’ll be very handy to know in the future.
I think I’ve got one more post in me about SimpleSAMLphp and that is probably going to be integrating SimpleSAMLphp with ADFS 2012R2\. That post will hopefully be shorter since we’ll be repeating a lot of the activities we’ve done above. For example, instead of importing the federation metadata from our Azure Application, we’ll import from the ADFS server and set that up in SimpleSAMLphp. We’ll configure our PHP “application” as a Relying Party Trust and get all the necessary information automatically from simpleSAMLphp and finally configure the ADFS server as the IdP for the application.
