Google Apps Integration (Pro)

Last modified by Administrator on 2024/12/05 00:11

Google Apps Integration (Pro)

Log in to XWiki using your Google account. Import Google Apps documents as attachments. Edit XWiki

googleapps.png
CategoryApplication
Active Installs15
Rating
0 Votes
LicenseGNU Lesser General Public License 2.1
Minimal XWiki version supportedXWiki 13.10
SourcesIssues
Table of contents

The Google Apps Integration allows you to integrate XWiki with Google's editing application (Google Docs, Spreadsheet, Presentations and Drawing). Thanks to this application it is possible to:

  • log in to XWiki using your Google account
  • easily import a Google Apps document as an attachment in XWiki (in multiple formats)
  • launch editing of an XWiki attachment in Google Apps. Once the editing session is finished you can reimport it in XWiki.

This integration uses the OAuth2 protocol to connect Google Apps with XWiki. It works with individual Google accounts as well as company wide Google Apps accounts.

To activate Google Apps you need to register for OAuth access on Google.com and insert your domain name and key in the settings from the XWki Administration. To see how you can register for OAuth access please read the dedicated section in the Installation instructions.

Once you have properly configured the application, you will be able to log in with your Google credentials and see the feature in the Attachments section of XWiki pages. You can either click on the edit link next to each attachment or use the Import from Google Apps button.

GoogleLogin.png

googleapps.png

You can also use the drive macro to insert (embed) a Google Document in your page.

DriveMacro.png

searchfordocument.png

External Resources

FAQ

How to insert the "Google Drive Macro"?

  • Create a new wiki page
  • Click on "+" > "Other Macros" on the editor bar
  • Search for "drive"
  • Select the "Google Drive Macro" and click "Submit" (no settings filled in)
  • Click to "Save and View" the wiki page
  • Next, you can click on "embed this document" and the selected document will be embedded inside the current page

How to sync the XWiki profile with the Google Account information?

On the Administration section, the "Permissions to request" options allow the user to specify which information will be copied from the Google Account to the XWiki profile upon login.
PermissionsToRequest.png

For the example below the first name, last name, email and user image were imported from the Google Account.
GoogleApps_profile.png

How to embed a document using the drive macro?

Once you have added the {{drive/}} macro to the wiki pages, you can search for the document to embed inside the Drive:
DriveMacroSearch.png

Upon click on the link "embed this document" the selected document will be included on the page.
EmbeddedDoc.png

How to import a document?

The "Import from Google Apps" feature is available on the "Attachments" tab.
ImportFirstStep.png

The user can search for the document inside his drive.
SearchDocumentToImport.png

Upon click on the desired format. the document will be added as an attachment to the page. PDF in the selected format in the example below.
ImportedFromGoogleApps.png

How to restrict the domain of the users allowed to login to the Wiki?

On the Google Apps Integration Configuration section the domain of the users allowed to login can be restricted by filling in the field XWiki Login Behaviour>Domain. For example, when using xwiki.com only emails like user@xwiki.com will be allowed.
GoogleApps-RestrictDomain.png

Users outside the domain will be informed as below:
GoogleApps-DomainMessage.png

Installation Steps

This paid extensions requires XWiki 13.10 or above. In order to install the extension, follow the next steps inside your XWiki instance (on cloud or on premise).

Navigate to the Extension Manager

In the Applications Panel click on "More Applications..." and then "Install new applications...". Alternatively navigate directly to the Administration and select the "Extensions" section.

step1.png

Install the Extension

Search for the extension you wish to install and use the Install button to install it.

step2.png

Get a License

Navigate to the "Licenses" section of the Administration, fill your details, look for the extension you just installed in the live table and click the buttons to get a trial license or to buy a license.

step3.png

Install the License

If you have selected a trial license then you're good and there's nothing else to do. Your trial license is automatically installed.

However if you've selected to buy a license you'll be redirected to a page to perform the payment. At the end you need to come back to the "Licenses" administration section and click on the "Check for Updates" button. This will download and apply the license you bought.

Use the Extension

Start using the Extension! Refer to the extension's documentation to know how to use it.

Installing Paid Apps on Subwikis

If you want to install an application on the whole farm (main wiki + subwikis), you can do so directly from the main wiki’s Extension Manager, as seen below:

step4.png

Extensions can also be installed only on a particular subwiki by global admins. Subwiki admins will not be able to install these extensions due to their limited rights.

Required Installation Steps on the Google Console

The Google Apps Integration Pro app requires a few settings in order to be able to connect to your wiki using a Google account. You first need to register for OAuth access on the Google Console. See below the steps in details applied in 3 cases: a Cloud wiki, a local instance using localhost and another local one using a custom alias. Most of the steps are the same, what would differ would be the Authorized URIs and links listed under the App Domain.

Step 1: Create a Google project for your Google Apps Integration Pro app

Go to https://console.cloud.google.com/ (see also https://developers.google.com/identity/protocols/oauth2?hl=en for more details about OAuth protocol). Create a Google project for your app as shown below:

new-project.png

Step 2: Enable the Google People API

