Welcome and thanks for downloading the Google Apps Plugin for WordPress. The instructions on this page presume you have installed one of the Free, Premium, or Enterprise versions of the Google Apps Login plugin and are now attempting to configure the plugin from the ‘Google Apps Login’ page under ‘Settings’ in your WordPress admin area.

We will guide you through registering your site with Google Developers Console (which you will need to do unless the plugin has already been able to pull the settings through from the free version of the plugin while, upgrading to Premium/Enterprise). Please note that your version of the Google Developers Console may vary slightly.

Configuration

Within WordPress, start from the page Settings -> Google Apps Login – which is where you probably followed the link to this instructions page.

The G Suite (Google Apps) domain admin needs to go to https://console.developers.google.com/ (link will open in a new window). If you are not the domain admin, you may still be able to use the console, just use your regular Gmail account to access the console if you are not using G Suite (Google Apps)

In the Google Developers’ Console, click on ‘Select a Project’ dropdown box at the top (this dropdown may show the name of an existing project instead). For more clarification please see the screenshot given below.

When you click on the drop-down menu you will get a pop-up screen where you can find an option to create a new project on the top right corner. Click on the New Project. For more clarification please see the screenshot given below.

When you click on the new project link, you will be redirected to the new page where you can write your project name and select the organization hierarchy. Please write the project name and click on create. For more clarification please see the screenshot given below.

Once you click one create button google console start process to create a project for you please wait until the google console completes the creating project for you. After the completion of the process, you will be notified that the project is created. Please see the screenshot given below.

Click on the project creation notification or select from the Project drop-down menu, you will be redirected to the dashboard screen of the selected project.

Now click on the menu icon from the top left corner and mouse hover on APIs & Services then click on the OAuth consent screen menu item. When you click on the menu item the screen looks like the screenshot given below.

Please select the appropriate option as per your requirement and then click on the create button.

You will get a form where you need to write Application Name and mention all your domains underneath the title authorized domains, this is to notify that on which domains you are going to use this application. For more clarification please see the screenshot given below.

After saving this form, please click on the credentials menu to find the option called Create Credentials on the top. Click on it and select the option OAuth Client ID. For more clarification please see the screenshot.

Once you select the OAuth client ID, you will be redirected to the page where you can select the application type. This is to select the platform you are going to use this OAuth 2.0 protocol. Please select the web application option. Once you select this option you will get a form where you can write the OAuth application name and you must have to define the Authorized JavaScript origins and Authorized redirect URLs then click on create button. For more clarification please see the screenshot given below.

Once creating the OAuth application process done you will be notified with the popup where you can find your Client ID and your Client Secret Key. For more clarification please see the screenshot given below.

You must copy and paste these values of the Client ID and Client Secret key into the boxes back on the WordPress plugin settings screen – i.e. back in your WordPress admin, under Settings -> Google Apps Login. For more clarification please see the screenshot given below.

If you plan to use our Google Drive Embedder extension plugin, then you will also need to enable the ‘Drive API’ and ‘Calendar API’. To enable these, in the Google Developers Console, go back to APIs & Services and click Library from the left-hand menu bar.

Search for each of Drive API and Calendar API and click into them so you can click the ‘Enable’ button.

If you are using the Enterprise version of Google Apps Login, you will also need to enable Admin SDK.

All done! Save the settings in your WordPress admin, then try logging out. You should now see a ‘Sign in with Google’ button on your WordPress login page.

For certain extensions (Google Apps Directory, or the Enterprise version of Google Apps Login) you may also need to follow the instructions to set up a service account. If in doubt, please ignore for now.

Next Steps

If you have purchased the Premium or Enterprise version of the plugin, please move on to the Premium Setup instructions to understand how to make use of the premium/enterprise features that automatically restrict access to users on your own G Suite (Google Apps) domain, including auto-creation of users.

You can also learn about the (free/premium/enterprise) plugin’s Advanced Options and Multisite capabilities.

Adding the ‘Login with Google’ button to any page on your site

The easiest way to add a Login with Google button anywhere on your site is to add the following link anywhere you would like a customer to be able to “Login with Google”:

/wp-login.php?gaautologin=true

For example, in HTML:

<a href="/wp-login.php?gaautologin=true">Login with Google</a>

This would have to leave the current page in order to go through the Google login flow. However, depending on how your site is set up, this may not land on the page you expect after Google has authenticated. To control the page it returns to after authentication, try adding a redirect_to parameter as follows in this example:

