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

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.

  1. Log in to the Google developer project site at https://console.developers.google.com/project/.
  2. Click Select a Project > Create Project (upper right of the console) and create a new project, or select an existing project.

    screenshot

  3. Select the Google APIs > API Manager page in the upper left of the console.

    screenshot

  4. Select the Overview > Google APIs tab.

    screenshot

  5. Enter google+ apis in the search field.

    screenshot

  6. Select and enable the Google+ API (for Gmail sign in).
  7. Select and enable Google+ Domains API (for domain sign in).
  8. Select the Enabled APIs tab and verify that required APIs are enabled:

    screenshot

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.

screenshot

To configure the consent screen:

  1. Click Credentials in the left-hand menu.
  2. Select the OAuth consent screen tab (at the top).
  3. 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.
  4. Click Save to save the configuration.
  5. Verify the consent screen configuration:

    screenshot

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.

  1. Click Credentials in the left navigation.
  2. Select the Credentials tab (at top).
  3. Click Create credentials.
  4. Select the OAuth client ID.
  5. For Application Type, select Other.
  6. In the Name field enter APC client or name of your choosing.
  7. Click Create.
  8. Click OK.
  9. Verify your client ID and secret as shown below.

    screenshot

Create the Web ID for web console login

The web ID is used to configure cluster login via the web console using Google auth.

  1. Click Credentials in the left navigation.
  2. Click Create credentials.
  3. Select OAuth client ID.
  4. For Application Type, select Web application.
  5. In the Name field enter Web console client or other name.
  6. 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:

    screenshot

  7. 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
    
  8. Click Save to save the web client configuration.

Verify and download the credentials

  1. Verify that your Google auth configuration is properly configured.

    You should have two client IDs: one for the web console one for APC.

    screenshot

  2. 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:

  1. Log in to your cluster's Web Console as an admin user.
  2. 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
      }
    }
    
  3. 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
      }
    }
    
  4. Save your changes to authGoogle.pol.
  5. 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::/"] }
     }
      }
    }
    
  6. 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.