Switch on SAML for PHP With Project Lightbulb

Print-friendly Version

See also: A sequel to this article, Single Logout: A Demo, which updates you about Project Lightbulb and describes how to terminate user sessions with all the members of a Circle of Trust.

Lightbulb, an Open Web Single Sign-On (OpenSSO) subproject, aims to achieve federated identity for LAMP (Linux, Apache, MySQL, PHP, Python, and Perl) and MARS (MySQL, Apache, Ruby, and the Solaris Operating System). Currently, Lightbulb offers a service provider (SP) written in PHP with Security Assertion Markup Language (SAML) 2.0. This article elaborates on the SP code and describes how to enable Web applications that are also written in PHP with SAML 2.0.

Note: At present, Lightbulb is experimental, so treat it as sample code only. Sun does not warrant or support Lightbulb.

SAML 2.0 consists of a set of specifications for communicating information on user authentication, entitlement, and attributes. With SAML, you can configure SPs to permit access to resources only when an identity provider (IdP) has authenticated a user, thus enabling SSO between the IdP and the SPs. SAML 2.0 was approved by the Organization for the Advancement of Structured Information Standards (OASIS) in March 2005.

Presently, Lightbulb implements the SP role in SAML 2.0's Web browser SSO profile through the SAML redirect and POST bindings. Figure 1 illustrates an example of the exchange of messages in that configuration.

Figure 1: Overview of Message Exchanges in SSO Configuration With Lightbulb

The solid lines with arrows represent SAML 2.0 protocol messages. The dotted lines with arrows are messages that are outside the scope of the protocol. Following is the process:

1. The user, with an account at the IdP, attempts to access a resource at the SP from a browser.
   
   
2. The SP, which trusts the IdP to authenticate the user, redirects the browser to the IdP with a 302 HTTP response.
   
   
3. The browser follows the redirect and sends an HTTP GET request to the IdP with a SAML authentication request encoded in an HTTP parameter.
   
   
4. The IdP authenticates the user.
   
   The user might be required to supply credentials in the form of a user name and password, a smart card, a biometric, or other mechanism.
   
   
5. The IdP returns to the browser an HTML page to be posted to the SP. The page contains a form with a SAML authentication response as a hidden element. A JavaScript onLoad() event handler automatically sends the form to the SP.
   
   
6. The browser posts the form to the SP, which then evaluates the SAML authentication response and allows or denies access to the resource.
   
   
7. The user then can or cannot access the resource, depending on the SP's decision.

To protect user privacy, SAML 2.0 can specify a pseudonym in the SAML Assertion's NameID element rather than the user's actual identifier (for example, the user name) at the IdP. That pseudonym, a string of characters typically randomly generated by the IdP, is known as a persistent (opaque) identifier—the user's identifier in the context of the IdP-SP relationship. That way, neither provider knows the user's identifier at the other end. Furthermore, because the user has a different persistent identifier for each IdP-SP pair, SPs cannot correlate user accounts among themselves.

Note: Even though other NameID formats are available with different privacy properties, persistent identifiers are most commonly used and are the only format currently supported by Lightbulb.

The preceding is a high-level view of SAML SSO. For more details on federated SSO, see the following:

• Federated Identity: Single Sign-On Among Enterprises, an October 2004 article that predates SAML 2.0
  
  
• SAML 2.0 Technical Overview (PDF), currently at draft 10

The current, initial Lightbulb SP is structured as a simple sample PHP application, integrated with SAML's SP library code. This section follows the SAML SSO protocol described in the previous section through the Lightbulb code and highlights the two SSO integration points between Lightbulb and the application. You can download the Lightbulb source code from the Web interface or CVS (see the instructions after logging in to java.net).

Initiating SAML SSO

The following excerpt from the prompt.php file contains a link to the spSSOInit.php script:

<a href="http://patlinux.red.iplanet.com/lightbulb/spSSOInit.php?metaAlias=/
sp&idpEntityID=http://
amfmdemo.example.com&binding=urn:oasis:names:tc:SAML:2.0:bindings:HTTPPOST&
RelayState=<?php echo htmlspecialchars($_GET["goto"])?>">
    Login via IDP
</a>

This is the first integration point between the Lightbulb SAML 2.0 code and the PHP application. Table 1 describes the script's parameters, which, closely modeled on OpenSSO's SAML 2.0, direct spSSOInit.php to initiate SAML 2.0 SSO.

Parameter	Description
metaAlias	The SP identifier. Multiple SPs are each denoted by metaAlias.
idpEntityID	The IdP identifier for authentication.
binding	The SAML binding in the protocol.
RelayState	The requested resource.

Currently, all four parameters are mandatory. Future versions of the script will likely streamline simple deployments by making metaAlias, idpEntityID, and binding optional.

The spSSOInit.php script performs the following tasks:

1. Uses metaAlias and idpEntityID as indexes into tables of metadata: configuration information such as the endpoint URLs in the protocol.
   
   
2. Assembles and prepares a SAML AuthnRequest element for transmission as an HTTP parameter according to the SAML 2.0 specification.
   
   
3. Compresses (deflates) the prepared AuthnRequest element, encodes it for Base64, and encodes the URL.
   
   
4. Constructs a URL with the encoded AuthnRequest and RelayState elements as parameters to the IdP's SSO service endpoint.
   
   
5. Redirects the browser to that URL.

Take a look at this typical AuthnRequest element.

Processing the SAML Response

On receiving the authentication request, the IdP authenticates the user and directs the browser to post a SAML response to the sp.php script.

Next, the following process takes place:

1. The sp.php script decodes the Base64 SAML response and parses the response and its component SAML Assertion with the processResponse() function from saml-lib.php.
   
   
2. processResponse() verifies that the Assertion's signature is correct and that the signing certificate's thumbprint (SHA-1 hash) matches the one on record in the metadata for the IdP.
   
   
3. The script maps the Assertion's NameID to a local user name and sets the latter with the setUserID() function from the localUserManagement.php script.
   
   This is the second point of integration. You would replace setUserID() with the function that sets the user name in your application.
   
   If NameID does not correspond to a user account, the script redirects the browser to the login page (prompt.php) and then to mapName.php to authenticate the user locally and to map NameID to the resulting local user name.

You've now examined a profile of the SAML SSO protocol, followed its execution through the Lightbulb PHP code, and noted the integration points between Lightbulb and a typical PHP application. A future article on Lightbulb will explain SAML's circle-of-trust concept and will describe how Lightbulb's single logout process terminates user sessions with all the members of a circle of trust.

Special thanks to Rob Richards, author of the PHP library for XML security, for his gracious permission to adapt the library code into OpenSSO for use in Lightbulb.

• Sun Java System Access Manager
  • Main page
  • Developer home
  • Software Forum
  
  
• SAML 2.0 Specification
  
  
• Project Lightbulb
  
  
• Project OpenSSO
  
  
• Related articles
  • Federated Identity: Single Sign-On Among Enterprises (October 14, 2004)
  • What's Happening in Identity at Sun (September 1, 2006)
  
  
• Sun developer services
  • Support
  • Training and certification