/wp-login.php?gaautologin=true&redirect_to=http://mysite.com/comebackhere/

(the redirect_to should really be URL-encoded, but it will often work if you can’t do this)

Hiding the ‘Login with Google’ button from the wp-login.php page

You may have only installed Google Apps Login in order to use an extension plugin such as Google Drive Embedder, but not actually want your users to see the ‘Login with Google’ button on your login page (nor be able to use its functionality).

There is no native way to turn off the Login functionality, but it should be possible to add some CSS code to your Theme to override the styles and hide the login button etc.

You could add the following CSS to your child theme’s style.css file:

form#loginform p.galogin, form#loginform p.galogin-powered, form#loginform p.galogin-or, form#loginform h3.galogin-or {
    display: none !important;
}

The above is a suggestion based on the default WordPress configuration, but hopefully you can adapt to match your theme if needed – or your web designer can do this for you.

If your theme’s styles aren’t pulling through to the login page, you might need to write some code to inject the CSS directly, perhaps from your Theme’s functions.php file:

function my_login_styles() {
?>
  <style type="text/css">
    form#loginform p.galogin, form#loginform p.galogin-powered, form#loginform p.galogin-or, form#loginform h3.galogin-or {
        display: none !important;
    }
    </style>
<?php
}

add_action('login_enqueue_scripts', 'my_login_styles');

Please remember to keep a backup copy of functions.php since entering the code incorrectly could break your site.

If you use the Theme My Login plugin (TML) to create a custom styled login page on your site, please be aware that since TML adjusts the way the login process works in WordPress, plugins like Google Apps Login that are expecting WordPress standards may not work.

An approach that will not disturb WordPress’ standard login mechanism so much would be to use a plugin that styles the existing wp-login.php page instead of creating a new login page, but of course this might involve more work to achieve something that matches your Theme. Our recommended plugin for this approach is Admin Custom Login, and this is directly compatible with Google Apps Login.

If you would like to attempt to get TML to work on your site, here are the suggested steps:

1. Specify both Authorized Redirect URIs in the Google Developers Console Project when you configure Google Apps Login:

http://www.website.com/wp-login.php
http://www.website.com/login
http://www.website.com/login/

Above, I’ve added two versions of the /login URL just in case. You would add these under API’s & Services -> Credentials -> OAuth 2.0 IDs. Click into the ‘web application’ ID you set up when you first configured the plugin.

2. Add the below code in functions.php in the Child theme or similar – of course change for your site’s wp-login.php URL:

function my_gal_login_url($login_url) {
  return 'http://website.com/wp-login.php';
}
add_filter('gal_login_url', 'my_gal_login_url', 10, 1);

The above steps may be enough, but if the ‘Login with google’ button doesn’t appear on the login form try step 3 below only (not step 4). If it appears but you sometimes get ‘session mismatch’ errors, please try both steps 3 and 4.

3. Add this link URL as ‘Login with Google’ on the TML login page (below theme_my_login shortcode):

http://website.com/wp-login.php?gaautologin=true

4. Hide the original ‘Login with Google’ button in Child theme CSS:

p.galogin, h3.galogin-or {
  display:none;
}

Some users have found that ‘Login with Google’ just returns them to the wp-login.php page with no error message showing, but actually if they then visit /wp-admin/ they find they were actually logged in (just not redirected to the dashboard as expected). If this happens to you, follow step 5:

5. In TML settings, uncheck ‘Enable custom redirection’ and maybe some other security settings.

If you would like any help, or want to report your own findings, please contact support.

Of course if you aren’t in a position to get your hands dirty with the detailed configuration required, the short answer is that I don’t think TML works alongside Google Apps Login straight out of the box!

When a user tries to Login with Google, it says “user is not registered in WordPress”

The free version of the plugin allows existing WordPress accounts to login using Google credentials, but it will not create accounts if they do not already exist in WordPress. I presume there is no WordPress account with the email address that corresponds to the Google account attempting to login.

You would need to purchase the premium or enterprise versions of the plugin if you want to sync users from a Google Apps domain to WordPress – i.e. to auto-create WordPress users for anyone with a Google account on your company’s domain, and to ensure that users can no longer login to WordPress after their Google accounts are deactivated.

If you’re already using the Premium or Enterprise version, please ensure the Domain Control tab in Settings -> Google Apps Login is set up correctly, including the ‘Auto-create users on my domain’ checkbox being checked.

