Configuring the Google Apps Connector

Managing Applications

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

The Google Apps connector is shipped with your Crowd installation. This is a Crowd application connector which allows single sign-on (SSO) to Google Apps. If you wish to activate SSO between Crowd-connected applications and Google Apps, you will need to configure the Google Apps connector as described below.

On this page:

Background

When people refer to Single sign-on (SSO) they are usually refering to two things.

  • Authentication - which userid and which password is used to confirm that a user is who they say they are
  • SSO - authenticating for one application means that you don't have to authenticate to access another application (at least for a while and if you are using the same browser)

So in the case of Google Apps, the authentication is your Google Apps userid and password. Google Apps handles the SSO part with its Google Accounts site. When you log into Gmail in the morning you are actually being asked to enter your authentication information at the Google Accounts site, which then redirects your browser back to Gmail if you successfully authenticate. The Google Accounts remembers that you successfully authenticated this morning so that when you go to a Google Docs page later on that day, the redirect happens again without needing to reauthenticate. This all happens unseen by most Google Apps users.

Now Google Apps has the ability to change where it goes for its SSO functionality. A Google Apps administrator can configure just their Google Apps instance to use a different SSO. This could be Crowd, or any other SSO service. Crowd then becomes the master SSO service instead of Google Accounts. This means that logging into Gmail in the morning will take you to a Crowd authentication screen, not the Google Accounts. The redirection back to Gmail after a successful authentication happens just as before.

However this is not how OnDemand integrates with Google Apps. In that case the SSO functionality remains with Google Accounts.

Prerequisites

Please note the following before you start:

  • Google Apps support for SSO: To enable single sign-on in Google Apps, you will need the Premier, Education, or Partners edition of Google Apps. The free Standard Edition of Google Apps does not support SSO. See the Google Apps documentation.
  • Using the Google Apps Connector with Java 6: If you want to integrate Crowd with Google Apps in a JDK 1.6 environment, you will need to download two extra files. Please refer to CWD-1388.

Step 1. Configuring the Crowd Application, Directory and Group Details

In this step, you will enter the application details for the Google Apps application connector in Crowd. You will manage access to Google Apps by associating Crowd directories and/or groups with the Google Apps application.

To define the Google Apps application details in Crowd:

  1. Log in to the Crowd Administration Console.
  2. Click the Applications tab in the top navigation bar.
  3. Click the link on the 'google-apps' application name.
  4. If required, you can change the description. Please ensure that the Active checkbox remains ticked.
  5. Click the Directories tab and select one or more user directories that contain the users who should have access to Google Apps.
  6. To choose which users within the directory may authenticate against the application, either:
    • On the Directories tab, change Allow all to authenticate to True. This will allow all users in that directory to log in to Google Apps. (The default is False.)
      OR
    • On the Groups tab, use the Add button to select one or more groups of users.
  7. Click the Permissions tab and set the directory permissions for the application.
  8. If required, you can change the application options on the Options tab:
  9. Click the Configuration tab and generate your SSO keys as described in Step 2 below.


Screenshot: Google Apps application details in Crowd

Step 2. Generating your SSO Keys

Now you will ask Crowd to generate a public and a private key for use in authenticating Crowd to Google Apps. (Google Apps calls the public key a 'verification certificate'.)

To generate your SSO keys:

  1. In the Crowd Application Browser, as described in Step 1 above, click the Configuration tab for the Google Apps application.
  2. Click Generate New Keys.

Crowd will generate a public key and a private key, placing them in the plugin-data\crowd-saml-plugin directory of your Crowd Home. (For more information about Crowd Home, see Important Directories and Files.) When the keys have been generated, you will see a message 'DSA keys successfully generated and stored to disk.'



Screenshot: Configuring the Google Apps connector in Crowd

Step 3. Configuring Google Apps to Recognize Crowd

In this step, you will log in to Google Apps as an administrator and enter the information required for Crowd to authenticate to Google Apps. This information consists of some Crowd URLs and the public key which you generated from Crowd.

