The user-authz module: FAQ

How do I create a user?

Creating a user.

How do I limit user rights to specific namespaces?

To limit a user’s rights to specific namespaces in the experimental role-based model, use RoleBinding with the use role that has the appropriate level of access. Example….

In the current role-based model, use the namespaceSelector or limitNamespaces (deprecated) parameters in the ClusterAuthorizationRule CR.

What if there are two ClusterAuthorizationRules matching to a single user?

Imagine that the user jane.doe@example.com is in the administrators group. There are two cluster authorization rules:

apiVersion: deckhouse.io/v1
kind: ClusterAuthorizationRule
metadata:
  name: jane
spec:
  subjects:
    - kind: User
      name: jane.doe@example.com
  accessLevel: User
  namespaceSelector:
    labelSelector:
      matchLabels:
        env: review
---
apiVersion: deckhouse.io/v1
kind: ClusterAuthorizationRule
metadata:
  name: admin
spec:
  subjects:
  - kind: Group
    name: administrators
  accessLevel: ClusterAdmin
  namespaceSelector:
    labelSelector:
      matchExpressions:
      - key: env
        operator: In
        values:
        - prod
        - stage

1. jane.doe@example.com has the right to get and list any objects in the namespaces labeled env=review
2. Administrators can get, edit, list, and delete objects on the cluster level and in the namespaces labeled env=prod and env=stage.

Because Jane Doe matches two rules, some calculations will be made:

• She will have the most powerful accessLevel across all matching rules — ClusterAdmin.
• The namespaceSelector options will be combined, so that Jane will have access to all the namespaces labeled with env label of the following values: review, stage, or prod.

Note! If there is a rule without the namespaceSelector option and limitNamespaces deprecated option, it means that all namespaces are allowed excluding system namespaces, which will affect the resulting limit namespaces calculation.

How do I extend a role or create a new one?

The experimental role model is based on the aggregation principle; it compiles smaller roles into larger ones, thus providing easy ways to enhance the model with custom roles.

Creating a new role subsystem

Suppose that the current subsystems do not fit the role distribution in the company. You need to create a new subsystem that includes roles from the deckhouse subsystem, the kubernetes subsystem and the user-authn module.

To meet this need, create the following role:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: custom:manage:mycustom:manager
  labels:
    rbac.deckhouse.io/use-role: admin
    rbac.deckhouse.io/kind: manage
    rbac.deckhouse.io/level: subsystem
    rbac.deckhouse.io/subsystem: custom
    rbac.deckhouse.io/aggregate-to-all-as: manager
aggregationRule:
  clusterRoleSelectors:
    - matchLabels:
        rbac.deckhouse.io/kind: manage
        rbac.deckhouse.io/aggregate-to-deckhouse-as: manager
    - matchLabels:
        rbac.deckhouse.io/kind: manage
        rbac.deckhouse.io/aggregate-to-kubernetes-as: manager
    - matchLabels:
        rbac.deckhouse.io/kind: manage
        module: user-authn
rules: []

The labels for the new role listed at the top suggest that:

• the hook will use this use role:

  rbac.deckhouse.io/use-role: admin
  

• the role must be treated as a managed one:

  rbac.deckhouse.io/kind: manage
  

  Note that this label is mandatory!

• the role is a subsystem one, and it shall be handled accordingly:

  rbac.deckhouse.io/level: subsystem
  

• there is a subsystem for which the role is responsible:

  rbac.deckhouse.io/subsystem: custom
  

• the manage:all role can aggregate this role:

  rbac.deckhouse.io/aggregate-to-all-as: manager
  

Then there are selectors that implement aggregation:

• this one aggregates the manager role from the deckhouse subsystem:

  rbac.deckhouse.io/kind: manage
  rbac.deckhouse.io/aggregate-to-deckhouse-as: manager
  

• this one aggregates all the rules defined for the user-authn module:

   rbac.deckhouse.io/kind: manage
   module: user-authn
  

This way, your role will combine permissions of the deckhouse subsystem, kubernetes subsystem, and the user-authn module.

Notes:

