Access control
Controller access on Datasance PoT uses one Role object for two callers.
- A person or group calls the Controller HTTP API. The token is OIDC. A RoleBinding grants a Role to a User or Group subject.
- A workload uses a ServiceAccount. That identity belongs to one application. A microservice names the Role with
spec.serviceAccount.roleRef.
Sign-in and user records stay in Get started: Embedded OIDC, External OIDC, and Identity and sign-in. This section is what an authenticated caller is allowed to do.
| Page | What it covers |
|---|---|
| Roles | Rules for one namespace. Create, replace, and the resource list. |
| Role fields | rules at the document root. |
| Role bindings | One Role granted to subjects. |
| RoleBinding fields | roleRef and subjects at the document root. |
| Service accounts | Application-scoped identity. CLI name application/name. |
| ServiceAccount fields | metadata.applicationName and root roleRef. |
Deploy with potctl deploy -f. There is no apply.
Subjects a workload may use on the bus are account rules and user rules. Permission checks on the Edgelet API are API RBAC. A Kubernetes Role from the operator install is a different object. See Kubernetes.
Request path
A human caller sends an OIDC bearer token. The Controller maps the route to a resource and a verb. RoleBindings for that User and Group decide whether the Role allows the pair.
| Subject | Claim on the token |
|---|---|
| User | preferred_username, username, email, or sub |
| Group | resource_access[<client id>].roles, roles, or groups, lowercased |
Group names should match the identity provider role names. admin, developer, and viewer are the usual examples.
| Route class | Token | Role check |
|---|---|---|
| Public | None | None |
| Auth-only | Bearer token | Skipped. The catalog verb list is empty. |
| User RBAC | Bearer token | Resource and verb from the route |
| Fog token | Fog provisioning token | Separate from this user RBAC |
Public routes include GET /api/v3/live, GET /api/v3/status, and GET /api/v3/architectures/. Auth-only routes include POST /api/v3/user/login and the OAuth browser routes. Routes under /api/v3/agent/* use a fog provisioning token. They are not this user RBAC.
When the token carries password_change_required, the caller may only use GET /api/v3/user/profile and POST /api/v3/user/change-password. Other protected routes return 403 until the password changes.
The route list is the Controller API.
System roles
admin cannot be modified or deleted.
| Role | Scope |
|---|---|
admin | All resources, all verbs |
sre | Operational resources. Read-only on roles, roleBindings, and the NATS operator, bootstrap, and hub resources |
developer | Create and update workloads. Read-only on infrastructure |
viewer | get and list |
agent-admin | Edgelet API group. Not a human Controller user |
microservice | Limited self-service on the Edgelet API group for a running workload |
agent-admin and microservice are for the Edgelet API group. See API RBAC.
Which resources sre, developer, and viewer include is on Roles.
Verbs
| Verb | Typical HTTP |
|---|---|
get | GET one resource, HEAD |
list | GET a collection |
create | POST |
update | PUT |
patch | PATCH, and some POST actions such as start and stop |
delete | DELETE |
WebSocket routes use get. Some sub-resource actions use patch.
Workload stack
Deploy in this order: Role, then RoleBinding, then ServiceAccount, then the microservice that names the account. Inside one file, the CLI sorts kinds in that order.
metadata.applicationName on the ServiceAccount must match an Application. The CLI name is application/name. Deploy the Application first when that name is not already on the Controller.
# The CLI deploys Role, then RoleBinding, then ServiceAccount.
# metadata.applicationName must match an Application.
apiVersion: datasance.com/v3
kind: Role
metadata:
name: app-worker
namespace: my-ecn
rules:
- apiGroups: [""]
resources: ["microservices"]
verbs: ["get", "list"]
---
apiVersion: datasance.com/v3
kind: RoleBinding
metadata:
name: app-worker-binding
namespace: my-ecn
roleRef:
kind: Role
name: app-worker
subjects:
- kind: ServiceAccount
name: worker
apiGroup: ""
---
apiVersion: datasance.com/v3
kind: ServiceAccount
metadata:
name: worker
namespace: my-ecn
applicationName: my-app
roleRef:
kind: Role
name: app-worker
The microservice then sets spec.serviceAccount.roleRef to that Role. See Microservices.
Console
Roles, Role Bindings, and Service Accounts are on Access control. NATS account rules and NATS user rules on that same screen are Message bus.
When a call returns 403
Check the RoleBinding for the OIDC user or group, and the verbs on that resource. A token with password_change_required also returns 403 outside the profile and change-password routes.
A denied publish or subscribe on the bus is a user rule or an account rule. Audit rows are under Events and API.