I can’t login to WordPress at all any more!

Plugins sometimes conflict with each other, or configuration is incomplete, so you find you can’t access your WordPress site. For that reason, it is important to have a way to remove plugins and perform other low-level resets if needed.

If Login with Google isn’t working, you should still be able to enter your regular WordPress username/password to access the site. (Unless you have selected the option to forbid this for accounts in your Google Apps domain, in the premium or enterprise versions.)

If you have set your site to automatically login with Google, you can override that behavior by going to the following URL on your site:
/wp-login.php?gaautologin=false&gahidewplogin=false

If you still can’t login, after resetting your WordPress username and password, you should start to disable some plugins that are likely to be causing a problem. Of course you can’t access your Plugins page in WordPress admin, so you will need access to your server’s database or file system.

Here is a useful guide explaining what to do, courtesy of WP Beginner.

If you have Google Apps Login Enterprise installed, and you have accidentally configured the Domain Control tab in a way that means none of your users is an admin user any longer, you may need to change your user back to being an admin via MySQL. See here for instructions.

I install the plugin, and my wp-login.php page is just blank

The only time we’ve seen users experience a blank screen has been because they don’t have CURL enabled on their server.

Read this article describing how you can debug and (hopefully) get an error message to see if that is the problem.

Or, since most often the problem is that CURL needs installing, it may be easier for you to jump straight to finding out whether CURL is installed, and enabling it if not. If that doesn’t solve the problem, you may need to debug as above.

Users sometimes can’t login because Google chooses their personal Gmail account

Here’s what happens whenever you click Login with Google, and it depends how many Google accounts are currently logged-in within the same browser:

1. If currently logged in to 0 Google accounts, you will be asked to login to one and the plugin will attempt to login to WordPress against that account
2. If currently logged in to exactly 1 Google account, Google will automatically return that account for the WordPress login attempt
3. If currently logged in to 2 or more Google accounts, Google will show the user a list of current accounts and allow them to choose which one they want for the WordPress login

Then, if the selected Google account doesn’t match an existing WordPress account and doesn’t come from a Google Apps domain that is authorized in the plugin to have a WordPress account created for it, the user will be told:

Email address needs to be in mycompany.com. person@gmail.com is not authorized – Sign out of Google to switch accounts

If this is causing confusion, one possibility is to tick the option in Advanced Options of Settings -> Google Apps Login labelled ‘Force user to confirm Google permissions every time’. This adds an extra step to everyone’s login flow asking them to confirm they are happy for Google to connect to the WordPress site (by default, they only see this the very first time). The only reason for this option is to give the user a chance to see (in the top right corner) which Google account has been picked up, and give them the opportunity to change it.

When attempting ‘Login with Google’ I see Invalid JSON in service response

After clicking ‘Login with Google’, and authorizing your Google account, you are redirected back to the WordPress login page and see the error message: Invalid JSON in service response: <followed by a load of strange characters>

This is because Google has recently started compressing some of their responses from their API calls, and older servers are unable to interpret it.

Please ask your web host if they can update to a newer CURL version that has libz/gzip/idn enabled.

Server-side Caching no longer works on my site

Google Apps Login attempts to set its wordpress_google_apps_login cookie on every page of your site. This cookie is only really needed on the wp-login.php page, but many sites have unusual configuration of the login page, so by default the plugin sets the cookie on every page. This can affect some server-side caching systems which turn off caching because this cookie is different for each user.

You can instruct the plugin to only write the cookie on the wp-login.php page in the first place, and this should fix the cache for the rest of your site.

We have instructions providing code that you can add to your Theme’s functions.php file or similar.

If you are using Google Apps Login Enterprise version on a WordPress multisite installation, please get in touch with us. We have an extension plugin available that will allow you to override Group Role Rules on a sub-site basis.

Domain Control tab – multisite options

In a multisite installation, there are two extra settings on the Domain Control tab:

‘Add users to sub-sites if they are not yet members’ – if checked, this will always add all users as members to all sub-sites whenever the role mapping rules are processed for a user. In this case, the user will be added to each sub-site under the role determined by the rules you’ve set up. If not checked, the role will only be applied to the user in sub-sites of which they are already a member (which will likely be no sites for a new user, unless you have some other plugin to take care of sub-site membership assignment).

