Skip to content

User Management

Complete guide to managing users, permissions, and scopes in S5 Slidefactory.

Overview

S5 Slidefactory uses scope-based authorization for fine-grained access control to workflows, templates, presentations, and resources.

Authentication (Who are you?) - Local users: Username/password in database - Azure AD (Entra): Microsoft SSO authentication

Authorization (What can you do?) - Scopes: Permissions like workflows:read, templates:write, presentations:generate - Wildcard: * grants full admin access - Hierarchical: Scopes can be global or resource-specific

Quick Start

Create Admin User

# Docker
docker-compose exec web slidefactory user create-local admin@example.com \
  --name "Admin User" \
  --preset admin

# Local
slidefactory user create-local admin@example.com \
  --name "Admin User" \
  --preset admin

Create Regular User

docker-compose exec web slidefactory user create-local user@example.com \
  --name "Regular User" \
  --preset user

Scope System

Scope Format

Scopes follow a hierarchical pattern: 

<resource>:<identifier>:<action>

Common Scopes

Scope Description
* Full access (superadmin)
workflows:* All workflow permissions
workflows:read View workflows
workflows:execute Execute workflows
templates:* All template permissions
templates:read View templates
templates:write Create/edit templates
presentations:* All presentation permissions
presentations:generate Generate presentations
presentations:read View presentations
admin:users Manage users
admin:settings Manage settings

Scope Presets

Admin (Full access): 

["*"]

User (Standard permissions): 

[
  "workflows:read",
  "workflows:execute",
  "templates:read",
  "presentations:*"
]

Viewer (Read-only): 

[
  "workflows:read",
  "templates:read",
  "presentations:read"
]

Workflow Manager: 

[
  "workflows:*",
  "templates:read",
  "presentations:*"
]

CLI Commands

Create Users

# Create local user with preset
docker-compose exec web slidefactory user create-local EMAIL \
  --name "NAME" \
  --preset admin|user|viewer

# Create with custom scopes
docker-compose exec web slidefactory user create-local EMAIL \
  --name "NAME" \
  --scopes '["workflows:read", "presentations:*"]'

# Create without password (prompt)
docker-compose exec web slidefactory user create-local EMAIL --name "NAME"

# Create with password
docker-compose exec web slidefactory user create-local EMAIL \
  --name "NAME" \
  --password "SecurePassword123!"

List Users

# List all users
docker-compose exec web slidefactory user list

# Output shows:
# email@example.com | Admin User | local | admin
# user@example.com  | Regular    | local | user

View User Details

# Show user details and scopes
docker-compose exec web slidefactory user show EMAIL

# Output includes:
# - Authentication provider
# - Display name
# - Scopes
# - Created date
# - Last login

Update Users

# Add scopes
docker-compose exec web slidefactory user add-scopes EMAIL \
  --scopes '["workflows:execute"]'

# Remove scopes
docker-compose exec web slidefactory user remove-scopes EMAIL \
  --scopes '["admin:settings"]'

# Set scopes (replace all)
docker-compose exec web slidefactory user set-scopes EMAIL \
  --scopes '["workflows:*", "templates:read"]'

Change Password

# Interactive prompt
docker-compose exec web slidefactory user change-password EMAIL

# With password argument (not recommended)
docker-compose exec web slidefactory user change-password EMAIL \
  --password "NewPassword123!"

Delete Users

# Delete user
docker-compose exec web slidefactory user delete EMAIL

# Force delete without confirmation
docker-compose exec web slidefactory user delete EMAIL --force

Azure AD (Entra) Integration

Configuration

Set environment variables:

# Azure AD Configuration
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret

# Application URL
APP_URL=https://slidefactory.yourcompany.com

Group-to-Scope Mapping

Map Azure AD groups to Slidefactory scopes:

# Environment variable format
ENTRA_GROUP_SCOPES='{
  "Slidefactory-Admins": ["*"],
  "Slidefactory-Users": ["workflows:read", "workflows:execute", "presentations:*"],
  "Slidefactory-Viewers": ["workflows:read", "presentations:read"]
}'

JIT (Just-In-Time) Provisioning

Users are automatically created on first login:

  1. User logs in via Azure AD
  2. Slidefactory checks if user exists
  3. If not, creates user with scopes from Azure AD groups
  4. User is logged in and can access resources

Example Flow: 

User: john@company.com
Azure AD Groups: ["Slidefactory-Users"]
↓
First Login via Azure AD
↓
User auto-created with scopes:
  - workflows:read
  - workflows:execute
  - presentations:*
↓
User logged in successfully

Manual Azure AD User Creation

You can pre-create Azure AD users:

