Access Control and Authorization#

Access Control and Authorization in Dosu encompasses a comprehensive security framework that manages user permissions, authenticates third-party integrations, and controls data access across the platform. The system implements organization-level role-based access control (RBAC) complemented by integration-specific authentication mechanisms for GitHub, Confluence, and Slack. This cross-platform security model operates independently from platform-specific permission systems, coordinating access control across multiple third-party services while maintaining a unified organizational hierarchy.

The architecture balances security with usability through a multi-layered approach. At the organizational level, Dosu implements RBAC with three distinct roles (Owner, Admin, and Member) that control administrative capabilities and data source management. For third-party integrations, the system employs OAuth 2.0 flows for Slack and Confluence, GitHub App installations with JWT-based authentication, and platform-specific permission models that respect the principle of least privilege. Each integration maintains its own authentication lifecycle while sharing organizational access control policies, creating a consistent security posture across all connected services.

A distinguishing characteristic of Dosu's access control model is its explicit configuration requirement: repositories and channels are not automatically added as data sources after integration—users must explicitly configure them, providing intentional control over what gets indexed and synchronized. This design principle, combined with integration-specific access restrictions and organizational role enforcement, creates a defense-in-depth security model that protects sensitive data while enabling seamless collaboration across platforms.

Plan-Based Feature Availability#

Certain enterprise-grade security and authorization features are available only on specific pricing tiers:

All plans include the standard three-role RBAC system (Owner, Admin, Member). For organizations requiring enhanced security controls, compliance features, or custom authentication workflows, the Enterprise plan provides these advanced capabilities.

Organization-Level RBAC System#

Core Roles and Permissions#

Dosu implements role-based access control (RBAC) at the organization level with three core roles:

1. Owner: Full control over the organization, including deletion authority. Each organization has exactly one owner.
2. Admin: Can invite and manage members, manage deployments and data sources, and view billing information.
3. Member: Can view deployments and data sources and interact with Dosu features. Cannot manage team members or billing.

User Onboarding Mechanisms#

Users become organization members through two pathways:

Manual Invitation: Admins invite users by email and assign roles at the time of invitation.

Domain-Based Autojoin (Enterprise only): Organizations with an Enterprise plan can enable domain-based autojoin to automatically add users with matching email domains during authentication. Each organization can have one enterprise account configuration that manages autojoin settings through the enterprise_account table.

Enterprise Account Configuration#

The enterprise account table structure includes:

• org_id: Links the enterprise configuration to a specific organization (enforced by the one_enterprise_account_per_org constraint)
• autojoin_enabled: Controls whether automatic user addition is active
• active_domains: Array of email domains (e.g., company.com) that qualify for autojoin
• sso_provider_id and sso_enabled: SSO configuration (independent from autojoin functionality, Enterprise only)

The table includes two primary constraints:

• one_enterprise_account_per_org: Ensures each organization has at most one enterprise account configuration
• sso_enabled_requires_provider: Enforces that SSO can only be enabled when a provider is configured

Row-level security (RLS) policies control access to enterprise account configurations. Organization members can read their organization's enterprise account settings, but all mutations are restricted to service-role access (backoffice operations).

Organizations with an Enterprise plan can enable domain-based autojoin with or without SSO configured—these are independent features within the enterprise account.

Autojoin Behavior and Role Assignment#

Autojoin applies only to newly created users—specifically, users whose accounts were created within the last 90 seconds. Existing users are not affected by autojoin settings.

The autojoin process is triggered at three specific touchpoints:

1. OAuth Callback: After successful OAuth authentication (SSO or social login), if the user is newly created, the system automatically attempts autojoin during the callback
2. Password Login Flow: After successful password-based authentication, if the user is newly created, the client makes a POST request to /auth/enterprise-autojoin to attempt autojoin
3. Explicit Endpoint: The /auth/enterprise-autojoin POST endpoint can be called directly to trigger an autojoin attempt for the authenticated user

When autojoin is triggered for a user whose email domain matches the enterprise account's active_domains:

1. Domain Matching: The system extracts the email domain and checks it against the active_domains array in the enterprise account table
2. Automatic Organization Addition: The user is automatically added to the organization
3. Intelligent Role Assignment:
   • If the user has a pending invitation to the organization, they receive the role specified in that invitation (e.g., ADMIN)
   • If no pending invitation exists, the user is assigned the default MEMBER role
   • Pending invitations are consumed (deleted) after the autojoin process
4. Onboarding Completion: The user's onboarding status is automatically marked as complete
5. Organization Context: The system sets URL parameters (switchToOrg) and cookies (MY_SELECTED_ORG) to automatically switch the user to their newly joined organization

