Authorization Concepts#

This page explains the core concepts of the NeMo Microservices Platform authorization system and how they work together to control access to resources.

Authorization Model Overview#

The NeMo Microservices Platform uses a workspace-scoped, role-based access control (RBAC) model. This means:

  1. All resources (models, datasets, jobs, etc.) belong to a workspace

  2. Access is controlled by granting roles to principals within specific workspaces

  3. Each role contains a set of permissions that determine allowed operations

  4. API tokens can have scopes that further restrict access

Core Concepts#

Workspaces#

Workspaces are the fundamental authorization boundary in NMP. They serve as logical containers for organizing and controlling access to resources.

Key characteristics:

  • Every resource (model, dataset, evaluation job, etc.) belongs to exactly one workspace

  • Access control is enforced at the workspace level

  • When you create a workspace, you automatically become its Admin

Workspace Access Levels#

Workspaces can have different access levels based on role bindings:

  • Private: Only explicitly granted members can access (no wildcard binding)

  • Shared read-only: All authenticated users can view resources (Viewer role for *)

  • Shared read-write: All authenticated users can create and modify resources (Editor role for *)

Principals#

Principals represent authenticated identities that can access the platform. Principals are typically human users identified by their email address.

Each principal can have different roles in different workspaces:

alice@company.com:
  - Admin in workspace "team-ml"
  - Editor in workspace "shared-datasets"
  - Viewer in workspace "prod-models"

Wildcard Principal#

The special principal * (asterisk) represents all authenticated users. Granting a role to * in a workspace gives that access level to everyone who authenticates with the platform.

This is the mechanism for creating shared workspaces:

Workspace: "shared-datasets"
├── Role Binding: principal="*", role="Viewer"     # Everyone can read
└── Role Binding: principal="alice@company.com", role="Admin"  # Alice manages

Roles#

Roles are named collections of permissions. When you grant a role to a principal in a workspace, they receive all permissions included in that role.

Predefined Roles#

NMP provides three standard roles:

Viewer - Read-only access

  • List and view all resources in the workspace

  • Run inference on deployed models

  • View evaluation results, job logs, and other workspace resources

  • Cannot create, update, or delete resources

Editor - Read and write access

  • All Viewer permissions

  • Create, update, and delete resources

  • Run evaluations, customization jobs, and other operations

  • Cannot manage workspace settings or members

Admin - Full workspace control

  • All Editor permissions

  • Manage workspace members (add/remove users, assign roles)

  • Grant access to all users via the wildcard principal *

  • Full administrative control over the workspace

Platform Admin Role#

The PlatformAdmin role is a special highly privileged role that provides full access to all workspaces and all operations across the entire platform. This role is typically reserved for platform operators.

Platform admins can:

  • Access all workspaces regardless of explicit role grants

  • Manage global platform configuration

  • Create and delete any workspace

  • Bypass all authorization checks

Role Bindings#

Role bindings associate a principal with a role in a specific workspace. This is how you actually grant access.

A role binding contains:

  • Principal: The user being granted access (e.g., alice@company.com)

  • Workspace: The workspace where access is granted (e.g., team-ml)

  • Role: The role being assigned (e.g., Editor)

Example role bindings:

Workspace: "team-ml-research"
├── Role Binding 1
│   ├── Principal: "alice@company.com"
│   └── Role: "Admin"
│
├── Role Binding 2
│   ├── Principal: "bob@company.com"
│   └── Role: "Editor"
│
└── Role Binding 3
    ├── Principal: "charlie@company.com"
    └── Role: "Viewer"

API Scopes#

In addition to role-based permissions, NMP supports API scopes as a coarse-grained access control mechanism at the token level.

How Scopes Work#

API scopes are specified when creating authentication tokens and define which parts of the API the token can access. They follow the format resource-group:access-type.

Common scopes:

  • models:read, models:write - Access to models APIs

  • datasets:read, datasets:write - Access to datasets APIs

  • evaluation:read, evaluation:write - Access to evaluation APIs

  • customization:read, customization:write - Access to customization APIs

  • inference:read, inference:write - Access to inference APIs

  • platform:read, platform:write - Broad platform access

Two-Layer Authorization#

For a request to succeed, it must satisfy both requirements:

  1. Token scope check: The API token must have at least one of the endpoint’s required scopes

  2. Permission check: The principal must have the required permissions through role grants in the workspace

This allows you to create tokens with limited access (e.g., read-only token with models:read scope) even if the user has broader permissions (e.g., Editor role with write permissions).

Automatic Role Assignment#

Workspace Creation#

Creating a workspace is a special operation:

  • All authenticated users can create workspaces (no special permission needed)

  • The creator automatically receives the Admin role

  • New workspaces are private by default (only the creator has access)

  • You can immediately start creating resources

Default Workspaces#

NMP automatically provisions role bindings for the wildcard principal * on certain workspaces:

  • default workspace: All authenticated users have Editor role, allowing everyone to create and manage resources immediately

  • system workspace: All authenticated users have Viewer role, providing read-only access to system-level resources

Workspace Visibility#

Users only see workspaces they have access to. When listing workspaces, the API returns only workspaces where the user has at least one role binding (direct or via wildcard *).

If a user tries to access a workspace they don’t have permission for, the API returns 403 Forbidden rather than 404 Not Found. This is intentional security behavior—it avoids revealing whether a workspace exists to unauthorized users.

Workspace Deletion#

A workspace cannot be deleted if it contains resources (projects, datasets, models, etc.). The deletion fails with a 409 Conflict error that lists which entity types exist. You must delete these resources first before deleting the workspace.

Best Practices#

  1. Principle of least privilege: Grant users the minimum role they need (Viewer unless they need to create/modify resources)

  2. Use workspaces for isolation: Create separate workspaces for different teams or projects

  3. Limit token scopes: When creating API tokens, include only the scopes needed for the specific use case

  4. Review access regularly: Periodically audit workspace members and remove access that’s no longer needed

  5. Use wildcard bindings carefully: Only grant the * principal a role when you intentionally want to share access with all authenticated users. Use Viewer for read-only sharing; avoid Editor unless everyone truly needs write access