Versions Compared

Old Version 64

changes.mady.by.user Mikołaj Mitura

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

Introduction

Google Apps for Crowd is a plugin for Atlassian Crowd, which makes it possible to reuse your user database from Google Apps domain in any application which can connect to Atlassian Crowd user database.

...

Because of introduction of the service accounts, unfortunately the administrator of your Crowd server needs to do some extra configuration during upgrade to 1.1 version; but thanks to this the authentication process to Google APIs is safer: you don't have to give real password to Google Apps domain to get user and group list, just a 'per-application' password (JSON key) for this service account is enough. From end user perspective nothing changes - they can still login using their Google Apps login and password as they did before.

Just like 'per-application passwords' for service accounts, the plugin also supports Google 'per-application' passwords for end-users to improve security. More information on that is provided here.

Anchor
Google Apps domain configuration
Google Apps domain configuration

Google Apps domain configuration

Anchor
Service account for Directory API
Service account for Directory API

Service account for Directory API

The plugin needs to use Google Directory API; one thing required to access it is a service account with proper access rights:

...

      • Go to Security > Show More > Advanced settings > Manage API client access;
      • In the Client Name field paste value Client Id of the service account created in developers console;
      • In the One or More API Scopes field paste this list of access rights the plugin needs:

 

Panel
https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly

 

      • Anchor
        Administrator e-mail
        Administrator e-mail
        Click Authorize.

Administrator e-mail

Additionally, the service account needs an e-mail of an administrator user which has access rights to read user and group information from the Google Apps domain.
The final access rights to the domain given the plugin are logical AND of the access rights of the service account you set above, and the access rights of the administrator user you'll use with this service account. You can just use the default Google Apps administrator account (it's available at Company profile > Primary administrator account) - it's still secure because of this AND-ing of access rights you can always revoke access rights for the service account. Alternatively you can create a dedicated user and assign it an administrator role with rights to read user and group information.

Anchor
imap for authorization of users
imap for authorization of users

