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.
Internally, versions before 1.0 used Provisioning API to get user and group list and ClientLogin to get access token to Provisioning API and validate user passwords. Since Google has deprecated that APIs, in version 1.0 we moved from Provisioning API to Directory API to get user and group list, and in version 1.1 we moved from ClientLogin to GMail's IMAP to validate user passwords, and to service accounts to get access token to Directory API.
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.
The plugin needs to use Google Directory API; one thing required to access it is a service account with proper access rights:
One or More API Scopes field paste this list of access rights the plugin needs:
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 |
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:
nc -z imap.gmail.com 993 |
or:
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).
To allow IMAP authethication with password, account in google domain must have "Allow less secure apps" enabled.
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:
Crowd
, JIRA
, JIRA on my work laptop
or whatever - Google doesn't verify this name in any way, it's just for your information);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.
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.Click Attributes tab. You have to provide the following attributes:
| license for the plugin (you can get 30-day trial license for free) |
| name of your Google Apps domain (like |
| the e-mail of the user from Administrator e-mail step |
| contents of the JSON key file downloaded in Service account for Directory API step |
| unused keys from previous versions from this plugin, you may delete them; now the JSON key does the same in much more secure way |
| 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 |
| Determines whether domain name will be appended to user and group names returned by the directory. If set to |
| Timeout in milliseconds for Google batch requests (for fetching user and group details). Default value if not provided is 5 minutes = |
| Maximum size of Google batch requests. Tweaking this value may increase (or decrease) directory speed. Valid values are |
| CPGA4C directory is prefetched and cached from time to time (Crowd calls this process 'synchronization'). This value is specified in seconds - the default is |
| 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.
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.
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;log4j.properties
file. For example, to disable logging of slow HTTP requests, add the following line to log4j.properties
:
log4j.logger.pl.craftware.shaded.org.perf4j.TimingLogger=OFF |
atlassian-crowd.log
or log4j.properties
, and for more details on logging in Crowd, see here in Crowd documentation.