This document describes the web-based reference implementation of a SAML-based single sign-on (SSO) service that logs users in to Google Apps. The web application is a PHP application that generates and sends SAML requests, receives and parses SAML requests, calls a function to authenticate users, and then returns a SAML response to the user's browser. The browser must then send the SAML response on to the Assertion Consumer Service (ACS) URL to log the user into Google Apps. The identity provider can choose the appropriate mechanism to use to trigger the post of the SAML response, but possible solutions include a button that the user clicks or a JavaScript function.
This document contains an overview of the code included in the SAML reference package. It also describes a three-stage process for partners who are using the reference implementation as a guide during their own development process.
The following references may help you to implement a SAML-based SSO service:
The SAML reference code performs two types of functionality.
The PHP SAML reference implementation uses a web server with PHP 5 installed, and requires the xmlsec binary for signing the XML SAML response.
The following list identifies the file and directory structure of the SAML reference code. File or directory names shown in bold, blue text identify files that perform functions handled by the identity provider in a SAML transaction. The remaining files and directories in the list either perform functions handled by the sevice provider in a SAML transaction or they are used exclusively in the user interface (UI). (In practice, your SAML-based SSO service will not need to have a user interface; however, you may want to adapt the UI provided in the reference package to use for debugging purposes.)
*.php - This directory contains six PHP files used in the SAML reference implementation The following list explains each of the files in more detail.
process_response.php - This file receives a SAML request, parses it, calls a method to authenticate the user, and constructs and sends a SAML response. Your application will need to perform this functionality.
saml_util.php - This file provides functions required to generate the SAML response.
create_request.php - This file constructs a SAML request. In an actual SAML transaction, the service provider will execute these functions. As such, your production SSO service does not need to include functions for creating SAML requests..
identity_provider.php - This file provides a UI for process_response.php, and is not required in a production SSO service.
saml_demo.php - This file provides a user interface for the SSO demo, and is not required in a production SSO service.
service_provider.php - This file provides a UI for create_request.php, and is not required in a production SSO service
global/ - This directory contains images and stylesheets used in the UI for the reference implementation. You do not need to modify these files.
keys/ - This directory contains public and private DSA keys that are used to sign SAML responses. Google also uses the public key to decode SAML responses authenticating users who log in to the psosamldemo.net domain, a sample domain that you can use to test your SAML-based SSO service.
templates/ - This directory contains two templates, one for generating SAML requests and another for generating SAML responses. Your production application will not use the request template but you may want to use the response template.
This section explains how you can use Google's SAML reference implementation to implement a SAML-based SSO service that allows users to log in to Google Apps through your site. This document prescribes a three-stage process for partners who plan to use the reference implementation as a guide during their integration process.
Stage I explains the steps for installing the code for the reference implementation and verifying that the reference implementation works on your site.
Stage II explains code modifications that you would make so that the sample code will direct SAML requests to your internal user authentication application. In this stage, you will modify the application to authenticate a user and verify that the user can access Google Apps.
Stage III explains further code modifications that you will need to make so that authenticated users are logged in to Google Apps for your domain rather than Google's SAML demo site.
This reference implementation uses a web server with PHP 5 installed, and requires the xmlsec binary for signing the XML SAML response.
Copy the contents of the samltool_php.zip file into the webroot directory of your web server.
Your root directory should now contain the file and directory structure explained earlier in this document.
Please ensure that the xmlsec binary is either in a location that is included in your PATH environment variable, or is in a location accessible by your web server. You may need to edit process_response.php to specify the path to the executable. The xmlsec source and Windows binary can be downloaded from the xmlsec home page.
By this time, you are ready to test your installation. Verify that your web server is running and then try to access the saml_demo.php file in your development environment. The URL for the application should be:
Note: You will need to replace HOST_NAME with the host name of your web server.
When you access this URL, you should be able to generate and submit a SAML request by following the instructions in the
Open the identity_provider.php file, which is included in the reference package. Locate the two comment blocks that begin with the words Stage II and follow the comments in the instructions. The example below shows one of the comment blocks:
After completing this step, the UI for the reference implementation will display editable username and password fields:
Old:
|
New:
|
The login function in process_response.php represents whatever steps you, as the identity provider, take to authenticate a user. If the user is successfully authenticated, the function should return the user's username. If the user is not successfully authenticated, the function should return null.
During this step, you need to modify the login function to call your internal code for authenticating a user. You also need to modify your authentication code so that it returns either the user's username or null, depending on whether the user is successfully authenticated. If a user is successfully authenticated, your authentication mechanism should return the username that Google Apps associates with the user. This may be the same username associated with the user on your site.
The login function will receive the username and password that you enter in the username and password fields that you added in the previous step.
Note: For this stage, your application should return the username "demouser" when a user is successfully authenticated rather than the user's actual username.
Now you are ready to test your installation again. Verify that your web server is running and then reload the saml_demo.php file in your development environment. The URL for the application should be:
Note: You will need to replace HOST_NAME with the host name of your web server.
Generate and submit a SAML request using the submit buttons in the GOOGLE - Service Provider window. Then enter a username and password into the username and password fields and click the Generate SAML Response button. You can then review the SAML response and submit it using the Submit SAML Response button.
If you entered a valid username and password, you should be logged in to the demouser@psosamldemo.net Gmail account. If you did not enter a valid username and password, you should see an error message.
In stage II, you verified that you can use your internal authentication mechanism to log a user into a Google application (Gmail) for the psosamldemo.net domain. In stage III, you will modify the code to log users into Google Apps for your domain.
The SAML specification requires that XML files be digitally signed before they are exchanged between a service provider (Google) and identity provider (Google partner). The sample code in the SAML reference package logs a user into the psosamldemo.net domain. Accordingly, it includes the DSA public and private keys used to encode SAML responses that authenticate users for that domain. Since Google supports RSA, you could also generate keys using the RSA algorithm.
In this step, you will generate a pair of RSA or DSA public and private keys for encoding SAML responses that log users into Google Apps for your domain. After generating the keys, store the public key in one file and the private key in another file. Your web application should be able to access these keys, but users should not be able to access the files through a web browser.
After saving the keys, update your authentication application to use these keys to encode SAML responses rather than the DSA keys included in the SAML reference package. In process_response.php, search for the comment starting with the following text to identify the correct code to change:
After generating your public RSA or DSA key, you need to upload the key to Google using the Admin Console. You also need to provide the URL for your SAML-based SSO service as well as the URL that your users will be redirected to when they log out of a hosted Google application.
At this stage, you need to modify your application so that you log users into their own accounts rather than the demouser@psosamldemo.net accounts. You can either use the Provisioning API to create users or you can use the web interface to create users who can access Google Apps.
Verify that the login function in process_response.php returns the correct username when you enter a username and password in the UI.
Now you are ready for the final test. Verify that your web server is running and then reload the saml_demo.php file in your development environment. The URL for the application should be:
Note: You will need to replace HOST_NAME with the host name of your web server.
Generate and submit a SAML request using the submit buttons in the GOOGLE - Service Provider window. Then enter a username and password into the username and password fields and click the Generate SAML Response button. You can then review the SAML response and submit it using the Submit SAML Response button.
If you entered a valid username and password, you should be logged in to the Google Apps account that corresponds to that username. If you did not enter a valid username and password, you should see an error message.
The SAML reference package includes templates for SAML requests and SAML responses.
The AuthnRequestTemplate.xml file contains a template for SAML requests. The file contains four variables:
The SAML request has the following format. The variables listed above are shown in bold, blue text.
The SamlResponseTemplate.xml file contains a template for SAML responses. The file contains the following variables:
RESPONSE_ID - A 160-bit string containing a set of randomly generated characters. The code calls the Util.createID() method to generate this value.
REQUEST_ID - The ID of the request being responded to.
DESTINATION - The ACS URL to which the response will be submitted.
ISSUE_INSTANT - A timestamp indicating the date and time that the SAML response was generated. The code calls the Util.getDateAndTime() method to generate this value.
AUTHN_INSTANT - A timestamp indicating the date and time that you authenticated the user.
ASSERTION_ID - A 160-bit string containing a set of randomly generated characters. The code calls the Util.createID() method to generate this value.
USERNAME_STRING - The username for the authenticated user. Modify the ProcessResponseServlet.login() method to return the correct value.
NOT_BEFORE - A timestamp identifying the date and time before which the SAML response is deemed invalid. The code sets this value to the IssueInstant value from the SAML request.
NOT_ON_OR_AFTER - A timestamp identifying the date and time after which the SAML response is deemed invalid.
RSADSA - Contains the lowercase string 'rsa' or 'dsa', indicating which type of key will be used to sign the response.
ISSUER_DOMAIN - The domain of the issuer of this response.
The SAML response has the following format. The variables listed above are shown in bold, blue text.