The point here is that under WordPress multisite, the user exists once globally (i.e. throughout the whole multisite), but can be added as a member to each sub-site independently of the others; and furthermore the user can have different roles in each sub-site. For example, the user could be a subscriber in sub-site 1, an admin of sub-site 2, and not a member at all of sub-site 3.

‘Demote existing Super Admins who do not have a Super Admin mapping above’ – if checked, the plugin will happily remove super admin privileges if the Domain Control rules determine that the user should have a role other than Super Admin. Leave checked (default) if you think that’s risky – i.e. it’s too easy to insert an extra rule that maps a super admin to something else. If it remains unchecked, you would have to manually demote any super admin that is no longer required on the multisite.

In WordPress multisite, super-admin is a different type of role to all the others – it applies globally, whereas the lesser roles can be assigned to any other member of any sub-site independently of the others.

Advanced Options – multisite Redirect URIs

In all versions of Google Apps Login, the Advanced Options tab contains an extra option related to multisite Redirect URIs. See here for more details.

Advanced instructions for WordPress Multisite installations

By default, all logins need to be submitted via the root site’s wp-login.php page (since that is the only Redirect URL you were asked to submit to Google Developers Console when you first set up the plugin). That should be fine to get you started, so please just try it out, but you may find that users are sometimes redirected to unexpected pages, depending on where on your network of sites they decided to login.

If have a small number of sub-sites, and new sub-sites are not expected to be added often, you might prefer to register additional Redirect URLs with Google for each of your sub-sites, in addition to the root site you were asked to enter when you first configured the plugin.

If you are using ‘domain mapping’ so that your sub-sites are on completely separate domains, you will need to add each site’s login page as its own Redirect URL.

For example, you may end up listing all of https://mywpsite.com/wp-login.php, https://mywpsite.com/subsite1/wp-login.php, and https://mywpsite.com/subsite2/wp-login.php as Redirect URLs in the Google Developers Console.

You will then need to check the box in the Multisite Options section of the plugin’s admin panel labelled Use sub-site specific callback from Google. This will cause all logins submitted to the sub-site they were invoked on.

If you are using the Enterprise version of Google Apps Login, there are further multisite considerations described here.

Advanced Options

You and your users will be able to use Google Apps Login perfectly fine if you simply ignore the Advanced Options section. However, there are two options, plus an extra little trick, that will allow you to customize the exact login flow as you desire.

Force user to confirm Google permissions every time

If checked, users will have to fully authorize your site to Google every time they login. This may make the login flow clearer for users who are currently logged into exactly one Google account, and also gives them the chance to login to a different Google account instead. However, the login flow is quicker if you leave this unchecked.

Automatically redirect to Google from login page

If checked, all users will be automatically forwarded to the Google login flow when they access the /wp-login.php page. If your users only ever use ‘Login via Google’, this saves them having to click that button on the login page to initiate the process.

Login page redirect override

It is not a setting in itself, but a trick that you may use to override the behavior of the last setting described (i.e. Automatically redirect to Google from login page). Whether or not that setting is checked, you can send users to /wp-login.php?gaautologin=true to ensure the automatic redirect happens. Likewise, you can send users to /wp-login.php?gaautologin=false to ensure the full WordPress login form is displayed, giving them the choice of username/password or ‘Login via Google’, regardless of the Automatic redirect setting.

This can be useful if you want, for example, a link in your sidebar advertising the Google Login functionality as a direct link, without forcing it on all users at all times.

Display ‘Powered By wp-glogin.com’ on Login form

Uncheck this to remove the attribution link on your login page. Of course we are thrilled if you want to spread the word about our product, but it’s no problem if this is not appropriate for your site. It can also be useful for future admins of your site to understand immediately how you have implemented Login with Google, and to come to us for support.

Automatically logout of Google when logging out of WordPress

Premium/Enterprise only. When ‘Automatically logout of Google when logging out of WordPress’ is checked, logging out of WordPress returns users to the WordPress login page as usual, indicating they are now logged out. And it also displays a widget counting down from five seconds before it will redirect automatically to the Google logout pages.

If the user wants to remain logged in to Google, they can click the widget’s cancel button before the five seconds are up!

Login button text

Premium/Enterprise only. Enter some text in the box next to ‘Login button text’ to change the text shown in the ‘Login with Google’ button on the WordPress login page. For example, you could change it to say ‘Company Email Login’.

Multisite Options

The Multisite Options section of the plugin’s admin panel contains an option named Use sub-site specific callback from Google. This is explained in our Multisite instructions.

