kubi

README

Kubi

Kubi is the missing tool for Active Directory or LDAP driven company. It handles OpenLDAP or Active Directory LDS authentication for Kubernetes clusters. It acts as a Kubernetes Token Server, authenticating user through LDAP, AD LDS and assigns permissions dynamically using a predefined naming convention (LDAP Group).

It manages authorization and authentication of users/admins/other profiles on K8S clusters, manages multi-tenancy, and performs a few minor side tasks.

Note: to understand properly Kubi project, you should be familiar with authentication and authorization concepts in Kubernetes. Those docs are good starting points. https://kubernetes.io/docs/concepts/security/controlling-access/ https://kubernetes.io/docs/reference/access-authn-authz/authentication/

Kubi components goals

Kubi is composed of 4 bricks, each with its own mission. Kubi components leverage the authentication webhook authentication mode, and RBAC authorization mode. 3 bricks are stored in this current repo : https://github.com/ca-gip/kubi 1 brick, the CLI, is stored is another repo: https://github.com/ca-gip/kubi-cli

Kubi CLI:

• offers a client interface to contact Kubi API

Kubi API:

• delivers authentication tokens and kubeconfig files (containing the token)

Kubi Authentication Webhook: (which is today misnamed authorization webhook)

• tells the API server if a token is legitimate
• fills in the tokenReview status field with following info : is the user authenticated ?
• if so, which groups is he part of ?
• to do that, it does a request to the OpenLDAP/AD to know the groups of the user

Kubi operator:

• watches AD groups in a given path and create properly formatted namespaces (ServiceAccounts, RoleBindings). Clusterrole are created statically
• watches NetworkPolicyConfig and create netpols

Architectural diagrams

You can modify following diagrams using the excalidraw file under docs/ folder.

Kubi operator

Kubi CLI + API

Kubi authentication webhook

Example of kubeconfig file

Example of TokenReview

Index

• Kubi
  • Index
• General
  • Parameters
  • Versioning
• Client
  • For Windows users
  • For Linux
    • With kubi cli
      • For Linux
      • For Mac
      • Connection
    • With curl
• Installation
  • Prerequisites
  • Create a crt signed by Kubernetes CA
  • Create the signing request
  • Approve the csr
  • Retrieve the crt
  • Create a secret for the deployment
  • Create a secret for LDAP Bind password
  • Deploy the config map
  • Deploy the Custom Resource Definitions
  • Deploy the prerequisites
  • Deploy Kubi
  • Customize the default network policy
  • Basic Webhook configuration
  • Advanced Webhook configuration
• Roadmap
• Development environment
  • Deploy the local config
  • Copy the secret from you Kubernetes cluster
  • Running

General

Namespaces and Rolebindings are automatically created and managed by Kubi. Kubi parse the LDAP group and find the namespace and the role. The first part (from the right) is the role, and the second is the namespace.

The _ is used to split Role and Namespace, the pattern is <whatever>_<namespace>_<role>. Namespace must be DNS1123 compatible and can´t exceed 63 characters ( kubernetes constraint ).

For example:

• a ldap group named: WHATYOUWANT_DEMO_ADMIN give cluster role binding admin permissions to the namespace DEMO.
• a ldap group named: WHATYOUWANT_PROJECT-IN-PRODUCTION_ADMIN give cluster role binding admin permissions to the namespace PROJECT-IN-PRODUCTION.

If the namespace is missing, it will be automatically created at startup. You can refresh it by calling /refresh. Some namespace are protected: kube-system, kube-public, default. Kubi can generate NetworkPolicy if PROVISIONING_NETWORK_POLICIES flag is enabled. In this case, it create a Networpolicy that create something like a bubble.

The network policy works like this principle:

• Every pods can communicate inside the namespace
• Pods cannot communicate with external resources ( outside cluster )
• Dns is not filtered

You can customize PROVISIONING_EGRESS_ALLOWED_PORTS, PROVISIONING_EGRESS_ALLOWED_CIDR, PROVISIONING_INGRESS_ALLOWED_NAMESPACES to add default rules. For specific exceptions, add another network policy.

Parameters

