Authenticating Multitenant Users and Groups

Table of Contents

• Lightwave Security Services
• Roles and Rights
• Process Overview
• Connecting to the Lightwave Management VM
• Gaining Access to the Docker Container Running Lightwave
• Creating a System Administrator in Lightwave
• Creating a Tenant Administrator
• Creating Project Users
• Using Lightwave Groups in Photon Controller
• Setting Security Groups for Administrators, Tenants, and Project Users
• Connecting to the Load Balancer for Secure Login
• Tenants, Resource Tickets, and Projects
• Projects

Lightwave Security Services

Photon Controller integrates with Lightwave to help secure Photon Platform. An open source project published by VMware on GitHub, Lightwave furnishes a directory service, a certificate authority, a certificate store, and an authentication service.

Lightwave authenticates Photon Platform users with its directory service. Lightwave group memberships provide a means of authorizing Photon Platform users as system administrators, tenants, or project users.

Roles and Rights

Photon Controller's multitenant model includes the following types of users:

System administrators. The Photon Controller system administrator has rights to perform any action. They create tenants and establish the security group for each tenant.

Tenant administrators. A system administrator assigns at least one tenant administrator to each tenant. Under the tenant to which they are assigned, a tenant administrator can create, modify, and delete resource tickets, projects, and other objects scoped under a tenant or a project. A tenant administrator can also manage the security groups associated with the tenant.

Project users. Project users can view and modify project resources, including Kubernetes clusters, VMs, and disks. After a Photon Controller tenant administrator or system administrator sets a security group for a project, the group members are granted project user rights.

Here's how to work with Lightwave and Photon Controller to authenticate and authorize users and groups in the context of Photon's model of multitenancy.

Process Overview

The process of creating users and groups goes like this:

1. Find the virtual machine running Lightwave so that you can access Lightwave to create users and groups.
2. Connect to the Docker container running Lightwave to use the directory command-line utility.
3. Create a system administrator group and user for Photon Controller so that you can log on to Photon Controller and be authenticated with Lightwave.
4. Optionally create additional users and groups in Lightwave by using the Lightwave directory utility.
5. Log in to Photon Controller as the system administrator, a tenant administrator, or a project user.

Connecting to the Lightwave Management VM

Before you can create users and groups in Lightwave for use in Photon Controller, you must find the Lightwave management VM, connect to it with SSH, and then enter the Docker container running the Lightwave service.

First, find the end point IP address of the Lightwave container by running the following commands with the Photon command-line utility on a workstation that's connected to Photon Controller:

photon deployment show

Connect to the Lightwave VM with SSH; the default password is vmware.

ssh esxcloud@<IPaddressOfAuthEndPoint>  

Gaining Access to the Docker Container Running Lightwave

After logging in to the Lightwave VM with SSH, you can connect to the Docker container running the Lightwave service:

docker exec -it Lightwave bash

Change directories to the directory containing the Lightwave directory management command-line utility, called dir-cli:

cd /opt/vmware/bin

You can now use the Lightwave dir-cli tool to create a system administrator, a tenant administrator, and a project user for Photon Controller by using the following sequence of commands:

./dir-cli ssogroup create --name "NameOfGroup"
./dir-cli user create --account <account-name> --user-password 'Your$ecret1!' 
                      --first-name <firstName> --last-name <lastName>
./dir-cli group modify --name <NameOfGroup> --add firstName-lastName 

Creating a System Administrator in Lightwave

After you first deploy Photon Controller with authentication turned on, you must log in to the Lightwave management VM and create a Photon Controller system administrators group that contains a user. When you're done, the user is a system administrator who can create tenants and project users on Photon Controller.

Using the password defined in the oauth_password key of your deployment template (L1ghtwave! in the example in the quick start guide), you can run Lightwave directory commands similar to the following examples to create a group in Lightwave, create a user, and add the user to the group.

./dir-cli ssogroup create --name "photonControllerAdmins"
./dir-cli user create --account pc-admin --user-password 'Your$ecret1!' 
                      --first-name pc --last-name admin
./dir-cli group modify --name photonControllerAdmins --add pc-admin

Creating a Tenant Administrator

Similarly, you can use the same sequence of commands to create a tenant administrators group and a tenant administrator:

./dir-cli ssogroup create --name tenant-admins
./dir-cli user create
    --account demo-tenant-admin 
    --user-password Passw0rd! 
    --first-name demo
    --last-name tenant
./dir-cli group modify --name tenant-admins --add demo-tenant-admin

Creating Project Users

And here's an example of how to create a group and a user for a project in Photon Controller:

./dir-cli ssogroup create --name dev-project-users
./dir-cli user create 
    --account dev-project-user1 
    --user-password Passw0rd!
    --first-name Project 
    --last-name User1