# Create Azure AD user
docker-compose exec web slidefactory user create-entra john@company.com \
  --name "John Doe" \
  --preset user

Common Workflows

Setup: Create Initial Admin

# 1. Create admin user
docker-compose exec web slidefactory user create-local admin@yourcompany.com \
  --name "System Admin" \
  --preset admin

# 2. Verify creation
docker-compose exec web slidefactory user list

# 3. Login via web UI
# Visit: http://localhost:8000
# Login with admin@yourcompany.com

Add Team Members

# Create users for team
docker-compose exec web slidefactory user create-local alice@company.com \
  --name "Alice Smith" --preset user

docker-compose exec web slidefactory user create-local bob@company.com \
  --name "Bob Johnson" --preset user

# Verify
docker-compose exec web slidefactory user list

Grant Workflow Manager Access

# Create workflow manager
docker-compose exec web slidefactory user create-local manager@company.com \
  --name "Workflow Manager" \
  --scopes '["workflows:*", "templates:read", "presentations:*"]'

# Or upgrade existing user
docker-compose exec web slidefactory user add-scopes user@company.com \
  --scopes '["workflows:*"]'

Revoke Access

# Remove specific permission
docker-compose exec web slidefactory user remove-scopes user@company.com \
  --scopes '["presentations:generate"]'

# Downgrade to viewer
docker-compose exec web slidefactory user set-scopes user@company.com \
  --scopes '["workflows:read", "presentations:read"]'

# Or delete user entirely
docker-compose exec web slidefactory user delete user@company.com

Reset Password

# User forgot password
docker-compose exec web slidefactory user change-password user@company.com

# System will prompt for new password
# User can now login with new password

Troubleshooting

User Can't Login

Symptom: "Invalid credentials" error

Solutions: 

# 1. Check user exists
docker-compose exec web slidefactory user list

# 2. Verify email is correct (case-sensitive)
docker-compose exec web slidefactory user show user@company.com

# 3. Reset password
docker-compose exec web slidefactory user change-password user@company.com

# 4. Check application logs
docker-compose logs web | grep -i "login\|auth"

User Can't Access Resource

Symptom: "Permission denied" or 403 Forbidden

Solutions: 

# 1. Check user's scopes
docker-compose exec web slidefactory user show user@company.com

# 2. Add missing scope
docker-compose exec web slidefactory user add-scopes user@company.com \
  --scopes '["workflows:execute"]'

# 3. Verify scope format is correct
# Scope must match exactly: "workflows:execute" not "workflow:execute"

Azure AD Login Fails

Symptom: Redirect fails or "Authentication error"

Solutions: 

# 1. Verify environment variables
docker-compose exec web env | grep AZURE

# 2. Check Azure AD configuration
# - Redirect URI must match APP_URL
# - Client secret must be valid
# - Tenant ID must be correct

# 3. Check application logs
docker-compose logs web | grep -i "azure\|entra"

# 4. Test Azure AD connectivity
curl "https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0/.well-known/openid-configuration"

CLI Command Not Found

Symptom: slidefactory: command not found

Solutions: 

# For Docker (recommended)
docker-compose exec web slidefactory user list

# For local development
# 1. Ensure virtual environment is activated
source venv/bin/activate

# 2. Install package in development mode
pip install -e .

# 3. Run command
slidefactory user list

Database Connection Error

Symptom: "Could not connect to database"

Solutions: 

# 1. Check database is running
docker-compose ps postgres

# 2. Check DATABASE_URL is correct
docker-compose exec web env | grep DATABASE_URL

# 3. Restart services
docker-compose restart web

# 4. Check database logs
docker-compose logs postgres

Security Best Practices

Password Requirements

  • Minimum 12 characters
  • Mix of uppercase, lowercase, numbers, symbols
  • No common passwords (password123, admin, etc.)
  • No email in password

Scope Assignment

  • Principle of least privilege: Only grant necessary scopes
  • Regular audits: Review user scopes quarterly
  • Remove unused accounts: Delete inactive users
  • Use presets: Start with presets, customize only if needed

Azure AD Integration

  • Use groups: Manage access via Azure AD groups
  • JIT provisioning: Let users auto-create on first login
  • Regular sync: Verify group membership matches access needs
  • Monitor logs: Track Azure AD authentication attempts

API Integration

For programmatic user management, see the slidefactory-core API documentation.

Quick Reference

For a quick command reference, see the examples above. All commands support --help flag for detailed options.

Production Security

In production: - Use Azure AD for user authentication - Enforce strong passwords for local users - Regularly audit user scopes - Monitor authentication logs - Rotate service account passwords