INTEGRATION WITH A GOOGLE APPS TEST ACCOUNT
===========================================

Setup a Google Apps Test Account
--------------------------------

1. Get a Google Apps Test Account here:

https://www.google.com/a/cpanel/sample/new?hl=en

NOTE: This is only good for 14 days.

If your email address is foo@example.com, your domain name will be something like:

fooexamplecom.sample-ga.com

For the remainder of this document, we'll just say YOURDOMAIN.

Google will email you a username and password for this test account.

2. Login and accept all the terms.

Configure SAML 2.0 Single Sign-On
---------------------------------

3. Go to your Control Panel > Advanced Tools > Single Sign-On

https://www.google.com/a/cpanel/YOURDOMAIN/SetupSSO

4. First, upload your public certificate, containing the public key.

For a NON-PRODUCTION server, you can use "idptest/sample/sample-certificate.pem".
For a PRODUCTION server, DO NOT USE THE SAMPLE CERTIFICATE! Instead, use the
"idptest/keys/mk_keys.sh" script to create your own certificate and private key.

When you have uploaded your certificate, the page will say:

"A certificate file has been uploaded"

WARNING: BE SURE TO CLICK "SAVE" AFTER UPLOADING A CERTIFICATE.

5. Second, enter the SAML 2.0 IdP URLs.

For an unmodified saml2idp, you should use these:

Enable Single Sign-on: checked
Sign-in page URL     : http://127.0.0.1:8000/idp/login/
Sign-out page URL    : http://127.0.0.1:8000/idp/logout/
Change password URL* : http://127.0.0.1:8000/accounts/password/change/

*NOTE: The change password URL isn't yet supported by saml2idp.

6. Save changes.

Start your test IdP
-------------------

7. Create the Django database and super user account.

$ ./manage.py syncdb

NOTE: Go ahead and setup a super user account when prompted.
    Enter the email address that Google is expecting. It should be
    what you entered when you setup your test account in step 1.

8. Ensure that you have enabled the Google Apps processor. In settings.py:

    SAML2IDP_REMOTES = {
        ...
        'google_apps': {
            'acs_url': 'https://www.google.com/a/YOURDOMAIN/acs',
            'processor': 'saml2idp.google_apps.Processor',
        }
        ...
    }

9. Run the Django test server.

    $ ./manage.py runserver

Login and logout using SAML 2.0
-------------------------------
At this point, I highly recommend starting the SAML Tracer plugin for Firefox:
https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/

10. Open the GMAIL URL for your sample domain:

http://mail.google.com/a/YOURDOMAIN

Google will redirect to your test IdP's login page.

11. Login using your local IdP.

After logging in (using your superuser account), your IdP will redirect back
to Google Mail.

12. Logout as normal.

Google Mail will redirect to your local IdP's logout page.

TROUBLESHOOTING
===============
1. Google Apps says, "cannot parse the response."
    Something is broken. Please report this to us.

2. Google Apps says something about "unauthorized."

    a. Ensure that you have uploaded the correct public key.
    b. Ensure that the email address that Django has is the same as what you
         configured for your Google Apps user account.

Unfortunately, Google Apps isn't very forthcoming with error messages, so it's
hard to debug.