This approach allows organizations to pre-assign specific roles to certain employees (via pending invitations) while maintaining general autojoin for all domain users. Admins retain full control to modify roles or remove members as needed after autojoin.

Implementation Reference#

The autojoin logic is implemented in server/utils/enterprise-autojoin.ts through the tryAutoJoinEnterprise utility function. This function:

• Validates the user's email domain against enterprise accounts with autojoin enabled
• Checks for pending invitations to honor pre-assigned roles
• Adds the user to the organization with the appropriate role
• Marks onboarding as complete
• Returns the organization ID on successful autojoin, or null if no matching enterprise account exists

The OAuth callback (app/[locale]/auth/callback/route.ts) automatically invokes this utility for newly created users. The password login flow (components/login/PasswordLogin.tsx) makes a POST request to the /auth/enterprise-autojoin endpoint, which in turn calls the same utility function.

Account Requirements#

Users need a Dosu account to manage their organization's knowledge base (reviewing documentation, approving drafts, configuring deployments), but account creation is not required to interact with Dosu on Slack or GitHub—those integrations work for anyone in the connected workspace or repository.

Data Source Access Control#

Data sources are connected at the organization level and shared across all organization members. Once a data source is created, all members of the Dosu organization can access its contents. However, access restrictions can be configured at the repository or workspace level depending on the integration type.

GitHub Integration Access Control#

Repository Permission Requirements#

To create a GitHub data source or deployment, users must have Triage permission or higher on the repository, or be the user who installed the Dosu GitHub App. Read-only collaborators cannot create data sources or deployments for a repository.

For private repositories, users must be the GitHub App installer or have Triage permission or higher to create data sources or deployments. Once a private repository is connected, all members of your Dosu organization can access its indexed content.

GitHub App Permission Model#

The GitHub App permission model distinguishes between read-only access for code inspection and repository metadata, and read-write access for interactive features like responding to issues, applying labels, and managing pull requests.

Read access includes repository contents, metadata, administration, actions, checks, and commit statuses; read-write access covers issues and issue comments, pull requests and pull request reviews, and discussions and discussion comments.

Slack Integration Access Control#

Channel Access Model#

Dosu can only access channels where it has been explicitly invited. The invitation model differs by channel type:

• Public channels: The application can see all public channels after installation but only actively monitors channels where you've created a deployment
• Private channels: You must explicitly invite the application using /invite @[AppName] before it can be selected for a deployment

Organization-Level Data Access#

Once a Slack workspace is connected to the Dosu organization, all organization members can access data from that workspace's connected channels. Access is not filtered by individual Slack channel membership—if a channel is connected as a data source, all Dosu organization members can query its contents.

OAuth Permissions#

The Slack integration requests three categories of permissions during OAuth:

Channel Access:

• Read public and private channel info
• Read message history
• Join channels

Messaging:

• Send messages
• Add reactions

User Info:

