shotgrid-casbin-adapter¶

A Casbin policy adapter that enables loading and saving access control policies from/to Autodesk ShotGrid (formerly Shotgun).

Installation¶

pip install shotgrid-casbin-adapter

Quick Start¶

Basic Usage¶

import casbin
from shotgrid_casbin_adapter import Adapter

# Using environment variables (SHOTGRID_URL, SHOTGRID_SCRIPT_NAME, SHOTGRID_API_KEY)
adapter = Adapter()

# Or pass connection parameters directly
adapter = Adapter(
    base_url="https://your-studio.shotgridstudio.com",
    script_name="casbin_script",
    api_key="your_api_key",
)

# Scope to a specific project (one adapter = one project's policies)
adapter = Adapter(
    base_url="https://your-studio.shotgridstudio.com",
    script_name="casbin_script",
    api_key="your_api_key",
    project_id=42,
)

e = casbin.Enforcer("model.conf", adapter)

sub = "alice"
obj = "data1"
act = "read"

if e.enforce(sub, obj, act):
    # permit alice to read data1
    pass
else:
    # deny the request
    pass

Integration with FastAPI¶

Use this adapter with fastapi-authz to add Casbin-based authorization to your FastAPI application:

import casbin
from fastapi import FastAPI
from fastapi_authz import CasbinMiddleware
from starlette.authentication import AuthenticationBackend, AuthCredentials, SimpleUser
from starlette.middleware.authentication import AuthenticationMiddleware

from shotgrid_casbin_adapter import Adapter

app = FastAPI()

# Set up the ShotGrid-backed Casbin enforcer
adapter = Adapter(
    base_url="https://your-studio.shotgridstudio.com",
    script_name="casbin_script",
    api_key="your_api_key",
)
enforcer = casbin.Enforcer("rbac_model.conf", adapter)


# Authentication backend (example with basic auth)
class BasicAuthBackend(AuthenticationBackend):
    async def authenticate(self, request):
        if "Authorization" not in request.headers:
            return None
        # ... your authentication logic ...
        username = "alice"
        return AuthCredentials(["authenticated"]), SimpleUser(username)


# Add middleware (order matters: auth first, then Casbin)
app.add_middleware(CasbinMiddleware, enforcer=enforcer)
app.add_middleware(AuthenticationMiddleware, backend=BasicAuthBackend())


@app.get("/dataset1/{item}")
async def access_dataset(item: str):
    return {"message": f"Access granted to dataset1/{item}"}

Example rbac_model.conf:

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

CLI Usage¶

Create Casbin fields on a ShotGrid custom entity type and seed a default admin policy:

Prerequisite: The custom entity type must already be enabled in ShotGrid (Site Preferences > Entities). The init command only creates fields on an existing entity type — it cannot create the entity type itself.

# Using just (loads .env automatically)
just sgca-init CustomEntity39

# Or using environment variables directly
export SHOTGRID_URL="https://your-studio.shotgridstudio.com"
export SHOTGRID_SCRIPT_NAME="casbin_script"
export SHOTGRID_API_KEY="your_api_key"
sgca init

# Or pass parameters via CLI options
sgca init \
    --base-url "https://your-studio.shotgridstudio.com" \
    --script-name "casbin_script" \
    --api-key "your_api_key"

# Specify a custom entity type (must already exist in ShotGrid)
sgca init --entity-type "CustomEntity01"

# Scope the admin policy to a specific project
sgca init --entity-type "CustomEntity39" --project-id 42

The init command creates the fields and seeds a default admin policy (p, admin, *, *) so the adapter is ready to use immediately. If --project-id is provided, the admin policy is scoped to that project.

If the entity type does not exist, the command will report an error and remind you to enable it in Site Preferences first.

The init command creates the following fields on the entity type:

Field	Type	Description
`ptype`	text	Policy type (e.g. `p`, `g`)
`v0`	text	First policy value (subject)
`v1`	text	Second policy value (object)
`v2`	text	Third policy value (action)
`v3`	text	Fourth policy value
`v4`	text	Fifth policy value
`v5`	text	Sixth policy value

Environment Variables¶

Variable	Description	Required
`SHOTGRID_URL`	ShotGrid server URL	Yes*
`SHOTGRID_SCRIPT_NAME`	Script name for authentication	Yes*
`SHOTGRID_API_KEY`	API key for authentication	Yes*
`SHOTGRID_ENTITY_TYPE`	Custom entity type name (default: `CustomEntity01`)	No
`SHOTGRID_PROJECT_ID`	ShotGrid project ID for scoping operations	No

* Required when not passing connection parameters directly to the Adapter constructor.

Adapter API¶

`Adapter(sg=None, base_url=None, script_name=None, api_key=None, entity_type=None, project_id=None, filtered=False)`¶

Parameter	Type	Description
`sg`	`shotgun_api3.Shotgun`	Existing ShotGrid connection. If provided, other params ignored.
`base_url`	`str`	ShotGrid server URL. Falls back to `SHOTGRID_URL` env var.
`script_name`	`str`	Script name. Falls back to `SHOTGRID_SCRIPT_NAME` env var.
`api_key`	`str`	API key. Falls back to `SHOTGRID_API_KEY` env var.
`entity_type`	`str`	Entity type name. Falls back to `SHOTGRID_ENTITY_TYPE` env var.
`project_id`	`int`	ShotGrid project ID. Falls back to `SHOTGRID_PROJECT_ID` env var. `None` = site-wide.
`filtered`	`bool`	Enable filtered policy loading. Default: `False`.

Supported Methods¶

Method	Description
`load_policy(model)`	Load all policies from ShotGrid
`save_policy(model)`	Save all policies to ShotGrid (replaces existing)
`add_policy(sec, ptype, rule)`	Add a single policy rule
`add_policies(sec, ptype, rules)`	Add multiple policy rules (batch)
`remove_policy(sec, ptype, rule)`	Remove a single policy rule
`remove_policies(sec, ptype, rules)`	Remove multiple policy rules (batch)
`remove_filtered_policy(sec, ptype, field_index, *field_values)`	Remove by filter
`load_filtered_policy(model, filter)`	Load policies matching a filter
`update_policy(sec, ptype, old_rule, new_rule)`	Update a single rule
`update_policies(sec, ptype, old_rules, new_rules)`	Update multiple rules
`update_filtered_policies(sec, ptype, new_rules, field_index, *field_values)`	Update by filter
`is_filtered()`	Check if adapter is in filtered mode

Project Scoping¶

ShotGrid sites contain multiple projects. By default, the adapter operates at site level — all policy rules across projects are mixed together. To isolate policies per project, bind a project_id at the Adapter level:

# One adapter per project — policies are automatically scoped
project_a_adapter = Adapter(sg=sg, project_id=1)
project_b_adapter = Adapter(sg=sg, project_id=2)

# Each enforcer only sees/modify its project's policies
enforcer_a = casbin.Enforcer("model.conf", project_a_adapter)
enforcer_b = casbin.Enforcer("model.conf", project_b_adapter)

When project_id is set: - All find() queries include a ["project", "is", {"type": "Project", "id": project_id}] filter - All create() operations link the entity to the project - When project_id is None (default), behavior is site-wide (backward compatible)

Soft Delete¶

ShotGrid's delete() operation retires entities rather than destroying them, and find() excludes retired records by default. This provides natural soft-delete behavior — retired policies are invisible to the adapter but can be restored via the ShotGrid UI if needed.

License¶

MIT