./dir-cli group modify --name dev-project-users --add dev-project-user1`

When you're done creating groups and users, type exit to leave the container, and then type exit again to leave the SSH session.

For more information about Lightwave, see the Lightwave GitHub repo.

Using Lightwave Groups in Photon Controller

Photon Controller uses Lightwave groups as generic collections of user accounts. The groups are created by a Lightwave administrator, not the Photon Controller administrator. In Lightwave, the groups contain no properties that distinguish system administrators from tenant administrators or project users.

To control access by enforcing the distinctions among groups in Photon Controller, you use one of the following commands to set a group from Lightwave as the security group for a deployment, tenant, or project.

photon deployment set-security-groups

Members of the security group for a deployment are system administrators for Photon Controller.

photon tenant set_security_groups

Members of the security groups for a tenant are tenant administrators.

photon project set_security_groups

Members of the security groups for a project are project users. They receive project-specific rights to work with and modify projects.

Important: The command to set security groups overrides existing groups. The groups that you include in the photon project set_security_groups command, for example, replace all the existing security groups---even ones that you have already defined. The only exception is inherited groups, which are retained by default. When you create a project, the project inherits the security groups from the tenant that governs the project, including whatever groups the tenant inherited.

The next section presents examples of how to set the security groups for a deployment, a tenant, and a project. Remember to be careful when you run the commands to set a security group so that you don't lock yourself out of the system.

Setting Security Groups for Administrators, Tenants, and Project Users

To set a group named dev-project-users as the security group for an existing project named dev-project, connect to Photon Controller by using the Photon command-line utility on your workstation and then run the following command:

photon project set_security_groups dev-project -t demo -g photon\\dev-project-users

As the example above illustrates, you specify group names in the following format: <securitydomain>\\<NameOfGroup>. Here's an example: photon\\Administrators. The security domain must be made up of all lowercase letters.

Here's an example of how to set a group as a tenant administrator. All the members of the group have tenant administrator rights. In the example, plato is the name of the tenant.

photon tenant set_security_groups plato photon\\tenant-admins

A system administrator can set a Lightwave group that contains a list of users who have rights to administer the entire deployment of Photon Controller. Important: The following command overrides the existing groups. Be careful running it because providing the wrong group could remove your access:

photon deployment set-security-groups photon\\photonControllerAdmins

All the commands to set security groups can contain a comma-separated list of groups; example:

photon deployment set-security-groups photon\\photonControllerAdmins, photon\\Administrators, photon\\superUsers

Connecting to the Load Balancer for Secure Login

After you created a security group in Lightwave, you can connect to the load balancer to create tenants, resource tickets, and projects.

First, find the load balancer's IP address by running the following commands with the Photon CLI on your workstation:

photon deployment show

Since you deployed Photon Controller with authentication, you must connect to the IP address of the load balancer by appending Port 443:

photon target set -c https://<production_system_ip>:443

And then you can log in by using the pc-admin account at oauth_tenant that you created in the Lightwave directory. Lightwave authenticates the user.

photon target login --username pc-admin@<oauth_tenant> --password 'Your$ecret1!'

Here is an example. In the sample YAML file used by the quick start guide, the oauth_tenant is set to esxcloud---so <oauth_tenant> is replaced with esxcloud. (You may have used a different name for the oauth_tenant, such as photon.)

photon target login --username pc-admin@esxcloud --password 'Your$ecret1!'

Finally, check your work:

photon system status
Overall status: READY
Component          Status
PHOTON_CONTROLLER  READY

As the status says, you're now ready to work with the system. You can create tenants, projects, and other resources.

Tenants, Resource Tickets, and Projects

As a multitenant system, Photon Controller abstracts physical resources so that it can allocate them across the system on behalf of users. In Photon Controller's multitenant structure, tenants, resource tickets, and project users are closely tied together.

When you create a tenant, you give it a pool of resources that the tenant's projects can consume. The pool is allocated through resource tickets. A resource ticket sets aside a limited amount of resources, such as CPUs, RAM, and disks.

The limits for each class of resource are defined as a tuple that includes a key, a value, and a unit.

Key	Value (type)	Unit	Description
vm	integer	COUNT	The number of Virtual Machines that can be created by all projects using this ticket
vm.memory	integer	GB	The amount of virtual memory, in gigabytes, that can be consumed by all virtual machines in all projects using this ticket
vm.cpu	integer	COUNT	The number of virtual CPU cores that can be consumed by all virtual machines in all projects using this ticket

A resource ticket is scoped to a singe tenant, persists for the life of the tenant, and is removed when the tenant is deleted.

Projects

A project is a way to allocate the pool of resources assigned to a tenant through resource tickets.

Tenant administrators create projects based on a resource ticket and can impose project-specific limits on ticketed resources. A project can be granted the right to use all or part of a ticket's resources. Project users can create VMs and disks by paring images with flavors.

For more information about tenants, projects, and resources, see Working with Tenants, Resource Tickets, and Projects.