Skip to main content

How to Create a New Tenant

This guide walks you through creating a new tenant using the Zeta Alpha Platform UI. The tenant creation process sets up a complete, ready-to-use environment including authentication, storage, a default index, and essential content sources.

Prerequisites​

Before creating a tenant, ensure you have:

Required for All Tenants​

  1. Admin access to the Zeta Alpha Platform UI
  2. LLM API keys: API credentials for your chosen language model provider (OpenAI, Azure OpenAI, etc.)
    • Primary model API key (for reasoning and chat)
    • Small model API key (for extraction and summarization)
  3. SerpApi API key: API credentials for federated search functionality
  4. Infrastructure information:
    • S3 bucket names for ingestion and processing storage
    • Kubernetes namespace configurations (OpenSearch, embeddings service, chat service, pipeline service)
    • Embeddings service endpoints

Additional Requirements by Authentication Method​

Choose one of the following based on your preferred authentication method:

For Password Authentication​

  • Admin user details: Email address, first name, and last name for the initial administrator account
  • The admin user will receive an email to activate their account

For SSO Authentication​

  • OIDC Discovery Endpoint: Your identity provider's OpenID Connect discovery URL
  • OAuth2 Client ID and Client Secret: Application credentials from your identity provider
  • Attribute mappings: Field names for email and group memberships in your IdP
  • (Optional) Group IDs for role assignments: IdP group identifiers for automatic role assignment (Member, Manager, Ingestion Manager)

Creating a New Tenant​

Navigate to the Tenants tab in the Zeta Alpha Platform UI and click the Create Tenant button.

Create Tenant Form

The tenant creation process will automatically:

  1. Create the tenant with default configurations (customizable after creation)
  2. Set up an admin user (password authentication only) who will receive an email to activate their account
  3. Configure SSO (SSO authentication only) Based on your identity provider settings
  4. Create a default index with standard field configurations for document management
  5. Initialize base content sources:
    • user-documents-ingestion: For ingesting user-uploaded documents
    • notes-ingestion: For ingesting user notes and annotations
    • tags-enhancement-ingestion: For enhancing documents with user-created tags
    • user-documents-metadata-enhancement: For AI-powered metadata extraction from uploaded documents
  6. Configure chat bots and AI agents for various tasks (document chat, deep research, Q&A, summarization, etc.)
  7. Set up federated search with "All the Web" and optionally "All of Science"
  8. Create a sample document demonstrating the ingestion pipeline

Base Information​

Fill in the following required fields:

  • Tenant Name: A unique identifier for the tenant (e.g., "acme-research"). This will be automatically converted to kebab-case format for internal use.
  • First Name of admin user: Administrator's first name (only required for password authentication)
  • Last Name of admin user: Administrator's last name (only required for password authentication)
  • Email of admin user: Administrator's email address (only required for password authentication; used for account activation)
  • (Optional) Affiliation of admin user: Organization or department affiliation (only for password authentication)

Federated Search Configuration​

  • SerpApi API Key: API key for enabling federated search across external sources
  • Include All of Science: Toggle switch to enable/disable All of Science federated search. When enabled, users can search across academic papers in addition to the internal index and general web search.

LLM Configuration​

Configure the language models that power search, chat, and data processing:

  • LLM Deployment Name: Model name for primary tasks (reasoning, chat). Example: "gpt-4", "gpt-4o"
  • LLM API Key: API key for the primary model
  • LLM Small Deployment Name: Model name for lightweight tasks (extraction, summarization). Example: "gpt-4o-mini"
  • LLM Small API Key: API key for the small model (can be the same as the primary key)

Azure OpenAI Configuration (Optional)​

