Authenticating Multitenant Users and Groups

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.

Table of Contents

• Lightwave Security Services
• Roles and Rights
• Process Overview
• Connecting to the Lightwave Management VM
• 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, Quotas, 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 quotas, 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.

Process Overview

The process of creating users and groups goes like this:

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

Connecting to the Lightwave Management VM

You can log in to the Lightwave service with SSH and create additional users and groups.

Before you can log in with SSH, however, you must access the VM through its console in ESXi and modify the VM's SSH configuration file to permit root login.

To permit root login over SSH, open /etc/ssh/sshd_config with the vim text editor and set all three instances of PermitRootLogin to yes. After you modify and save the SSH daemon's configuration file, you must restart the sshd daemon for the changes to take effect:

systemctl restart sshd

Then connect to the Lightwave VM with SSH using the root account and password that you set in the YAML file for the Lightwave VM; example:

 ssh root@<IPaddressOfLightwaveVM>   

After you log in to the Lightwave VM with SSH, change directories:

cd /opt/vmware/bin

Using the Lightwave administrator password that you defined in the YAML configuration file when prompted, run the following Lightwave directory commands to create a group, 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

When you are done, type exit again to leave the SSH session.

Connecting to the Lightwave Web Interface

You can also create users and groups by the Lightwave web interface. To connect to it, you must first add a Lightwave entry to the /etc/hosts file of your Linux workstation so that your browser can use the hostname that you set for the Lightwave VM instead of its IP address.

Here's an example of how to add a Lightwave entry to /etc/hosts:

##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
127.0.0.1   localhost
255.255.255.255 broadcasthost
::1             localhost
198.51.33.10    lightwave-1.example.com

You can now connect to the Lightwave VM by connecting to its full hostname over HTTPS; example:

https://lightwave-1.example.com

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 administrator password defined in the your YAML 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 groups 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, quotas, 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 that you created in the Lightwave directory. Combine the account name with the domain name defined in your YAML template. Lightwave authenticates the user.

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

Here is an example:

photon target login --username pc-admin@example.com --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, Quotas, 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, quotas, 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 quotas. A quota 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 quota
vm.memory	integer	GB	The amount of virtual memory, in gigabytes, that can be consumed by all virtual machines in all projects using this quota
vm.cpu	integer	COUNT	The number of virtual CPU cores that can be consumed by all virtual machines in all projects using this quota

A quota 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 quotas.

Tenant administrators create projects based on a quota and can impose project-specific limits on the resources. A project can be granted the right to use all or part of a quota'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, Quotas, and Projects.