Moving forward, you will need to Enable the Google People API. This API is needed to access the Google account information. To enable it go to the project's API & Services section, on the Dashboard, click on ENABLE APIS AND SERVICES, search for Google People API and click ENABLE.

AddPeopleAPI.png

Step 3: Enable the Google Drive API

This API is needed to access Google documents. Similarly, to enable it go back to the dashboard and click on ENABLE APIS AND SERVICES, search for Google Drive API and click ENABLE.

GoogleDriveAPI.png

Step 4: Settings on the OAuth Consent Screen

Pick the Internal option to make the Google login option available only to users within your organization. When picking the Internal users type you will be able to use the integration of both http and https installations. While, if you pick the External users type the integration will work on a http installation only in testing mode, but when passing on production it will work only with https installations. 

OAuth-consent-screen-target-users.png
Select the type of users you want to target with this project

Then, fill in the following fields:

  • Application name (to be used later on the Google Apps configuration page within Other section of the wiki administration)
  • Authorized domains (in our examples we added "xwiki.com")
  • Application Homepage link (we added the link towards the Main page of the standard XWiki)
  • Application Privacy Policy link (we added the link towards the standard Help page in XWiki)

OAuth-consent-screen-Web-Application-name.png
Example with a Cloud wiki

We tested as well on XWiki 12.10.8, Long Term Support version, recommended for production, with the Google Apps Integration Pro version 2.4.10, the case of using a local wiki with localhost on the App domain fields and as Authorized URIs. The login with Google was successful.

oauth-consent-screen-localhost.png
Example with localhost links on a local wiki

In case you are using an older version of the Google Apps Integration Pro than 2.4.10, you might experience an issue where Google does not accept localhost in the App domain fields. You could then use an alias, for example apps.xwiki.com instead of localhost. Depending on your OS you will need to also update the hosts file to which you should add the following IP/Alias pair: your IP   your Application Homepage link (e.g. 127.0.0.1   apps.xwiki.com). The Application Homepage link would look like http://apps.xwiki.com:8080/xwiki/bin/Main/ and the Application privacy policy link http://apps.xwiki.com:8080/xwiki/bin/view/Help/.

Step 5: Generate the Google Client ID and Secret Credentials

The final step here would be to generate OAuth Credentials: the Google Client ID and Secret, that will then be added to the Google Apps Configuration page. Thus, after setting up the OAuth client go to Credentials and click on Create credentials > Create OAuth client ID.

Then, select "Web Application" and fill in a name, and the Authorized redirect URIs. The Authorized redirect URI needs to end with GoogleApps/Oauth. Make sure you hit enter after filling in the Authorized redirect URI, otherwise the value will not be saved. Then click the Create button. 

ClientIDWebApplication
Example of Authorized URI for the apps.xwiki.com wiki alias

A popup will appear with the Client ID and Client Secret, but you can reaccess them from Credentials in your Google Console Project.

IDSecret.png

See below an example with fictional Client ID and Secret (for security reasons) and Authorized redirect URIs used when wanting to login with Google from a main wiki or from subwikis. It would require to install the Google Apps Integration Pro application on both the main and the other subwikis where you'd like to use this login option. The same Application name (set in the previous step), Client ID and Secret will need to be used on the Google Apps configuration page on your subwikis (see the following step for examples).

OAuth-Client-ID-Credentials-Authorized-URIs.png
Example of Authorized URIs, on a Cloud wiki, when the Google Login is configured on both main and other subwikis

For the local wiki using localhost, the Authorized URI would look like: http://localhost:8080/xwiki/bin/view/GoogleApps/OAuth.

Required Configuration on the Wiki side

Activate the Google Authentication

In order to activate the Groovy Authentication, you need to update the following settings in the xwiki.cfg file (webapps > xwiki > WEB-INF) and restart the wiki:

xwiki.authentication.authclass=com.xpn.xwiki.user.impl.xwiki.GroovyAuthServiceImpl
xwiki.authentication.groovy.pagename=xwiki:GoogleApps.AuthService

If you are an XWiki Cloud user, you do not have direct access to this file. You will need to contact the XWiki Support team to perform this change for you.

In addition, if you want to uninstall the Google Apps Integration (Pro) from your wiki, don't forget to remove these settings from the xwiki.cfg file.

Complete the Google Apps Integration Configuration

Next you will need to update the Application Name, Client ID and Secret inside the XWiki Administration, the Other section, Google Apps tab. If you want to use Google login on both main and other subwikis, you would need to install the app on all of them and complete the configuration with the same details.

GoogleApps-Administration-XWiki.png
Example of Google Apps configuration on the apps.xwiki.com wiki

Here is an example from the Google Apps configuration on the Cloud main wiki:

configuration-main-wiki.png
Example of Google Apps configuration on the Cloud main wiki

For the local wiki using localhost, you would need as well the same details, in our example being: the Application name - Local wiki and, of course, dedicated Client ID and Secret.

Limitations that are affecting the application

Concerning Unregistered Users Rights

If the option "Prevent unregistered users from viewing pages, regardless of the page rights" from the wiki administration > Users & Rights > Rights is checked, it prevents Google Apps Login from working.