If you're using Azure OpenAI instead of standard OpenAI, provide these additional fields:

  • OpenAI API Type: Set to azure for Azure OpenAI services
  • OpenAI API Base URL: Your Azure OpenAI resource endpoint (format: https://<resource-name>.openai.azure.com)
  • OpenAI API Version: API version for Azure OpenAI (e.g., 2024-02-15-preview)

Leave these fields blank if you're using standard OpenAI services.

Infrastructure Configuration​

Specify the infrastructure resources for data storage and processing:

  • Ingestion Storage Bucket: S3 bucket name for storing ingested documents
  • Processing Storage Bucket: S3 bucket name for processing artifacts and temporary data
    • Ensure CORS rules allow tenant access to these buckets
  • Embeddings Service: Service name for generating search query embeddings
  • Embeddings Service Pipeline: Service name for generating document embeddings during ingestion (can be the same as Embeddings Service)
  • OpenSearch Namespace: Kubernetes namespace where your OpenSearch cluster is deployed
  • Embedding Service Namespace: Kubernetes namespace for the embeddings service
  • Chat Namespace: Kubernetes namespace for the chat service

Note: By default, storage is configured for AWS S3. For Azure Blob Storage, see Changing Storage to Azure Blob Storage after tenant creation.

Authentication Method Selection​

Choose how users will authenticate to your tenant:

Option 1: Password Authentication (Default)​

Users create accounts with email and password. This is the simplest option and works immediately without additional identity provider setup.

When selecting password authentication, configure the following:

  • The system will create an admin user who will receive an email to activate their account
  • Admin user details (first name, last name, email, and optional affiliation) are required

Option 2: SSO Authentication (Single Sign-On)​

Users authenticate through your organization's existing identity provider (Microsoft Azure AD, Okta, Google Workspace, etc.). This provides better security and a seamless experience for enterprise users.

When selecting SSO, you must configure the following settings:

Required SSO Fields​
  • OIDC Discovery Endpoint: Your identity provider's OpenID Connect discovery URL (usually ends with /.well-known/openid-configuration)
    • Example for Azure AD: https://login.microsoftonline.com/<tenant-id>/v2.0/.well-known/openid-configuration
  • Client ID: Application ID from your identity provider for this Zeta Alpha tenant
  • Client Secret: Secret key from your identity provider (store securely)
  • Email Attribute Mapping: Field name in your IdP containing user email addresses (defaults to "email")
  • Microsoft Groups Attribute Mapping: Field name in your IdP containing user group memberships (defaults to "groups")
Optional Integration Mappings​

Map user attributes to enable seamless integration with third-party services (all default to "email" if left blank):

  • Slack User Attribute Mapping: Field for linking Slack accounts
  • Google Drive User Attribute Mapping: Field for linking Google Drive access
  • SharePoint User Attribute Mapping: Field for linking SharePoint access
Optional Group Role Assignments​

Map identity provider groups to tenant roles for automatic permission assignment:

  • Member Group ID: IdP group granting Member access (basic read/search permissions)
  • Manager Group ID: IdP group granting Manager access (includes Member permissions plus user management)
  • Ingestion Manager Group ID: IdP group granting Ingestion Manager access (document upload and management)
Important Notes for SSO Users
  • Identity Provider Setup: Your IT administrator must configure the OAuth2/OIDC application in your identity provider with the appropriate redirect URI before users can authenticate. The redirect URI can be found in the tenant creation form.
  • Group Mapping: Without explicit group role assignments, all SSO users receive Member-level access by default.

Accessing the New Tenant​

For Password Authentication​

After tenant creation, the admin user receives an email with a password setup link. Follow these steps:

  1. Check your email for the activation message
  2. Click the link to set your password
  3. Navigate to your tenant's Zeta Alpha Navigator URL
  4. Sign in with your email and new password

If email service is not configured in your environment, contact your Zeta Alpha representative to obtain the password setup link manually.

For SSO Authentication​

If you configured SSO during tenant creation:

  1. Navigate to your tenant's Zeta Alpha Navigator URL
  2. You'll be redirected to your organization's login page (e.g., Microsoft, Okta, Google Workspace, etc.)
  3. Authenticate using your existing organizational credentials
  4. You'll be redirected back to the Navigator with appropriate role-based permissions

No password setup emails are sent for SSO tenants.

Customize Your Tenant​

After creation, tenants have default configurations that can be customized to meet your specific needs.

Editing Tenant Configuration​

  1. Navigate to the Tenants tab in the Platform UI
  2. Click on your tenant name to view the configuration (displayed as JSON)
  3. Click the Edit button to modify the configuration
  4. Make your changes to the JSON object
  5. Click Submit to save your changes

For creating indexes with custom fields, see the Create a Custom Index guide.

Changing Authentication to Use SSO​

To manually enable SSO for an existing tenant:

  1. Navigate to the Tenants tab
  2. Click on your tenant name
  3. Click Edit
  4. Update the authentication_settings configuration:
{
  "authentication_settings": {
    "protocol": "oidc",
    "protocol_settings": {
      "oidc": {
        "client_id": "<tenant-name>-research-navigator",
        "issuer": "https://<your-login-url>/realms/<realm>/",
        "redirect_uri": "https://<tenant-name>-search.<your-domain>"
      }
    },
    "allow_anonymous_users": false
  }
}

Replace the placeholder values:

  • tenant-name: The value under the key "tenant"
  • your-login-url: The Zeta Alpha login URL (ask your Zeta Alpha representative if unsure)
  • realm: Your identity provider realm (ask your Zeta Alpha representative if unsure)
  • your-domain: The domain where your tenant is hosted (e.g., company.com)

OIDC Example

Changing Storage to Azure Blob Storage​

By default, storage is configured for AWS S3. To use Azure Blob Storage:

  1. Navigate to the Tenants tab and edit your tenant configuration
  2. Change storage_settings.ingesting.backend to azure
  3. Change storage_settings.processing.backend to azure
  4. Replace the S3 configuration with Azure Blob Storage settings:
{
  "storage_settings": {
    "ingesting": {
      "backend": "azure",
      "azure": {
        "azure_account_url": "https://your-account.blob.core.windows.net",
        "azure_container_name": "your-container",
        "azure_blob_prefix": "ingestion"
      }
    },
    "processing": {
      "backend": "azure",
      "azure": {
        "azure_account_url": "https://your-account.blob.core.windows.net",
        "azure_container_name": "your-container",
        "azure_blob_prefix": "processing"
      }
    }
  }
}

Azure fields:

  • azure_account_url: (Required) Azure Blob Storage account URL
  • azure_container_name: (Required) Container name in Azure Blob Storage
  • azure_blob_prefix: (Optional) Prefix for organizing blobs within the container

Azure Blob Example

Next Steps​