The instructions on this page assume you are using the Enterprise version of Google Apps Login and have already followed the setup steps that apply to all versions, followed by the instructions specific to the Premium (and also Enterprise) version which you can read here. This page explains more about the Enterprise plugin’s granular user role controls.

Setup a Service Account

To ensure all users in your domain can call the Google Groups API, the Enterprise version of Google Apps Login plugin requires you to complete an extra setup step.

If you haven’t already created a Service Account when you configured the plugin, then you will not see the Service Account email address and Private key fingerprint towards the bottom of the Main Settings tab in Settings -> Google Apps Login in your WordPress admin.

If these fields are not yet completed, follow the instructions to set up a Service Account here.

Mapping Google Groups and OrgUnits to Roles

A key feature of the Enterprise version of the plugin is having greater control over WordPress roles. Please click on the Domain Control tab.

As for the Premium version, you should enter your company’s G Suite (formerly known as Google Apps) domain name in My Google Apps domain, and check Auto-create new users on my domain if that’s the functionality you desire. When users from your G Suite (Google Apps) domain attempt to login to WordPress using “Login with Google”, their accounts will be auto-created if they don’t already exist in WordPress.

The Enterprise Role Mapping Rules section allows us to specify how roles are assigned to those auto-created new users – and, optionally, we can reinforce those role rules every time a user logs in via Google.

Setting up Rules

You can add multiple rules to map from Google Groups or OrgUnits to WordPress roles. Enter the email address of a Google Group, or an OrgUnitPath, and select the desired corresponding role from the dropdown. Above, you can see we want members of the Google Group developers@mycompany.com to become Admins in WordPress; and members of the Group marketing@mycompany.com to become Editors. If the user is in neither of those Groups, then they may become Contributors if they belong to the /HardwareDivision OrgUnitPath (or below – e.g. /HardwareDivision/Mobile). Finally, if they do not match any of the rules they will be assigned the ‘Default Role’ of Subscriber.

There is also a ‘No Access’ option in the role dropdown so that any matching users are denied any usable role in the site.

Adding and Removing Rules

To add an extra rule click the Add Rule button. This will provide an extra empty row for you to enter a new rule.

To remove a rule box, just click the Delete link at the end of that row.

Rules are applied in the order shown in the Domain Control tab, stopping when any match is reached so that the first matching role will be applied. To change the order of the rules you can click and drag the up/down arrow icon at the left-hand side of the rule row that you want to move.

Overriding individual emails

Sometimes, you will want to create very specific rules that aren’t worth the creation of a Google Group. For example, you may want only yourself to be an Admin, but no other members of any Group (or anyone at all) – and it’s not really worth creating a new Group containing only yourself. In that case, you can simply enter an individual email address (e.g. your own) instead of a Group email address, and select the desired role from the dropdown.

Initially, when activated, the plugin will try to set up some rules based on your admin users. These will all be overrides so that admin users remain admins even after the rules are applied. You can remove these if you like, but they are in there as a safety net. If we didn’t put them in to start with, it would be easy just to run a set of blank rules and make all users, say, subscribers – at which point there would be no admins left to fix things!

How rules are applied

It is important to understand that the rules are applied in the order listed on the settings page, and finally the Default role is applied if no other matches are found. Once a rule matches and is applied, the search will stop.

If there are no rule matches, the Default Role will be applied.

In the example in the screenshot above, if a user is member of both developers and marketing groups, they will become an Admin in WordPress because the developers -> Admin rule is listed first.

For individual email addresses, you would normally want to list those first above any Group entries. Otherwise, if the user is also a member of a Group, an earlier Group-based rule could prevent their individual email address rule from matching first.

Check and reset roles on every login

If this is unchecked, the rules are only applied when a new user is auto-created. If you check the box, the rules will be reapplied (e.g. if membership of Google Groups has changed), every time a user logs in using Google.

Note that rules will not be applied if a user logs in using regular WordPress username/password – but you can check the box towards the top of the Domain Control tab if you want to ensure they can’t login that way.

All role changes (or any problems fetching Google Group or OrgUnitPath information) will be listed in the Logs tab of the Google Apps Login -> Settings page.

Note that multisite installations have a couple of extra options on this page – explained here.

Next Steps

Please do not hesitate to get in touch with us if you have any questions at all about the plugin!

You can also find out about Premium/Enterprise Advanced Options and Multisite usage.