Product
This article relates to both LogonBox Cloud (Saas) and LogonBox On-prem (VM).
Introduction
This article shows you how to connect to a Google business domain for your user database.
Configuring Google for authentication
- To begin, a new project must be created in your Google Developers Console if you don't have one already. Go to https://console.developers.google.com and login with a Google Account that has permission to manage users in the Google directory. From the projects dropdown at the top of the screen, select New Project.
- Enter a project name, and select the billing account and location. Click Create.
3. Select the new project from the dropdown at the top of the screen. Then navigate to APIs & Services and click Enable APIs and services.
4. Search for admin SDK. Select Admin SDK API when it appears.
5. Click Enable. If this is already enabled, click Manage instead.
6. Next click on OAuth consent screen on the left menu and set the User Type to Internal. Click Create.
7. Type an Application Name of your choice and select a user support email from the dropdown..
You can also optionally set an App logo here.
8. Whilst on this page, scroll down and set values in App domain, these are optional but you can add the LogonBox home URL and any privacy policy or terms of service links you want your users to see.
For Authorized Domains click Add Domain and add a domain. This needs to match the hostname of your LogonBox server or the top level domain of your host.
Add an email address in the Developer contact information and click Save and Continue.
9. You should now be on the Scopes page. Click Add or remove scopes.
10. For the scopes, in the Manually add scopes section, you can just paste in the following text:
https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.group.member,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.user.alias
Click Add to Table, then Update, then Save and Continue.
11. Click on the Credentials menu on the left, then Create Credentials and select OAuth client ID.
12. At the Create OAuth client ID screen, select Web Application and give the new application a name.
13. For Authorised JavaScript origins add two URIs (Note: Press tab or click outside the text box to add the URL, don't press enter as it will premeturely create the config).
https://localhost
https://LogonBoxURL
Replace LogonBoxURL with the address used by your users to connect to Access Manager.
14. Now in Authorised redirect URIs enter the same hostnames with /app/api/google/oauth/end included in the path
https://localhost/app/api/google/oauth/end
https://LogonBoxURL/app/api/google/oauth/end
Now select Create to complete the account creation.
15. Take note of the Client ID and Client Secret that are provided, you will need these later and this is the only time you will be shown the secret. Click OK.
16. Now you will need to create a Service Account. Click Create Credentials drop down, this time select Service Account.
17. In the account creation give it a Service account name and Service account ID. Click Done at the bottom.
18. You can leave the Role section as Select a role. Just click Done.
You should see your new Service Accountm click the link for this account under the Email section.
19. Click the Keys tab, then Add Key->Create new key.
20. Select JSON and click Create.
21. This will then download the JSON file, so save that, then click Close on the popup. The full text of this file will be required later.
22. Click on Service Accounts on the left, then scroll the page to the right to see the OAuth 2 client ID.
Make a note of the Client ID of the service account, note this down as the Service Account ID. Take care that this is different than the Client ID we already noted, we will need this for the last part of the Google admin configuration.
23. You will now have all the details you require for configuring a Google Directory in LogonBox, but there is one last setting in Google that needs to be configured.
Configure Google Security Settings
Go to your Google Apps Admin Console at https://admin.google.com/AdminHome and login with your Google admin account.
Select or search for the Security option.
In the Security page click API Controls.
Tick the Enable API Access option.
Then scroll down to Domain-wide delegation and click Manage domain-wide delegation.
In the API Clients page we will register a new client access configuration. Click Add New.
For the Client ID use the Service Account Client ID that we noted earlier (this was the second Client ID we noted and is the one containing just numbers rather than a hostname).
For the OAuth scopes field you can copy and paste the following entries:
https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.group.member,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.user.alias
Click Authorize. This completes the steps for Google Apps configuration, in LogonBox we are now ready to create the Google Directory.
Adding the Google Directory
In your LogonBox, navigate to Users & Permissions, then click Configure User Database.
In the Update Realm screen that appears, click the Realm Type dropdown and select Google.
The screen will update to show the relevant tabs for this configuration.
In the first tab, Connection, enter the following information:
- Admin Email: The email address of the Google Apps admin account that will be used to manage this connection.
- Customer Domain: The domain of the Google Apps account.
- Service Account Json: The content of the Json file downloaded when configuring the credentials on the Google Developers Console.
- OAuth2 Client ID: The Client ID configured on the Google Management Console.
- OAuth2 Secret ID: The Client Secret configured on the Google Management Console.
- Read Only: Set to ON if you do not want to manage or update Google users from the Hypersocket server. Defaults to OFF.
The next tab is Org Units and is optional. Org unit filtering can come in useful when you have a large number of users, or if you wish to limit which set of users will be allowed to log on to the system.
Org units can be added to an include filter by using Include Orgunits, or they can be blocked by using Exclude Orgunits. You may use Include and Exclude filters at the same time, include gets processed before exclude when reconciling.
To add a filter, type in the orgunit name into the relevant text box and press enter to add it to the list box below that.
An existing filter can be removed by clicking on the X to the right of the name in the list.
The third tab is Principal Filter, which gives a more finely grained filtering to further restrict which user objects are cached by the server. This can be used to build on the Included/Excluded Orgunits, but here individual Users and/or Groups can be defined to exclude them.
As with other list items, type in the user or group you wish to exclude then press enter to add it to the list.
If you click onto the Advanced link, another tab is available, Reconcile.
This contains settings relating to how the users are cached in LogonBox. LogonBox connects to the remote user database periodically to update its list of cached users and then performs an update (reconcile) of this cache by either adding new users, deleting users that no longer exist or updating existing users.
The reconcile settings are:
- Rebuild Cache: On next reconcile, delete the cache and import all user objects from scratch. This takes more time than a normal reconcile. Defaults to OFF.
- Purge Duplicates: On rare occasions an out of date cache can cause duplicate users to be created in the cache. If that happens, this option can force removal of these duplicate users and rebuilds the cache. Defaults to OFF.
- Cache Passwords: LogonBox will generate a one-way hash of the users’ passwords the next time they log on and cache this. Subsequent authentication attempts do not need to contact the domain controller for authentication until the Hypersocket server is restarted. Defaults to OFF.
- Reconcile at Login: Performs a reconcile of the user’s account at login. This can ensure that the latest information for that user (such as group membership and AD attributes) are perfectly up to date each login. Generally this is not needed as user accounts do not change very often. Defaults to OFF.
There is one more tab that only appears after editing the Realm after it has been created. This tab is Status and contains information relating to the reconcile status:
- Status: Contains the status of the last reconcile, which can be Completed or Failed.
- Next Due: The date and time that the next reconcile is due to run.
- Last Performed: The date and time that the last reconcile was performed.
- Last Error: If the last reconcile failed, any errors appear in this field.
Once you have entered all the required configuration, click the Update button to save the changes.
LogonBox will now connect to the Google directory and synchronise the list of users.
