FireFly Analytics LogoFireFly Analytics
Architecture / IAM / Users

User Onboarding in FireFly

A comprehensive guide to how users are registered, authenticated, and granted access to organizations and Databricks resources in the FireFly platform.

Overview

Users in FireFly authenticate via SSO (Okta) and are associated with one or more organizations through membership records. Each user can have different roles in different organizations and may have individual Service Principal mappings for Databricks access.

This document describes how users are registered, authenticated, onboarded to organizations, and granted access to Databricks resources.

Key Concepts

  • SSO Authentication: Users authenticate via Okta - no Databricks account needed
  • Multi-Organization Membership: Users can belong to multiple organizations with different roles
  • Session-Based Org Selection: Active organization stored in session for API routing
  • SPN-Based API Access: Databricks calls use organization SPN, not user credentials

Onboarding Steps

User onboarding involves several steps, some automated and some manual:

  • Automated: User registration, session creation, member addition, SPN mapping in FireFly
  • Manual: User SPN creation in Databricks, adding user to Databricks group

User Data Model

The following entity-relationship diagram shows all tables involved in user management and their relationships.

User-Related Tables

user

Core user record created during SSO authentication

  • id: Unique user identifier
  • email: User's email (unique)
  • name: Display name from SSO
  • accountIdUserIdMapping: SCIM IDs per Databricks account

member

User-to-organization membership with role

  • userId: Reference to user
  • organizationId: Reference to organization
  • role: "owner", "admin", or "member"

session

User session with active organization context

  • userId: Reference to user
  • activeOrganizationId: Currently selected org
  • token: Session token
  • expiresAt: Session expiration

userSpns

Individual user Service Principal mappings (optional)

  • email: User email (unique)
  • clientId: SPN OAuth client ID
  • clientSecret: Encrypted SPN secret
  • principalId: Databricks principal ID

account

OAuth account from better-auth for SSO tokens

  • userId: Reference to user
  • providerId: OAuth provider (e.g., "oidc")
  • accessToken: SSO access token
  • refreshToken: SSO refresh token

Complete User Onboarding Flow

The following diagram shows the complete flow for onboarding a new user to the platform and granting them access to an organization's data. Red boxes indicate manual steps.

Onboarding Phases

1. User Registration

User visits FireFly and authenticates via Okta SSO. If this is their first login, a user record is created in PostgreSQL.

2. Organization Access

User selects an organization they're a member of. The session is updated with the activeOrganizationId for API routing.

3. SPN Mapping (MANUAL)

Admin creates a user SPN in Databricks and maps it to the user in FireFly. This enables per-user tracking and permissions.

4. Databricks Group Access (MANUAL)

Admin adds the user/SPN to the organization's Databricks group. This grants access to Unity Catalog data.

5. Data Access

User can now access notebooks, SQL editor, and catalog browser. All Databricks API calls use the organization's SPN.

User Registration Sequence

This sequence diagram shows the detailed flow for user registration and session creation via Okta SSO.

First-Time vs Returning Users

  • First-time users: User record is created in PostgreSQL with email and name from SSO
  • Returning users: OAuth tokens are updated in the account table
  • Session creation: A new session is created for both cases with a cookie

Adding User to Organization

This sequence diagram shows the complete flow for adding an existing user to an organization and granting them Databricks access.

Detailed Steps

Step 5.1: Add User as Member in FireFly

Admin searches for the user and adds them with a role (owner/admin/member).

POST /api/admin/add-member
{
  "organizationId": "org_123...",
  "userId": "user_456...",
  "role": "member"
}

Step 5.2: Create User SPN in Databricks (MANUAL)

Admin must manually create a Service Principal for the user in the Databricks Account Console and grant it workspace access.

Step 5.3: Map User to SPN in FireFly

Admin enters the SPN credentials in FireFly to map the user.

POST /api/admin/databricks/accounts/map-scim-user
{
  "email": "user@example.com",
  "clientId": "abc123...",
  "clientSecret": "secret..."
}

Step 5.4: Add User to Databricks Group (MANUAL)

Admin must manually add the user/SPN to the organization's group in Databricks for Unity Catalog access.

SSO-SPN Authentication Flow

This diagram shows how users authenticate via SSO and how their requests are authorized using organization Service Principals.

Authentication Benefits

  • No Databricks Account Required: Users authenticate via Okta only
  • Centralized Access Control: FireFly manages organization membership
  • Secure API Access: SPN tokens used for all Databricks calls
  • Automatic Token Refresh: SPN tokens are cached and refreshed

User Access Control

This diagram shows how user roles and permissions are resolved in FireFly and Databricks.

User Roles

Owner

  • Full organization control
  • Manage all members
  • Configure BYOD settings
  • Delete organization

Admin

  • Manage members
  • Configure settings
  • Access all features
  • Cannot manage owners

Member

  • Access notebooks
  • Use SQL editor
  • Browse catalog
  • Import data

Databricks Permissions

Data access in Databricks is controlled by Unity Catalog groups and catalog permissions, separate from FireFly roles.

Unity Catalog Group

Organization members are added to a Databricks group:

  • SELECT on catalog tables
  • MODIFY on catalog tables
  • CREATE on schemas
  • Access to specific volumes

User SPN

Individual user SPNs enable:

  • Per-user audit trails
  • Individual permission grants
  • Workspace-level access
  • Cluster/warehouse access

API Reference

These are the key API endpoints for user management.

Authentication APIs

GET /api/auth/session - Get current session
POST /api/oauth/set-org - Set active organization
POST /api/oauth/switch-org - Switch organization
GET /api/sso-spn/user-data - Get user data for org

User Management APIs

GET /api/admin/search-users - Search users by email
POST /api/admin/add-member - Add user to organization
POST /api/admin/remove-member - Remove user from organization
POST /api/admin/update-member-role - Change member role
POST /api/admin/databricks/accounts/map-scim-user - Map SCIM ID
GET /api/admin/list-users-with-scim - List users with SCIM mapping

Frontend Locations

/sso-spn/login - User login page
/sso-spn/select-org - Organization selector
/admin/users - User management (admin)
/admin/organizations/[slug] - Manage org members

Key Takeaways

Understanding the user lifecycle is essential for proper platform administration. Here are the key points to remember:

1

Users Authenticate via SSO Only

No Databricks account is needed - users log in through Okta

2

Multi-Organization Membership

Users can belong to multiple orgs with different roles in each

3

Session Tracks Active Org

The activeOrganizationId in session determines API routing

4

SPN Mapping Enables Tracking

Per-user SPNs enable audit trails and individual permissions

5

Databricks Group Access is Manual

Users must be manually added to the Databricks group for data access

Related Documentation

Learn more about how organizations work and how the platform handles authentication and API routing.

OrganizationsAuthentication