freeleaps-ops/cluster/manifests/rbac-guide.md

# RBAC with Azure AD

First of all, we using OIDC to authenticate the users on Azure AD.

Which means we could get user's information from the token signed by Azure AD.

Below is the example of the token we got from Azure AD:

```json
{
  "aud": "7cd1df19-24ea-46d7-acd3-5336283139e0",
  "iss": "https://login.microsoftonline.com/cf151ee8-5c2c-4fe7-a1c4-809ba43c9f24/v2.0",
  "iat": 1747014804,
  "nbf": 1747014804,
  "exp": 1747018704,
  "aio": "AZQAa/8ZAAAAWDc1mcHgKt+Gb76ZbKKjBtztKcWhBIY2ye1PUSoyBL/TBvoIpA+JG7lsgWwQVQgc7X12fxRgAeg2Xo6VeO52Oy7HEKw4xx+TrECr2CJ8/nIoihxj+7+jSqLAOapWj5IfA54/p94F4jUFCJmXkx0RwVryE34A76wx4I+NDu8DbFt26Q5+b5Q0z/n9rmir8vVF",
  "email": "zhenyus@mathmast.com",
  "given_name": "Zhenyu",
  "groups": [
    "d8bacaf3-ce4a-48c3-82d9-477f5b1d04c4",
    "302556e5-c211-4f38-b482-2062d104c679"
  ],
  "name": "Zhenyu Sun",
  "nonce": "X6g5RW8_uFPrwloyWwpqnO40X5GXME-f-M-ggFBLl2c",
  "oid": "561acbe7-0ad9-421d-ba33-1142e7ce40c4",
  "preferred_username": "zhenyus@mathmast.com",
  "rh": "1.AX0A6B4Vzyxc50-hxICbpDyfJBnf0XzqJNdGrNNTNigxOeCaAO99AA.",
  "roles": [
    "mathmast:admin",
    "mathmast:data-platform-contributor"
  ],
  "sid": "002e6ae9-0dee-d68c-4192-e4173e82e375",
  "sub": "7Cea6-mcTSg9rfufy_dBltWoNzoe8wa0LSTKtiOcGZM",
  "tid": "cf151ee8-5c2c-4fe7-a1c4-809ba43c9f24",
  "upn": "zhenyus@mathmast.com",
  "uti": "5d9WJEXnFUmoEkqynxRFAA",
  "ver": "2.0",
  "wids": [
    "b79fbf4d-3ef9-4689-8143-76b194e85509"
  ]
}
```

As you can see, the `roles` field contains the Azure AD group that the user belongs to.

We can using this field with `ClusterRole` and `RoleBinding` to restrict the access to the namespace. 

## RBAC 101

### Create new role on Azure AD

1. Go to Azure AD portal.
2. Enter `Microsoft  Entra ID` console.
3. Click `App registrations` in left side menus.
4. Enter console page for `Freeleaps Kubernetes Cluster`.
5. Click `App roles` in left side menus.
6. Click `Create app role` button.
7. Fill in the form:
    - `Display name`: Your role name.
    - `Allowed member types`: `Users/Groups`.
    - `Value`: Your role code name preferably in `mathmast:role-name` format (must be unique).
    - Check `Do you want to enable this app role?` checkbox.

OK, you have created a new role on Azure AD.

Lets assign this role to your account.

### Assign role to your account

1. Go to Azure AD portal.
2. Enter `Microsoft  Entra ID` console.
3. Click `Enterprise applications` in left side menus.
4. Enter console page for `Freeleaps Kubernetes Cluster`.
5. Click `Users and groups` in left side menus.
6. Click `Add user/group` button.
7. Select users or groups you want to assign the role to.
8. Submit the form to assign the role to the users.

### Create `ClusterRole` and `RoleBinding` for your role

Now we need create a `ClusterRole` and `RoleBinding` for the role we just created.

Create file named `rbac.yaml` in the namespace directory you want to restrict.

Create a `ClusterRole` for your role:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: role-name
rules: [] // please refer to the official document for the rules
```

Create a `RoleBinding` for your role:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: role-name
  namespace: namespace-you-want-to-restrict
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: role-name
subjects:
  - kind: Group
    name: mathmast:role-name
    apiGroup: rbac.authorization.k8s.io
```

Apply the `ClusterRole` and `RoleBinding` to the cluster:

```bash
kubectl apply -f rbac.yaml
```

### Test the role

Now you can test the role by using `kubectl` command.

```bash
kubectl auth can-i --list=true --namespace=namespace-you-want-to-restrict
```

You should see the permissions you assigned to the role.
If you see `no` in the output, please check the following:

- The role is assigned to the user.
- The `ClusterRole` and `RoleBinding` are created in the correct namespace.
- Using `freeleaps-cluster-authenticator --ra` to refresh authentication state when you assigned new roles to your account.