IMAP for authorization of users
Anchor
IMAP for authorization of users
IMAP for authorization of users

  • In Google Apps Administration Console check if GMail is enabled: Apps > Google Apps > GMail(enabled by default);
  • Every user needs to enable IMAP on their GMail account: GMail > Settings > Forwarding and POP/IMAP > Enable IMAP (enabled by default);
  • Enable IMAPS port (993) on your firewalls so that the plugin on your Crowd server can check user passwords (probably enabled by default by your administrators).

    • (optional) If you're unsure if this port is open correctly, just try this shell command on that machine: 

      Code Block
      nc -z imap.gmail.com 993

      or:

      Code Block
      echo "" | telnet imap.gmail.com 993

      (immediate exit from this command with no error means that the port is open, long waiting for connection and/or error like "Unable to connect" or "Connection timeout" means that port isn't open).

 

Allow less secure apps: ON

To allow IMAP authethication with password, account in google domain must have "Allow less secure apps" enabled. 

 
Anchor
2-step verification (optional)
2-step verification (optional)

2-step verification (optional)

To improve security, the plugin partially supports 2-step verification for end users: things like SMS codes won't work with applications that use Crowd for authentication, because those applications display their own login window instead of using the one provided by Google. However instead of that, your end users can use per-application passwords. To use them each user should follow these steps:

    • In Select application field choose Custom;
    • Give it any name (like Crowd, JIRA, JIRA on my work laptop or whatever - Google doesn't verify this name in any way, it's just for your information);
  • Use the generated per-application password to login to that application. Because the password is machine-generated, usually it's best to use options like Remember me or Save password in the application and the web browser;

  • When you suspect an unauthorized access to an application using one or more of your application passwords (for example when your laptop was stolen), go again to the application passwords page (Google may ask you for SMS codes for better security), Cancel those passwords and generate and use new ones. It can also be a good idea to always regenerate the passwords from time to time.

Anchor
Crowd directory configuration
Crowd directory configuration

Crowd directory configuration

  • Open Crowd Administration Console in your web browser in new tab (to be able to return to Google Apps domain settings easily if they're wrong);
  • Click the Directories link in the top navigation bar;
  • Click Add Directory. 
  • Click Custom.
  • In Name field give your directory a name.
  • In Implementation Class input you have to put fully qualified class name of custom directory. The add-on provides two types of the directory:
    • pl.craftware.crowd.directory.GoogleAppsDirectory - directory that disallows local Crowd groups to be used with Google users;
    • pl.craftware.crowd.directory.GoogleAppsWithLocalGroupsDirectory - directory that doesn't have this limitation.
  • Type one of them and click Continue.


  • Click Attributes tab. You have to provide the following attributes:

plugin.license

 license for the plugin (you can get 30-day trial license for free)

google.apps.domain

 name of your Google Apps domain (like example.com)

google.apps.admin.email

 the e-mail of the user from Administrator e-mail step

google.apps.serviceaccount.jsonkey

 contents of the JSON key file downloaded in Service account for Directory API step

google.apps.admin.password, google.api.key (unused)

 unused keys from previous versions from this plugin, you may delete them; now the JSON key does the same in much more secure way

google.apps.group (optional)

 Name of Google group, used to filter users. If provided then only users from that group will be shown in the directory. If blank, then all users will be displayed

plugin.sync.withDomain (optional)

 Determines whether domain name will be appended to user and group names returned by the directory. If set to true, domain name will be appended (e.g. user@example.com), if false or empty, it won't be (e.g. user). 

google.apps.batchRequestReadTimeout (optional)

 Timeout in milliseconds for Google batch requests (for fetching user and group details). Default value if not provided is 5 minutes = 300000 milliseconds. If you'll ever get java.net.SocketTimeoutException: Read timed out, increasing this value may help.

google.apps.maxBatchRequestSize (optional)

 Maximum size of Google batch requests. Tweaking this value may increase (or decrease) directory speed. Valid values are 1 - 1000, and 100 is the default.

directory.cache.synchronise.interval (optional, since 1.2.0)

 CPGA4C directory is prefetched and cached from time to time (Crowd calls this process 'synchronization'). This value is specified in seconds - the default is 3600 (1 hour). If synchronization of your directory takes too long or you exceed Google Admin SDK daily quota, you can increase this value eg to 2 hours (7200). If you think your directory is synchronized too rarely, you ma try decreasing it eg to 30 minutes (1800).

com.atlassian.crowd.directory.sync.laststartsynctime 

 Remove this property (if exists) to apply your changes immediately during next directory action, without waiting for next directory.cache.synchronise.interval

  • Click Update.

  • Open new web browser tab and inside it configure JIRA and/or other apps to use this directory.

  • Go to the Authentication Test tab inside the application configuration web browser tab, and test whether users can login to the app with their passwords.

    • If there's something wrong, you'll get an appropriate error message in this window (in a real application login window it's typically hidden for security reasons). Then you can go back to the directory settings browser tab, or to the Google Apps domain configuration browser tab to fix what's wrong. If the error message on the screen doesn't say anything to you, check FAQ and logs.

    • If you change directory settings, you have to remember to remove com.atlassian.crowd.directory.sync.laststartsynctime and then rerun the authentication test to make sure the new settings are applied immediately.

Anchor
Crowd logging configuration
Crowd logging configuration

Crowd logging configuration

Crowd logging can be changed as described here.

All logs from this add-on and libraries it uses reside in the file atlassian-crowd.log. By default INFO log level is enabled, sometimes when there's a problem with the plugin it's too little to find the reason and you have to to increase log level of some logger, or when some logger produces too much data, you have to decrease its log level. The most interesting loggers are:

 
  • pl.craftware.cpga4c - logs from the add-on;
  • pl.craftware.shaded.com.google.api.client.http.HttpTransport - HTTP requests issued to Google servers;
  • pl.craftware.shaded.com.google - logs from Google libraries the plugin uses;
  • pl.craftware.shaded.org.perf4j.TimingLogger - HTTP requests which are too slow;
  • pl.craftware.shaded - logs from libraries the plugin uses;
  • pl.craftware - logs from the add-on and libraries it uses;
 
The configuration happens in log4j.properties file. For example, to disable logging of slow HTTP requests, add the following line to log4j.properties:
  

 

Code Block
log4j.logger.pl.craftware.shaded.org.perf4j.TimingLogger=OFF
For the exact locations of atlassian-crowd.log or log4j.properties, and for more details on logging in Crowd, see here in Crowd documentation.
 



...