Using Data Tables to Manage Admin Users

This tutorial shows how to use policy data tables and policy variables to simplify the process of adding new cluster admin users who are authenticated with Google's OAuth service. For an overview of policy variables and data tables, see Policy Variables.

Also see Adding Google Users as Admins.

This tutorial assumes that you have enabled Google OAuth on your cluster.

Background

When you install Apcera Platform you have the option enabling Google authentication and specifying the email addresses of the Google users you want to be cluster administrators. Cluster admins are granted (by policy) full permissions over all realms and resources. Before policy data tables, adding a new Google user after installing the cluster required duplicating policy boilerplate.

For example, to add a new admin user with the Google ID adminuser3@example.com you would copy/paste the policy claim on the auth::/oauth2/http realm that grants the new user access to the cluster and sets their name claim to their email address, for example:

on auth::/oauth2/http {
  if (Google->email == "adminuser1@example.com") {
    name "adminuser1@example.com"
    permit issue
  }
  if (Google->email == "adminuser2@example.com") {
    name "adminuser2@example.com"
    permit issue
  }
  if (Google->email == "adminuser3@example.com") {
    name "adminuser3@example.com"
    permit issue
  }
}

In addition to permitting access, you need to add policy that assigns the predefined admin role to the new user:

on audit::/ {
  if (auth_server@apcera.me->name == "adminuser1@example.com") { role admin }
  if (auth_server@apcera.me->name == "adminuser2@example.com") { role admin }
  if (auth_server@apcera.me->name == "adminuser3@example.com") { role admin }
}
on cluster::/ {
  if (auth_server@apcera.me->name == "adminuser1@example.com") { role admin }
  if (auth_server@apcera.me->name == "adminuser2@example.com") { role admin }
  if (auth_server@apcera.me->name == "adminuser3@example.com") { role admin }
}
...for all policy realms...

While these tasks are not difficult they are tedious and error prone when performed manually. With policy variables and data tables you can separate the policy data (email addresses) from the policy rules. To add a new admin user you only need to provide their email address.

Create the policy variable document

A policy variable document defines the name of your data table and its column names. Policy variable document filenames must be composed of systemDataTable (note camel-case), followed by the name of the data table the document defines. For example, if you are creating a policy variable named PolicyVar then the document it contains must be systemDataTablePolicyVar.

To create the policy variable document:

  1. Open the Web Console for your cluster and select Policy from the left navigation.
  2. Click Create to open the new policy document form.
  3. In the document name field enter systemDataTableAdminUsers.
  4. Copy and paste the following into the new policy document:

     on variables::/ {
       system policy variable {
         AdminUsers (email) {
         }
       }
     }
    

    This defines a new policy variable named AdminUsers that contains a single column named email. Note that the policy document filename suffix matches the policy variable name.

  5. Click Create Document.

    Create data table

Add users to the data table

Now that you've created the data table you can populate it with the email addresses of the users you want to be authorized admins.

To add users to the table:

  1. Click Policy in the left navigation, then click the Data Tables tab. It lists the single data table you just created named AdminUsers.

    Create data table

  2. Click AdminUsers to open it in table editing mode. At this point the table is empty.

    Data table

  3. Click Add Row.
  4. In the Email field enter the Google ID (email address) of a user you want to add as an admin and click Submit.

    Admin users data table

  5. Repeat steps 3-4 for all users you want to add, which are listed in the data table.

    Admin users data table

    You see the same list if you open the original systemDataTableAdminUsers document from main Policy view:

    Admin users data table

Create policy that references the data table

Next you'll create a policy document that references the policy data table you created. A policy claim that references a data table is issued for as many rows that the data table contains.

To give each user in the data table admin permissions:

  1. On the Policy tab in the Web Console click Create.
  2. Name the policy document google_admin_policy and copy/paste the following policy into the form:

       on auth::/oauth2/http {
         if (Google->email == PV->AdminUsers.email)
          {
            name PV->AdminUsers.email
            permit issue
          }
       }
    
       on all::/ {
          if (query->target fqnMatch "*::/" &&
            auth_server@apcera.me->name == PV->AdminUsers.email ||
            query->target fqnMatch "policy::/" ||
            query->target fqnMatch "policydoc::/")
            {
              role admin
            }
       }
    
    • Policy on auth::/oauth2/http issues a token to each user in the AdminUsers data table, and sets the name claim to the user's email.
    • Policy on the all::/ resource assigns the admin role to each user in the data table for each resource type. Policy on all::/ must be qualified with an if () {} clause that matches the query->target with a realm you specify. In this case, the fqnMatch is matched against *::/, which matches all resource types except policy::/ and policydoc::/. You must explicitly match those resource types against query->target, as show above.
  3. Click Create Document.

    Now any user whose email is added to the AdminUsers data table will be able to access and fully administer the cluster. To add additional admin users, simply add a new row to the AdminUsers data table.