Using Google Auth as the Identity Provider
This document describes how to configure your cluster to use Google auth as the identity provider for your Apcera cluster.
- Enabling Google Auth APIs
- Configuring the Consent Screen
- Create the client and web credentials
- Configuring cluster.conf for Google auth
- Monitoring Google Auth
- Adding Google Users as Admins
Enabling Google Auth APIs
To use Google Auth for you cluster, you generally need two Google APIs: Google+ API and Google+ Domains API. The Google+ API lets users log in to the cluster using their Gmail credentials. The Google+ Domain API lets users log in using a Google-powered domain email address, such as @apcera.com
.
- Log in to the Google developer project site at https://console.developers.google.com/project/.
-
Click Select a Project > Create Project (upper right of the console) and create a new project, or select an existing project.
-
Select the Google APIs > API Manager page in the upper left of the console.
-
Select the Overview > Google APIs tab.
-
Enter
google+ apis
in the search field. - Select and enable the Google+ API (for Gmail sign in).
- Select and enable Google+ Domains API (for domain sign in).
-
Select the Enabled APIs tab and verify that required APIs are enabled:
Configuring the Consent Screen
The consent screen (shown below) is displayed to the user when logging in using the APC client using Google authentication, after having browsed to the https://www.google.com/device URL and entered the eight-letter code presented by APC. This configuration is required for APC login using Google auth.
To configure the consent screen:
- Click Credentials in the left-hand menu.
- Select the OAuth consent screen tab (at the top).
- Configure the consent screen as follows:
- Email address – Enter or select your email.
- Product name shown to users – Enter "Apcera Platform" or other name of your choosing.
- Homepage URL – Enter
https://www.apcera.com
or other URL of your choosing. - Product logo URL – Enter
https://s3.amazonaws.com/apcera-static/oauth.png
or other logo of your choosing.
- Click Save to save the configuration.
-
Verify the consent screen configuration:
Create the client and web credentials
You need to create the client ID and key for APC login, and the web ID for log in using the web console.
Create the Client ID and Key for APC login
The client ID and key are used for configuring cluster log in using APC.
- Click Credentials in the left navigation.
- Select the Credentials tab (at top).
- Click Create credentials.
- Select the OAuth client ID.
- For Application Type, select Other.
- In the Name field enter
APC client
or name of your choosing. - Click Create.
- Click OK.
-
Verify your client ID and secret as shown below.
Create the Web ID for web console login
The web ID is used to configure cluster login via the web console using Google auth.
- Click Credentials in the left navigation.
- Click Create credentials.
- Select OAuth client ID.
- For Application Type, select Web application.
- In the Name field enter
Web console client
or other name. -
In the Authorized JavaScript origins section, enter the following URIs.
Replace
<subdomain>
,<domain>
and<tld>
with your cluster's details.http://auth.<subdomain>.<domain>.<tld> https://auth.<subdomain>.<domain>.<tld> http://console.<subdomain>.<domain>.<tld> https://console.<subdomain>.<domain>.<tld>
For example:
-
In the Authorized redirect URIs section, add the following URIs.
Replace
<subdomain>
,<domain>
and<tld>
with your cluster's details. If you are using HTTPS, you may not want to specify the HTTP URL, or vice-versa.http://console.<subdomain>.<domain>.<tld>/v1/oauth2/web/popup/googlecb https://console.<subdomain>.<domain>.<tld>/v1/oauth2/web/popup/googlecb
- Click Save to save the web client configuration.
Verify and download the credentials
-
Verify that your Google auth configuration is properly configured.
You should have two client IDs: one for the web console one for APC.
-
Download each client ID configuration as a JSON file.
Select each client ID and download the credentials in the JSON file. (Or download from the Credentials page shown above.) You will need this information to configure Google Auth for your cluster as described below. Be sure to secure each file.
Configuring cluster.conf for Google auth
To use Google Auth as the identity provider for a production deployment, you must specify your Google auth project in the cluster.conf
file. If a Google auth project is NOT configured, users will not be able to login to the web console until a valid project is configured.
To configure your cluster to use Google auth using a Google project, you add the following block to your cluster.conf
file:
"auth_server": {
"identity": {
"google": {
"users": [
"admin-email-address@gmail.com",
"another-admin-email-address@acme.com"
],
"client_id": "8675309-n411ocp2qb458v28c0f2elfarp1qj8.apps.googleusercontent.com"
"client_secret": "YOURCLIENTSECRET"
"web_client_id": "8675309-insivfss8u2l61h9khm1cmv5d7icqopl.apps.googleusercontent.com"
},
},
You specify Google as the identity provider, and authorize a default set of users by providing the email address for each. The email address can be a Gmail address or an enterprise domain address that you have registered with Google Apps.
The Google auth project credentials are split depending on if the client is logging in to the cluster using APC or the web console. To authenticate APC clients, you provide the values for the client_id
and client_secret
. To allow users to log in using the web console, you provide the web_client_id
.
Once your cluster is deployed you can use policy to permit more Google users access to the cluster and assign them policy. See Adding policy for Google auth users.
Monitoring Google Auth
You can use the Google Auth monitoring plugin to monitor Google Authenication in Zabbix. The plugin raises a Zabbix alert if you have issues with Google auth. When defining the plugin in the cluster.conf
file, you should use the base domain name for whatever cluster is being monitored. You should populate these values after the cluster is operational, then run orchestrator-cli
.
To do this, add the following parameters and values to the cluster.conf
file immediately after and siblings of the web_client_id
parameter for google auth. For example:
"scope_url": "http://cloud.company.com",
"refresh_token": "Monitoring refresh token"
These oauth2 parameters will be used to generate a config file for the oauth2 monitoring plugin in Zabbix. The cluster must be operational before configuring this section. In other words, after you have deployed your cluster and verified Google auth, you configure this section of the cluster.conf
file and redeploy the cluster with oauth2 monitoring enabled.
The scope_url
is a setting used by the Google auth monitoring plugin that goes into Zabbix. The scope_url
is used by Zabbix to raise an alert if you have issues with Google auth. When defining the scope_url
, you should use the base domain name for whatever cluster is being monitored.
Adding Google Users as Admins
When you deploy a cluster you can specify the initial set of Google users (email addresses) you want to have admin access to the cluster. Once a cluster is deployed with Google Auth you can use policy to permit cluster access to additional Google users and assign those users permissions, as described below.
To add a Google user as a cluster admin:
- Log in to your cluster's Web Console as an admin user.
- Click Policy in the left navigation and open the googleAuth.pol policy document. This policy document is created automatically during installation of the platform if you enabled Google Auth. It contains the Google email addresses that were specified during cluster deployment.
// Allowing Google users to get issued a token (i.e. log in to Apcera). on auth::/oauth2/http { if (Google->email == "example.user@gmail.com") { name "example.user@gmail.com" permit issue } }
- For each Google user you want to authorize as an additional admin user, copy/paste the existing
if ()
clause the following to the policy document, replacing the email addresses with the ones for// Allowing Google users to get issued a token on auth::/oauth2/http { if (Google->email == "example.user@gmail.com") { name "example.user@gmail.com" permit issue } if (Google->email == "admin-email-address-1@gmail.com") { name "admin-email-address-1@gmail.com" permit issue } if (Google->email == "admin-email-address-2@acme.com") { name "admin-email-address-2@acme.com" permit issue } }
- Save your changes to authGoogle.pol.
- Open the policy document named systemDataTableAssignedRoles.pol. This policy lets you easily assign a role (set of permissions) to a user.
// This table indicates what user logins should have which roles. // This policy is initialized for a new cluster with the list of admins, // but can be edited after deployment to set a role for any user and // resource. // on variables::/ { system policy variable { AssignedRoles (userName, role, resource) { { "admin@apcera.me", "admin", ["*::/", "policy::/", "policydoc::/"] } { "example.user@gmail.com", "admin", ["*::/", "policy::/", "policydoc::/"] } { "admin-email-address-1@gmail.com", "admin", ["*::/", "policy::/", "policydoc::/"] } { "admin-email-address-2@acme.com", "admin", ["*::/", "policy::/", "policydoc::/"] } } } }
-
Save your changes to systemDataTableAssignedRoles.pol.
The user should now be able to login to the cluster using APC or the Web Console and perform any operation.