• there are no restrictions on role name, but we recommend following the same pattern for the sake of readability;
• use-roles will be created in aggregate subsystems and the module namespace, the role type is specified by the label.

Extending the custom role

Suppose a new cluster CRD object, MySuperResource, has been created in the cluster (a manage role example), and you need to extend the custom role from the example above to include the permissions to interact with this resource.

First, you have to add a new selector to the role:

rbac.deckhouse.io/kind: manage
rbac.deckhouse.io/aggregate-to-custom-as: manager

This selector would enable roles to be aggregated to a new subsystem by specifying this label. After adding the new selector, the role will look as follows:

 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
   name: custom:manage:mycustom:manager
   labels:
     rbac.deckhouse.io/use-role: admin
     rbac.deckhouse.io/kind: manage
     rbac.deckhouse.io/level: subsystem
     rbac.deckhouse.io/subsystem: custom
     rbac.deckhouse.io/aggregate-to-all-as: manager
 aggregationRule:
   clusterRoleSelectors:
     - matchLabels:
         rbac.deckhouse.io/kind: manage
         rbac.deckhouse.io/aggregate-to-deckhouse-as: manager
     - matchLabels:
         rbac.deckhouse.io/kind: manage
         rbac.deckhouse.io/aggregate-to-kubernetes-as: manager
     - matchLabels:
         rbac.deckhouse.io/kind: manage
         module: user-authn
     - matchLabels:
         rbac.deckhouse.io/kind: manage
         rbac.deckhouse.io/aggregate-to-custom-as: manager
 rules: []

Next, you need to create a new role and define permissions for the new resource, e. g., the read-only permission:

 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
   labels:
     rbac.deckhouse.io/aggregate-to-custom-as: manager
     rbac.deckhouse.io/kind: manage
   name: custom:manage:permission:mycustom:superresource:view
 rules:
 - apiGroups:
   - mygroup.io
   resources:
   - mysuperresources
   verbs:
   - get
   - list
   - watch

The role will update the subsystem role to include its rights, so that the role bearer will be able to view the new object.

Notes:

• there are no restrictions on capability names, but we recommend following the same pattern for the sake of readability.

Extending the existing manage subsystem roles

To extend an existing role, follow the procedure outlined in the section above. Be sure to change the labels and the role name!

For example, here’s how you can extend the manager role from the deckhouse(d8:manage:deckhouse:manager) subsystem:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  labels:
    rbac.deckhouse.io/aggregate-to-deckhouse-as: manager
    rbac.deckhouse.io/kind: manage
  name: custom:manage:permission:mycustom:superresource:view
rules:
- apiGroups:
  - mygroup.io
  resources:
  - mysuperresources
  verbs:
  - get
  - list
  - watch

This way, the new role will extend the d8:manage:deckhouse:manager role.

Extending manage subsystem roles and adding a new namespace

If you need to create a new namespace (to create a use role in it by the hook), you only need to add one label:

"rbac.deckhouse.io/namespace": namespace

This label instructs the hook to create a use role in this namespace:

 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
   labels:
     rbac.deckhouse.io/aggregate-to-deckhouse-as: manager
     rbac.deckhouse.io/kind: manage
     rbac.deckhouse.io/namespace: namespace
   name: custom:manage:permission:mycustom:superresource:view
 rules:
 - apiGroups:
   - mygroup.io
   resources:
   - mysuperresources
   verbs:
   - get
   - list
   - watch

The hook monitors ClusterRoleBinding, and when creating a bindings, it loops through all the manage roles to find all the aggregated roles by checking the aggregation rule. It then fetches the namespace from the rbac.deckhouse.io/namespace label and creates a use role in that namespace.

Extending the existing use roles

If the resource belongs to a namespace, you need to extend the use role instead of the manage role. The only difference is the labels and the name:

 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
   labels:
     rbac.deckhouse.io/aggregate-to-kubernetes-as: user
     rbac.deckhouse.io/kind: use
   name: custom:use:capability:mycustom:superresource:view
 rules:
 - apiGroups:
   - mygroup.io
   resources:
   - mysuperresources
   verbs:
   - get
   - list
   - watch

This role will be added to the d8:use:role:user:kubernetes role.