Name	Description	Example	Mandatory	Default
PUBLIC_APISERVER_URL	Api server url (public)	https://k8s.macompany.com	yes	-
LDAP_USERBASE	BaseDn for user base search	ou=People,dc=example,dc=org	yes	-
LDAP_GROUPBASE	BaseDn for group base search	ou=CONTAINER,dc=example,dc=org	yes	-
LDAP_APP_GROUPBASE	BaseDn for group base search	ou=CONTAINER,dc=example,dc=org	no	-
LDAP_OPS_GROUPBASE	BaseDn for group base search	ou=CONTAINER,dc=example,dc=org	no	-
LDAP_CUSTOMER_OPS_GROUPBASE	*BaseDn for customer group base *	ou=CONTAINER,dc=example,dc=org	no	-
LDAP_ADMIN_USERBASE	BaseDn for admin base search	ou=Admin,dc=example,dc=org	yes	-
LDAP_ADMIN_GROUPBASE	BaseDn for admin group base search	ou=AdminGroup,dc=example,dc=org	yes	-
LDAP_VIEWER_GROUPBASE	BaseDn for viewer group base search	ou=ViewerGroup,dc=example,dc=org	no	-
LDAP_SERVICE_GROUPBASE	BaseDn for service group base search	ou=ServiceGroup,dc=example,dc=org	no	-
LDAP_ELIGIBLE_GROUPS_PARENTS	List of "|" separated BaseDn for user groups memberships search	ou=container,ou=Groups,dc=kubi,dc=ca-gip,dc=github,dc=com|ou=teams,ou=Groups,dc=kubi,dc=ca-gip,dc=github,dc=com	yes	-
LDAP_SERVER	LDAP server ip address	"192.168.2.1"	yes	-
LDAP_PORT	LDAP server port 389, 636...	389	no	389
LDAP_PAGE_SIZE	LDAP page size, 1000...	1000	no	1000
LDAP_USE_SSL	Use SSL or no	true	no	false
LDAP_START_TLS	Use StartTLS ( use with 389 port)	true	false	false
LDAP_SKIP_TLS_VERIFICATION	Skip TLS verification	true	false	true
LDAP_BINDDN	LDAP bind account DN	"CN=admin,DC=example,DC=ORG"	yes	-
LDAP_PASSWD	LDAP bind account password	"password"	yes	-
LDAP_USERFILTER	LDAP filter for user search	"(userPrincipalName=%s)"	no	(cn=%s)
TOKEN_LIFETIME	Duration for the JWT token	"4h"	no	4h
LOCATOR	Locator: must be internet or extranet	"intranet"	no	intranet
PROVISIONING_NETWORK_POLICIES	Enable or disable NetPol Mgmt	true	no	yes
CUSTOM_LABELS	Add custom labels to namespaces	quota=managed,monitoring=true	no	-
DEFAULT_PERMISSION	ClusterRole associated with default service account	view	no	-
BLACKLIST	Ignore Project	my-project-dev	no	-
PODSECURITYADMISSION_ENFORCEMENT	PodSecurityAdmission Enforcement	restricted	no	restricted
PODSECURITYADMISSION_WARNING	PodSecurityAdmission Warning	restricted	no	restricted
PODSECURITYADMISSION_AUDIT	PodSecurityAdmission Audit	restricted	no	restricted
PRIVILEGED_NAMESPACES	Namespaces allowed to use privileged annotation	native-development	no	-

Versioning

Since version v1.24.0, we have decided to modify the naming of versions for ease of reading and understanding. Example: v1.24.0 means that the operator was developed for Kubernetes version 1.24 and that the last 0 corresponds to the various patches we have made to the operator.

Client

For Windows users

1. Download the cli: download here
2. Open Cmd

# Get help
.\kubi.exe --help
# Connect and generate config file
.\kubi.exe --kubi-url <kubi-server-fqdn-or-ip>:30003 --generate-config --username <user_cn>
# Connect with your password and generate config file
.\kubi.exe --kubi-url <kubi-server-fqdn-or-ip>:30003 --generate-config --username <user_cn> --password your_pwd

For Linux

With kubi cli

For Linux

# Install the kubi cli
sudo wget https://github.com/ca-gip/kubi/releases/download/v1.8.5/kubi -P /usr/local/bin
sudo chmod a+x /usr/local/bin/kubi

# Connect to the cluster
kubi config --kubi-url <kubi-server-fqdn-or-ip>:30003 --username <user_cn>
# Connect with your password and generate config file
kubi config --kubi-url <kubi-server-fqdn-or-ip>:30003 --username <user_cn> --password your_pwd

For Mac

# Install wget with brew
brew install wget

# Install the kubi cli
sudo wget https://github.com/ca-gip/kubi/releases/download/v1.8.5/kubi-darwin -O /usr/local/bin/kubi
sudo chmod a+x /usr/local/bin/kubi

Connection

# Connect to the cluster
kubi config --kubi-url <kubi-server-fqdn-or-ip>:30003 --username <user_cn>
# Connect with your password and generate config file
kubi config --kubi-url <kubi-server-fqdn-or-ip>:30003 --username <user_cn> --password your_pwd

# Explain your token
kubi explain # for your current context token
kubi explain <another_token> for explaining another token

With curl

  curl -v -k --user <user_cn> https://<kubi-server-fqdn-or-ip>:30003/config

It is not recommended to use curl, because it is used with -k parameter ( insecure mode).

Contributing

• Contributing to kubi.

---

Developed with