Skip to main content

​
Assigning Roles to Users

This guide explains how to determine and pass the correct roles for each user in your application.

​
The Role Assignment Flow

You control role assignment entirely - DocBit AI just receives the roles you pass.

​
Mapping Strategies

​
1. Direct Mapping from User Groups

If your system has user groups, map them directly: 
function getRolesFromGroups(userGroups) {
  const roleMap = {
    'Human Resources': 'hr',
    'Finance Team': 'finance',
    'Engineering': 'engineering',
    'All Employees': 'all-staff'
  };
  
  return userGroups
    .map(group => roleMap[group])
    .filter(Boolean);
}

// User in "Human Resources" and "All Employees" groups
const roles = getRolesFromGroups(['Human Resources', 'All Employees']);
// Result: ['hr', 'all-staff']

​
2. Role Hierarchy

Build cumulative roles based on hierarchy: 
function getRolesFromLevel(level) {
  const hierarchy = {
    'employee': ['employee'],
    'manager': ['employee', 'manager'],
    'director': ['employee', 'manager', 'director'],
    'executive': ['employee', 'manager', 'director', 'executive']
  };
  
  return hierarchy[level] || ['employee'];
}

// A director gets all lower-level roles too
const roles = getRolesFromLevel('director');
// Result: ['employee', 'manager', 'director']

​
3. Attribute-Based Assignment

Derive roles from user attributes: 
function getRolesFromUser(user) {
  const roles = ['all-staff']; // Base role for everyone
  
  // Department
  if (user.department) {
    roles.push(user.department.toLowerCase());
  }
  
  // Management level
  if (user.isManager) roles.push('manager');
  if (user.isDirector) roles.push('director');
  if (user.isExecutive) roles.push('executive');
  
  // Project memberships
  if (user.projects) {
    user.projects.forEach(p => roles.push(`project-${p}`));
  }
  
  // Special access
  if (user.hasConfidentialAccess) roles.push('confidential');
  
  return [...new Set(roles)]; // Deduplicate
}

​
4. Claims from Identity Provider

Extract roles from JWT claims or IdP attributes: 
// From JWT token claims
function getRolesFromToken(decodedToken) {
  // Azure AD groups claim
  const groups = decodedToken.groups || [];
  
  // Custom roles claim
  const customRoles = decodedToken['extension_roles'] || [];
  
  // Combine and normalize
  return [...groups, ...customRoles]
    .map(r => r.toLowerCase().replace(/\s+/g, '-'));
}

​
Integration Examples

​
Express.js Middleware

const express = require('express');

function DocBit AIMiddleware(req, res, next) {
  const user = req.user; // From your auth middleware
  
  // Map your user to DocBit AI context
  req.DocBit AI = {
    orgId: user.tenantId,
    userId: user.id,
    roles: getRolesFromUser(user)
  };
  
  next();
}

app.use(DocBit AIMiddleware);

app.post('/api/ask', async (req, res) => {
  const response = await DocBit AIClient.chat({
    headers: {
      'X-External-Org-Id': req.DocBit AI.orgId,
      'X-External-User-Id': req.DocBit AI.userId,
      'X-External-Roles': JSON.stringify(req.DocBit AI.roles)
    },
    body: { message: req.body.question }
  });
  
  res.json(response);
});

​
Python/FastAPI

from fastapi import Depends, Request

def get_docbit_context(request: Request):
    user = request.state.user  # From your auth
    
    roles = ['all-staff']
    if user.department:
        roles.append(user.department.lower())
    if user.is_manager:
        roles.append('manager')
    
    return {
        'org_id': user.tenant_id,
        'user_id': str(user.id),
        'roles': roles
    }

@app.post('/ask')
async def ask(question: str, ctx = Depends(get_docbit_context)):
    return await docbit_client.chat(
        org_id=ctx['org_id'],
        user_id=ctx['user_id'],
        roles=ctx['roles'],
        message=question
    )

​
Dynamic Role Updates

Roles are evaluated per-request, so changes take effect immediately: 
// User gets promoted to manager
await updateUser(userId, { isManager: true });

// Next request automatically includes 'manager' role
// No need to update anything in DocBit AI

​
Security Considerations

Always determine roles server-side. Never trust roles passed from the client.

​
Do This

// Server-side: derive roles from authenticated user
app.post('/ask', authMiddleware, (req, res) => {
  const roles = getRolesFromUser(req.user); // Trusted source
  // ...
});

​
Don’t Do This

// Never accept roles from the client!
app.post('/ask', (req, res) => {
  const roles = req.body.roles; // DANGEROUS - user could pass any roles
  // ...
});

​
Best Practices

Give everyone at least one role (like all-staff) for company-wide documents.
Use the same role names when uploading documents and assigning to users.
Log which roles are assigned to help debug access issues.
Verify users see the right documents for their roles.

​
Next Steps