# Authorization Guide > **Control Plane migration:** the classic dashboard UI and port 57374 are removed in Loki Mode 10.8; the UI is the Control Plane (`loki dashboard`, default port 47821). Examples below that use port 57374 or `/api/*` describe the legacy API server. See [control-plane-migration.md](control-plane-migration.md) for the `/v1/*` mapping and what is not yet available. Role-based access control (RBAC) for Loki Mode. ## Overview Loki Mode implements a four-tier RBAC system that controls access to dashboard operations, API endpoints, and agent actions. RBAC integrates with both token-based authentication and OIDC/SSO. ## Role Definitions ### Admin Full access to all operations and configuration. **Scopes:** `*` (all) **Permissions:** - Start/stop/pause/resume sessions - Create/update/delete tasks - Modify configuration - Generate/revoke tokens - View audit logs - Manage users and roles - Access all API endpoints **Use Cases:** - System administrators - DevOps engineers - Project owners ### Operator Day-to-day operations without configuration changes. **Scopes:** `control`, `read`, `write` **Permissions:** - Start/stop/pause/resume sessions - Create/update tasks - View dashboard and logs - Execute agent actions - Access metrics endpoint **Cannot:** - Modify system configuration - Manage tokens or users - View audit logs (except their own actions) **Use Cases:** - Developers - CI/CD pipelines - Automated workflows ### Viewer Read-only access to dashboard and logs. **Scopes:** `read` **Permissions:** - View dashboard status - View task queue - View logs and events - View metrics - View agent activity **Cannot:** - Start/stop sessions - Create/modify tasks - Access audit logs - Modify any state **Use Cases:** - Stakeholders - Project managers - External observers ### Auditor Security and compliance monitoring. **Scopes:** `read`, `audit` **Permissions:** - View dashboard status - View task queue and logs - Access audit logs - View agent action history - Export compliance reports **Cannot:** - Start/stop sessions - Create/modify tasks - Modify configuration **Use Cases:** - Security teams - Compliance officers - Internal auditors ## Configuration ### Enable enterprise auth There is no separate `LOKI_RBAC_ENABLED` switch. Role mapping is part of the enterprise auth path, enabled by `LOKI_ENTERPRISE_AUTH` for token auth and by `LOKI_OIDC_ISSUER` + `LOKI_OIDC_CLIENT_ID` for OIDC/SSO (`dashboard/auth.py`). ```bash export LOKI_ENTERPRISE_AUTH=true loki start ./prd.md ``` ### Assign scopes via tokens `loki enterprise token generate` takes `--scopes` (a comma-separated scope list), not a `--role` flag. Roles as such are resolved from OIDC claims; tokens carry scopes directly. ```bash # Generate token with scopes loki enterprise token generate dev-1 --scopes control,read,write --expires 30 loki enterprise token generate viewer-1 --scopes read --expires 90 loki enterprise token generate auditor-1 --scopes read,audit --expires 180 loki enterprise token generate admin-1 --scopes '*' --expires 365 ``` ### Configuration File ```yaml # .loki/config.yaml enterprise: rbac: enabled: true default_role: viewer # Default for OIDC users without role mapping enforce_mfa: false # Require MFA for admin role (future) roles: admin: scopes: ["*"] operator: scopes: ["control", "read", "write"] viewer: scopes: ["read"] auditor: scopes: ["read", "audit"] ``` ### OIDC Role Mapping Map OIDC claims to Loki roles: ```yaml enterprise: rbac: oidc_role_mapping: # Map Google Groups to roles google: admins@example.com: admin devops@example.com: operator viewers@example.com: viewer # Map Azure AD groups to roles azure: 12345678-abcd-1234-abcd-123456789abc: admin # Group Object ID 87654321-dcba-4321-dcba-987654321cba: operator ``` ## Scope-Based Access Control ### Scope Hierarchy ``` * (all) ├── control │ ├── write │ │ └── read │ └── read ├── audit │ └── read └── read ``` Scopes are additive: - `control` automatically includes `write` and `read` - `write` automatically includes `read` - `audit` requires separate grant (not included in `*`) ### Endpoint Permissions | Endpoint | Required Scope | Roles with Access | |----------|----------------|-------------------| | `GET /api/status` | `read` | All roles | | `GET /api/tasks` | `read` | All roles | | `GET /api/logs` | `read` | All roles | | `GET /metrics` | `read` | All roles | | `POST /api/tasks` | `write` | Operator, Admin | | `PATCH /api/tasks/:id` | `write` | Operator, Admin | | `POST /api/control/start` | `control` | Operator, Admin | | `POST /api/control/stop` | `control` | Operator, Admin | | `GET /api/audit` | `audit` | Auditor, Admin | | `POST /api/enterprise/tokens` | `*` | Admin only | | `DELETE /api/enterprise/tokens/:id` | `*` | Admin only | | `POST /api/config` | `*` | Admin only | ## Permission Checks ### CLI There is no `loki enterprise rbac` subcommand. `loki enterprise` has exactly `status`, `token`, and `audit`. To see what a token can do, list the tokens and read their scopes: ```bash loki enterprise token list loki enterprise status ``` ### API There is no `/api/enterprise/rbac/check` endpoint; an earlier version of this page documented one along with a `permissions` response object, and neither exists. Scopes are enforced per-route: each `/api/*` route declares the scope it requires via `Depends(auth.require_scope(...))` in `dashboard/server.py`. A request either succeeds or is rejected, so exercise the route you care about: ```bash # Succeeds only if the token carries the route's required scope curl -i -H "Authorization: Bearer $LOKI_TOKEN" \ http://localhost:57374/api/status ``` Scope implication is resolved by `has_scope()` in `dashboard/auth.py:394`. ## Agent Action Authorization **Not implemented.** An earlier version of this page showed an `enterprise.rbac.agent_actions` block mapping individual agent actions (`git_commit`, `cli_invoke`, `file_write`, `file_read`) to required scopes. No such configuration is read by any code. Scope enforcement happens at the dashboard API boundary only, per route, not per agent action. ## Environment Variables These are the variables actually read by `dashboard/auth.py`. There is no `LOKI_RBAC_ENABLED`, `LOKI_RBAC_STRICT_MODE`, or `LOKI_RBAC_AUDIT_CHECKS`; an earlier version of this page listed all three and they were never implemented. | Variable | Default | Description | |----------|---------|-------------| | `LOKI_ENTERPRISE_AUTH` | `false` | Enable token authentication | | `LOKI_OIDC_ISSUER` | (empty) | OIDC issuer URL; set with `LOKI_OIDC_CLIENT_ID` to enable OIDC/SSO | | `LOKI_OIDC_CLIENT_ID` | (empty) | OIDC client id | | `LOKI_OIDC_AUDIENCE` | (empty) | Expected audience; usually the same as the client id | | `LOKI_OIDC_ROLES_CLAIM` | (empty) | Claim to read roles from; supports a dotted path | | `LOKI_OIDC_DEFAULT_ROLE` | `viewer` | Role applied when no recognized role claim is present | `_scopes_from_claims()` never returns `["*"]`/admin by default: full access requires an explicit admin role claim. When no recognized role claim is present, the least-privileged default role applies. ## Examples ### Multi-Environment Setup ```bash # Production - OIDC with a least-privilege default export LOKI_ENTERPRISE_AUTH=true export LOKI_OIDC_ISSUER=https://accounts.example.com export LOKI_OIDC_CLIENT_ID=loki-prod export LOKI_OIDC_DEFAULT_ROLE=viewer # Development - auth off export LOKI_ENTERPRISE_AUTH=false # Staging - OIDC with a more permissive default export LOKI_ENTERPRISE_AUTH=true export LOKI_OIDC_DEFAULT_ROLE=operator ``` ### Team-Based Access ```yaml # .loki/config.yaml enterprise: rbac: oidc_role_mapping: google: engineering@company.com: operator qa@company.com: operator product@company.com: viewer security@company.com: auditor devops@company.com: admin ``` ### Service Account Tokens ```bash # CI/CD pipeline token loki enterprise token generate github-actions \ --scopes control,read,write \ --scopes "control,read,write" \ --expires 365 # Monitoring system token loki enterprise token generate datadog \ --scopes read \ --scopes "read" \ --expires 9999 # Security scanner token loki enterprise token generate security-scanner \ --scopes read,audit \ --scopes "read,audit" \ --expires 180 ``` ## Best Practices ### Principle of Least Privilege 1. Start with minimal permissions (viewer role) 2. Grant additional scopes only as needed 3. Review and audit role assignments quarterly 4. Remove unused tokens immediately ### Role Assignment 1. Use OIDC role mapping for human users 2. Use token-based roles for automation 3. Separate production and development roles 4. Document role assignments and justifications 5. Rotate credentials regularly ### Auditing 1. Review audit logs for authentication and authorization events (audit logging is on by default; there is no separate per-permission-check toggle) 2. Review audit logs for unauthorized access attempts 3. Monitor for privilege escalation attempts 4. Alert on admin role usage in production 5. Generate compliance reports monthly ## Troubleshooting ### Permission Denied Errors ```bash # Check token role and scopes loki enterprise token list # Read the route's required scope from dashboard/server.py, then compare # against the scopes on your token from the listing above # Check recent audit entries for the denial loki enterprise audit tail # Generate new token with correct role loki enterprise token revoke loki enterprise token generate --scopes control,read,write ``` ### OIDC Role Mapping Not Working ```bash # Verify OIDC claims contain group information # Check identity provider configuration # Test with explicit token role first loki enterprise token generate test-admin --scopes '*' # Check which claim carries the roles echo "$LOKI_OIDC_ROLES_CLAIM" # View recent audit entries loki enterprise audit tail ``` ### Scope Confusion ```bash # List the scopes actually attached to each token loki enterprise token list # Check if scope is implied by hierarchy (see has_scope, dashboard/auth.py:394) # control -> write -> read # audit (separate, not included in control) # Test specific permission curl -H "Authorization: Bearer $TOKEN" \ http://localhost:57374/api/enterprise/rbac/check?scope=control ``` ## Migration Guide ### Upgrading from Token-Only to role-mapped OIDC There is no separate "RBAC mode" to switch on, and no in-place token editing. `loki enterprise` has exactly three subcommands: `status`, `token`, and `audit`. An earlier version of this page described `loki enterprise rbac check` and `loki enterprise token update --role`; neither exists. 1. Turn on enterprise auth and point Loki at your identity provider: ```bash export LOKI_ENTERPRISE_AUTH=true export LOKI_OIDC_ISSUER=https://accounts.example.com export LOKI_OIDC_CLIENT_ID=your-client-id export LOKI_OIDC_DEFAULT_ROLE=viewer ``` 2. Re-issue tokens with the scopes each holder should have. Tokens carry scopes directly and are not editable after creation, so revoke and regenerate: ```bash loki enterprise token list loki enterprise token generate dev-1 --scopes control,read,write --expires 30 ``` 3. Confirm the configuration is active: ```bash loki enterprise status ``` 4. Monitor audit logs for denials and adjust the role claim mapping (`LOKI_OIDC_ROLES_CLAIM`) as needed. ## See Also - [Authentication Guide](authentication.md) - Token and OIDC setup - [Audit Logging](audit-logging.md) - Track permission checks - [Enterprise Features](../wiki/Enterprise-Features.md) - Complete enterprise guide - [Network Security](network-security.md) - Additional security controls