To configure Google Apps to recognize Crowd:

  1. Log in to your Google Apps Dashboard as a Google Apps administrator.
  2. In Google Apps, click Security.
  3. Click Advanced Settings.
  4. Click Set up single sign-on (SSO).
  5. Copy the URLs from the Crowd configuration screen (see above) and paste them into the Google Apps screen.
  6. Now you will upload the public key which Crowd generated for you in Step 2above:
    • Still in Google Apps, click Browse under 'Verification certificate'.
    • Navigate to the the plugin-data\crowd-saml-plugin directory of your Crowd Home.
    • Select the public key certificate (file name DSAPublic.key) and upload it to Google Apps.
  7. If necessary for your network configuration, check Use a domain specific issuer and enter any required network masks in Google Apps. Please refer to the Google Apps documentation for guidance on these settings.
  8. Save your changes in Google Apps.


Screenshot: Setting up SSO in Google Apps

Step 4. Verifying that a User can Log in to Google Apps

It is a good idea now to check that your users can log in to Google Apps.

To test a user's authentication to Google Apps:

  1. In the Crowd Application Browser, as described in Step 2 above, click the Authentication Test tab for the Google Apps application.
  2. Enter a user's login details and verify the login. For more details, you can refer to Testing a User's Login to an Application.

Congratulations! You have now configured Crowd for SSO with Google Apps.

More Information about the Google Apps Connector

Deleting the Keys

Once you have generated the keys, a Delete Keys button will appear on Crowd's configuration screen. Click this button to remove the keys from the Crowd Home directory. This will disable SSO with Google Apps.

The Ins and Outs of SSO with Google Apps

  • Single sign-on (SSO) applies only to the applications within Google Apps. The Google Apps administration section (control panel) does not support SSO.
  • When you sign out of Google Apps, you will also be signed out of Crowd and all Crowd-connected applications. This is the usual SSO behavior.
  • But when you sign out of Crowd, you will remain logged in to Google Apps even though you will be logged out of other Crowd-connected applications. (Reason: Google does not rely on a cookie, so there is no easy way for Crowd to tell Google you have signed out.)
    (info) It would take some additional development to support single sign-out from Google Apps. If you would like to see this work undertaken, please vote for issue CWD-1238.
  • If you go directly to a Google Apps application without logging in to Crowd, Google Apps direct you to a Crowd login screen.
  • The Crowd login screen for Google Apps will not offer a 'Forgotten your password' link. You cannot change your Crowd password via Google Apps. Instead, if you need to change your password please log in to Crowd directly, by going to this URL: http://YOUR-CROWD-LOCATION:8095/crowd/

Usernames must be the Same in Google Apps and Crowd

Usernames must exist in Google Apps as well as Crowd and a person's username must be the same in both Google Apps and Crowd. The Crowd Google Apps connector does not support the automatic adding of users. If a user exists in Crowd but not in Google Apps, then the user will not be able to log in to Google Apps.

Other Authentication Frameworks and SAML Support

Crowd currently supports SSO via SAML with Google Apps only. The following information is relevant to developers who may want to use Crowd's classes to develop a plugin that supports SAML authentication with other frameworks.

Crowd's SAML implementation meets the requirements for Google Apps SSO. As Google Apps supports a subset of the SAML 2.0 spec, any authentication framework that relies on the same subset should also be compatible. The Crowd implementation is capable of servicing SAML 2.0 authentication requests using the HTTP-Redirect binding. For more information on the Google Apps authentication protocol, check out their SSO documentation.

An Example of Google Apps SSO in Action

Here's one example of how it might work:

  • John raises an issue in JIRA. In the issue description, he adds a link to a Google Apps document containing more details.
  • He assigns the issue to Sarah.
  • Sarah clicks the link and opens the document directly in Google Apps. No need to log in again, no need to remember a different password.

RELATED TOPICS

Crowd 3.0 beta documentation

Last modified on Jul 11, 2017

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.