• Read user profiles and email addresses (to identify who's asking questions)

Confluence Integration Access Control#

Authentication Methods#

Dosu supports three authentication methods for establishing Confluence workspace connections:

1. OAuth (Recommended): Sign in with your Atlassian account and grant Dosu read access to your Confluence content
2. Email + API Token: Use your Atlassian email and an API token when OAuth is not available
3. Scoped API Token: Use a scoped API token with specific permissions when your organization has restricted API token permissions

Space and Page Access#

The OAuth connection determines which spaces and pages Dosu can fetch, based on the permissions of the user who authorizes the connection.

Once a Confluence workspace is connected to your Dosu organization, all organization members can access data from that workspace's connected spaces and pages. Dosu recommends creating a dedicated service account in Confluence with access only to the spaces you want Dosu to index, then authorizing the Dosu connection with that account.

Dosu indexes global, collaboration, and knowledge base spaces, while personal spaces and system spaces are excluded. Pages (current/published versions only) are synced, while attachments, archived pages, and draft pages are not synced.

Multi-Layered Authentication Mechanisms#

GitHub Authentication Architecture#

Token-Based Authentication#

The GitHub integration implements multi-layered authentication with GitHub App installation tokens as the primary method and personal access tokens as fallback. JWT-based tokens generate installation-specific access tokens issued with a 10-minute expiration and a 30-second backdated timestamp to avoid clock skew issues. Installation access tokens are valid for one hour and automatically refreshed as needed.

Installation Lifecycle Management#

The GitHub App installation process allows administrators to choose to grant Dosu access to all repositories in their account or organization, or limit access to specific repositories.

After installation, Dosu automatically syncs three types of repository data: the list of accessible repositories, collaborators for each repository, and labels for each repository. Repositories are not automatically added as data sources or deployments after installation—users must explicitly create these configurations through the Dosu dashboard.

Suspension Detection and Graceful Degradation#

The system implements comprehensive suspension handling mechanisms:

• Detection: HTTP 403 errors are checked for the message "This installation has been suspended"
• Automatic Database Marking: When 403 indicates suspension, the repository is automatically marked as suspended in the database
• Webhook Lifecycle Management: The system responds to suspend and unsuspend webhook actions, marking all repositories as suspended or reactivated accordingly
• Proactive Skipping: Suspended repositories are automatically skipped during syncing and webhook event handling to prevent repeated failures

When an installation is suspended, all associated deployments are automatically disabled.

Retry Logic and Error Handling#

The authentication system uses selective retry logic with exponential backoff: auth operations retry up to 5 times but specifically exclude 403, 404, and 410 errors, as well as installation suspension and token-not-found exceptions.

Slack Authentication Architecture#

OAuth Flow and Workspace Connection#

Slack workspace connections are established through a guided OAuth flow. The installation process:

1. Navigate to Settings > Deployments and select Slack
2. Click Add to Slack workspace
3. You're redirected to Slack's authorization interface to select the workspace
4. After authorization, you're redirected back to complete setup

After installation, the application syncs the list of channels in your workspace and waits for you to create deployments for specific channels.

Webhook Security#

Webhooks are validated using HMAC SHA-256 signature verification with a configured webhook secret, ensuring that only legitimate requests from Slack are processed.

Confluence Authentication Architecture#

OAuth Authorization Flow#

OAuth is the recommended authentication method where you sign in with your Atlassian account. During connection, you'll be redirected to Atlassian to grant Dosu read access to your Confluence content, and then redirected back to Dosu after authorization.

After authorizing, Dosu syncs your available Confluence spaces and you can select which spaces to index as data sources.

Token Expiration and Reauthorization#

If your Atlassian authorization expires, Dosu will prompt you to reconnect. Click "Reconnect" to reauthorize through Settings > Data Sources.

Synchronization Frequency#

Dosu checks your Confluence content for changes every 5 minutes. New and updated pages are automatically indexed; deleted pages are removed from the index.

Authorization for Feature-Based Access#

GitHub Deployment Configuration#

Deployments enable Dosu to respond interactively within specific GitHub repositories through feature-based configurations. Dosu offers two deployment modes: Standard Setup (complete control over configuration for production environments) and Preview Mode (creates deployment with all public-facing features disabled, generating response drafts only in the dashboard).

Agent Reply Modes#

Agent reply behavior offers three modes:

• Mention: Dosu only responds when tagged with @dosu
• Auto Draft: Dosu generates response drafts for review in the Review page
• Auto Reply: Dosu posts responses automatically

Auto-Labeling Authorization#

Auto-labeling analyzes label taxonomy, historical patterns, and issue content with configuration support for include/exclude lists to control which labels Dosu considers, custom instructions to guide decisions, and an ignore list preventing auto-labeling when certain labels are already present.

Pull Request Write Operations#

Dosu may create pull requests in two scenarios: when documentation changes that originated from synced GitHub files are accepted (creating a PR to sync changes back to the source file), and when a knowledge store is configured (allowing Dosu's agent to create PRs to update documentation pages). Dosu does not push code changes or merge pull requests for regular code or features—the only other writes Dosu performs in GitHub are labels, reactions, and comments.

Deployment Status Management#

Deployment status management enables administrators to pause deployments temporarily (suspending all automated actions), resume paused deployments, or delete deployments entirely.

Public Spaces and Open Access#

Spaces can be set to public visibility, which allows anyone (including users without a Dosu account) to view documentation and ask questions. Data sources connected to public spaces become queryable by anyone. Public spaces are intended for open-source projects and public knowledge bases.

Security Principles and Best Practices#

Principle of Least Privilege#

The permission model supports a principle of least privilege approach to integration security by allowing organizations to grant Dosu only the minimum necessary permissions for their intended use cases. This is implemented through:

• Selective repository access: GitHub App installation allows limiting access to specific repositories
• Explicit channel invitation: Slack integration only accesses channels where explicitly invited
• Service account pattern: Confluence recommends dedicated service accounts with limited space access

Graceful Degradation#

The system implements multiple layers of error handling and fallback strategies to maintain service continuity even when specific permissions are unavailable or installations are suspended.

Explicit Configuration Requirement#

Repositories and channels are not automatically added as data sources after integration—users must explicitly configure them through the Dosu dashboard, providing intentional control over what gets indexed and synchronized.

Relevant Code Files#

Related Topics#

• GitHub Integration - Comprehensive coverage of GitHub App installation, data sources, and deployments
• Slack Integration - Workspace connections, channel monitoring, and bot deployment
• Confluence Integration - Authentication, space indexing, and bidirectional sync
• Data Sources - Cross-platform data source management and indexing
• Deployments - Interactive bot deployment and configuration across platforms