Organizations Plugin

Overview

The Organizations plugin provides multi-tenancy and team management capabilities. It enables users to create organizations, manage members with roles, organize members into teams, and send email-based invitations.

Core Entities

• Organizations: Owner-based organizational units
• Invitations: Email-based invitations for joining organizations
• Members: Users assigned to organizations with roles
• Teams: Group members into teams within organizations
• Team Members: Users assigned to teams within organizations

Features

• Multi-tenant organization management
• Role-based member management within organizations
• Team organization and management within organizations
• Email-based member invitations with configurable expiration
• Team member management
• Full lifecycle management (create, read, update, delete operations)

Configuration

Standalone Mode:

[plugins.organizations]
enabled = true
organizations_limit = 10 # Optional limit on number of organizations (set to 0 for unlimited)
members_limit = 100 # Optional limit on number of members per organization (set to 0 for unlimited)
invitations_limit = 100 # Optional limit on number of invitations sent to a user (100 by default)
invitation_expires_in = "24h" # Expiration time for organization invitations (24h = 1 day by default)
require_email_verified_on_invitation = true # Whether to require the invited user's email to be verified before accepting or rejecting an organization invitation (false by default)

Library Mode:

import (
  "time"

  authulamodels "github.com/Authula/authula/models"
  organizationsplugin "github.com/Authula/authula/plugins/organizations"
  organizationsplugintypes "github.com/Authula/authula/plugins/organizations/types"
)

organizationsplugin.New(organizationsplugintypes.OrganizationsPluginConfig{
  Enabled:                          true,
  OrganizationsLimit:               new(10),
  MembersLimit:                     new(100),
  InvitationsLimit:                 new(100),
  InvitationExpiresIn:              7 * 24 * time.Hour,
  RequireEmailVerifiedOnInvitation: true,
  ServiceHooks: &organizationsplugintypes.OrganizationsServiceHooksConfig{
    // Optional service hooks for custom logic on organization lifecycle events
  },
  SendOrganizationInvitationEmail: func(
    params organizationsplugintypes.SendOrganizationInvitationEmailParams,
    reqCtx *authulamodels.RequestContext,
  ) error {
    // Optionally handle email sending here...
    return nil
  },
})

API Reference

Each endpoint in this plugin requires the caller to have a specific hardcoded permission assigned to their role(s).

Organizations

Invitations

Members

Teams

Team Members

Database Schema

This plugin creates the following database tables:

Table: organizations

Table: organization_invitations

Table: organization_members

Table: organization_teams

Table: organization_team_members

Migrations are automatically handled when the plugin is initialized.

Service Hooks

This plugin supports service-level hooks, providing lifecycle callbacks with access to the actor context. Hooks are only supported in Library Mode.

The following hook configurations are available via OrganizationsServiceHooksConfig:

Organizations — OrganizationServiceHooksConfig:

Members — OrganizationMemberServiceHooksConfig:

Invitations — OrganizationInvitationServiceHooksConfig:

Teams — OrganizationTeamServiceHooksConfig:

Team Members — OrganizationTeamMemberServiceHooksConfig:

Plugin Capabilities

Service hooks can be used to execute custom logic at various points in the organization, member, invitation, team, and team member lifecycle. See the Service Hooks section for a full list of available hooks.

Security Recommendations

• Ensure that the Access Control plugin is properly configured to manage permissions for organization-related actions.
• Regularly review organization members and their roles to maintain proper access control.
• Make sure to always require authentication for all organization-related API routes and enforce role-based access control for certain routes.

Client Plugin

If you're using the Authula SDK, add the plugin to the client instance as follows:

import { createClient } from "authula";
import { OrganizationsPlugin } from "authula/plugins";

export const authulaClient = createClient({
  url: "http://localhost:8080/auth",
  plugins: [new OrganizationsPlugin()],
});