At the moment, the recommendation is to preventing the access to guests as a workaround until the issue is fixed. Here is how to deny the access rights specifically for Unregistered users :

  • On the wiki administration, Users & Rights section, Rights tab, pick the Users option deny the rights for Unregistered Users as seen below. The checkbox "Prevent unregistered users from viewing pages, regardless of the page rights" needs to be unchecked.
    UsersRights.png

Concerning the Active Directory Application

If you have the Active Directory Application installed, the Google Apps integration will not work. The reason is that this application overwrites the configured authenticator.

To try out the Google Apps integration you will need to uninstall the "Active Directory Application", but also the "Active Directory Authenticator" extension. Note that uninstalling only the "Active Directory Application" is not enough because the authenticator is a dependency of the application and the Extension Manager doesn't uninstall the dependencies when you uninstall the application.

You may also need to clear the cookies associated to the domain used by your XWiki instance, then try again to sign in with Google.

Options

The price is per year and varies depending on the support level and the number of users.

Support / Users 10 25 50 100 250 500 1000 2500 5000 10000 20000
Silver
Google Apps Integration (Pro) is part of the XWiki Pro package. Purchasing this package you will benefit from more extensions at a better price. Check the full offer in XWiki Pro! The Google Apps Integration (Pro) can be purchased individually only via online order (credit card payment), following the “How to Buy” procedure described below. The application is part of the XWiki Pro package, which can be purchased through manual order (bank transfer payment) by contacting sales@xwiki.com.

Benefits

What do you get when you purchase an XWiki extension?

1 year license

By purchasing an XWiki extension license, you'll benefit from it during one year.

Free updates

You benefit from all the extension updates during one year. You are always up to date.

Support included

If you are facing an issue, you can reach the XWiki support. Our team is always available to help.

How to Buy

To buy, install this extension from inside your XWiki instance and follow the instructions.

Release notes

v2.6.1

Upgrades:

  • #78 Upgrade Licensor dependency to version 1.25

v2.6

Bugs fixed:

#66 Picking the "original" option when trying to import a file from Google Apps is showing an error

#67 Edit with Google Apps button is not shown on the Attachments livedata table

Tasks done:

#68 Upgrade parent to 13.10-3

Upgraded licensing version to 1.24.1.

v2.5.2

Update the Licensing dependency version to 1.22

v2.5.1

Upgrade the licensor version to 1.20

v2.5

Update parent version to 11.10.

v2.4.10

Bugs fixed:

#60 XWiki "Login with Google" doesn't work

v2.4.9

Bugs fixed:

#59 Bypass trusted domain check when using redirect API 

v2.4.8

Bugs fixed:

#58 Authentification fails when photo has a name too long
#56 Google login branding
#55 `doc` files are not supported to sync with GoogleApps
#23 Buttons with FR or DE language aren't appearing correctly

v2.4.7

Bugs fixed:
#52: Typos.

v2.4.6

Bugs fixed:
#48 Opening links from TestDocumentList display an error.
#50 Cannot login with Google anymore.
#51 GData cannot be used to download anymore.

Improvements:
#53 Settings page should only be viewed by admins.

v2.4.5

Bugs fixed:
#43 GoogleApps breaks if getURL results to absolute URLs.

v2.4.4

Bugs fixed:
#37 Restrict domain for users to login doesn't work.

v2.4.3

Bugs fixed:
#33 Legacy People API needs to be activated.

v2.4.2

Update the Licensing dependency to version 1.14.3.

v2.4.1

Bugs fixed:
#26 Can't install Google Apps.

v2.4

Bugs fixed:
#16 Can't access any document from the Drive while using a "http" instance.
#22 Google Apps Integration shouldn't appear in Navigation on 8.4.5.

Improvements:
#13 Automatically import user photo from google account.
#18 Incomplete localization.
#19 Warn if the authenticator is not configured.

Update the Licensing dependency to version 1.14.3.

Updated translations:

  • French

v2.3.5

Update the Licensing dependency to version 1.13.2.

v2.3.4

Bugs fixed:
#4 Fix the google links from the Administration section.
#9 Extension's homepage description contains a broken link to Google Apps admin section.

Update the Licensing dependency to version 1.13.1.

v2.3.3

Update the Licensing dependency to version 1.13.

v2.3.2

Update the Licensing dependency to version 1.12.2.

v2.3.1

Update the Licensing dependency to version 1.12.1.

v2.3

Improve the message displayed when there is no valid license.
Update the Licensing dependency to version 1.8.

v2.2

Initial paid version.

Extension details

This information is only displayed to Administrators. Your users can't see this tab.

License

  • GNU Lesser General Public License 2.1

Sources

Issues

Type

  • xar

Developed by

Compatibility

  • Requires XWiki 13.10 or above.

Installable with the Extension Manager

Dependencies

  • com.xwiki.licensing:application-licensing-licensor-api 1.25
  • com.google.api-client:google-api-client 1.23.0
  • com.google.apis:google-api-services-people v1-rev443-1.23.0
  • com.google.apis:google-api-services-drive v2-rev358-1.23.0