Rolling out your own SAML integrations has always been hard. It’s a complex implementation that’s difficult to build securely and efficiently whether you’ve built it before or not. Here at Stormpath, we’ve rolled out a simple solution to enable SAML in your applications without custom code!

With only a few steps, you can integrate SAML into your PHP project. No matter which identity provider you are using, the code will remain the same. We can even help you with a no-code SAML experience with our ID Site integration. In this tutorial, we’ll walk you through how to enable SAML support for easy setup and usage of your favorite SAML provider with the Stormpath PHP SDK.

What Is SAML?

SAML (Security Assertion Markup Language) is an XML-based standard for securely exchanging authentication and authorization information between entities—specifically between identity providers, service providers, and users. Well-known IdPs include Salesforce, Okta, OneLogin, Shibboleth. Your apps are the SAML service providers, and the Stormpath API makes it possible to integrate them with the IdPs (but without headaches).

Set Up Your SAML Provider for PHP Applications

Configuration of a SAML provider is stored under a directory in Stormpath. This means the first step will be setting up a directory as a SAML directory. As a refresher, setting up a directory using the Stormpath PHP SDK looks like this:

This will create a basic cloud directory in the Stormpath system. To make this a SAML directory, we have to first instantiate a SAML provider then attach it to a directory. To instantiate a SAML provider, you use the following code:

  • SSO Login URL: The URL at the IdP to which SAML authentication requests should be sent. This is often called an “SSO URL”, “Login URL” or “Sign-in URL”.
  • SSO Logout URL: The URL at the IdP to which SAML logout requests should be sent. This is often called a “Logout URL”, “Global Logout URL” or “Single Logout URL”.
  • Signing Cert: The IdP will digitally sign auth assertions and Stormpath will need to validate the signature. This will usually be in .pem or .crt format, but Stormpath requires the text value.
  • Signing Algorithm: You will need the name of the signing algorithm that your IdP uses. It will be either “RSA-SHA256” or “RSA-SHA1”.

Once you have your provider instantiated, you then just add one item to the directory creation. As part of the properties, add a provider item and make it equal to the instantiated provider.

Now you have a SAML provider you can work with for your application.

Configure Your Service Provider In Your Identity Provider

Your Identity Provider (IdP) needs to understand some information about the Service Provider. We’ve simplified this process by providing a url that you can either give to your IdP, or gather the data from the url which includes all the information needed. To access this information, you have to get it from the directory provider.

This will give you a few items that you need to provide to your IdP. For some IdP’s you can give them the href that is provided as part of this response and they know how to handle it. We follow the standard format for the meta data. Other IdP’s will require you to get some of the information from here and provide it to them. The information you will need from the response follows:

  • Assertion Consumer Service URL: This is the location the IdP will send its response to.
  • X509 Signing Certificate: The certificate that is used to sign the requests sent to the IdP. If you retrieve XML, the certificate will be embedded. If you retrieve JSON, you’ll have to follow a further /x509certificates link to retrieve it.
  • SAML Request Binding: Set to HTTP-Redirect.
  • SAML Response Binding: Set to HTTP-Post.

Configure Your Application To Allow Callbacks

Configuring your application is an important part of the process. You will need to tell your application what urls it is allow to have the IdP send your users back to. These urls should be hosted by you. We have made it just like updating any other property on your application.

Map SAML Attributes To Stormpath

You may be asking yourself now about how Stormpath knows what values to use when putting the account information into the stormpath directory. This is all done from the Attribute Mapping Statements. IdPs will provide you with an XML that has data that you can pull from.

In this response you can see that there is a list of attributes and in each attribute is a Name and NameFormat. These are two values that you can use to map it to an attribute in Stormpath. In the above example let’s use the following mapping:

  • uid maps to Stormpath’s username
  • mail maps to Stormpath’s email
  • location maps to a custom data attribute for the account city_state

When mapping these attributes, you can use either name or nameFormat, or both. Stormpath will match as much as you provide to get the attribute value and map it to the correct account field. To set up this mapping, run the following:

Once these are mapped, Stormpath does just in time provisioning of the account so we are always synced with the IdP. Stormpath will see the xml that is returned from the IdP and find the attributes that you want to map and map them to what you defined them to.

How to Use Your SAML Provider for PHP Applications

Now that you have set up your SAML provider in your application, you can now use it for logging in. For this example, we are going to make a request to ID Site. Build a PHP API login request and redirect the user to ID Site:

Once here, You should see your SAML Provider as an option on the login screen.

Further Reading

Stormpath is really excited to offer SAML as part of the PHP SDK. We have full documentation on our github page where you can go further into detail. We will soon be offering SAML support inside of our integrations as well. Let us know what you think about our SAML support.

Feel free to drop a line over to email anytime.

Like what you see? to keep up with the latest releases.