Using the Admin Portal

Overview

The Frontier Admin Portal provides a web-based interface for managing your Frontier deployment. It’s built with React and offers a visual way to perform administrative tasks without using the API or CLI.

The Admin Portal is included in the Frontier repository under web/apps/admin. It’s a separate application that connects to your Frontier server via API.

Features

The Admin Portal provides tools for:

Organization Management: Create, view, and manage organizations
User Administration: View users, manage roles, and assign permissions
Authentication Configuration: Set up OIDC providers and authentication methods
Platform Preferences: Configure platform-wide settings
Domain Verification: Manage and verify organization domains
Audit Logs: Monitor system activity and user actions
Webhook Management: Configure and monitor webhook endpoints
Billing Overview: View billing accounts and subscriptions (if enabled)

The Admin Portal requires a running Frontier server. It cannot operate standalone.

Prerequisites

Before setting up the Admin Portal:

✅ Frontier server is running and accessible
✅ Node.js 18+ and npm installed
✅ You have a user account with admin privileges

Installation and Setup

Navigate to the admin portal directory

From the Frontier repository root:

cd web/apps/admin

Create environment configuration

Create a .env file with your Frontier server URLs:

.env

# Frontier HTTP API endpoint
FRONTIER_API_URL=http://localhost:8000

# Frontier gRPC Connect endpoint
FRONTIER_CONNECTRPC_URL=http://localhost:8002

Local Development
Production
Docker Compose

FRONTIER_API_URL=http://localhost:8000
FRONTIER_CONNECTRPC_URL=http://localhost:8002

FRONTIER_API_URL=https://api.your-domain.com
FRONTIER_CONNECTRPC_URL=https://grpc.your-domain.com

FRONTIER_API_URL=http://frontier:8000
FRONTIER_CONNECTRPC_URL=http://frontier:8002

Install dependencies

npm install

This installs all required packages including:

React 18+
Connect-Web for gRPC communication
UI component libraries

Start the development server

npm run dev

The portal will start on http://localhost:5173

The default port is 5173 (Vite’s default). You can change this in vite.config.ts if needed.

Access the portal

Open your browser to:

http://localhost:5173/console

You’ll be redirected to the login page.

Navigate to the login page

The Admin Portal login page shows available authentication methods based on your Frontier configuration.

Choose your authentication method

OIDC Provider
Magic Link
Development Mode

If you’ve configured Google, GitHub, or Azure AD:

Click Sign in with Google (or your provider)
Complete the authentication flow
You’ll be redirected back to the portal

If identity_proxy_header is configured (dev only):The portal will automatically authenticate you using the header value.

Verify your access

After logging in, you should see the Admin Portal dashboard.If you see “Access Denied” or “Insufficient Permissions”:

Ensure your user is listed in app.admin.users in Frontier config
Restart the Frontier server
Log in again

The Admin Portal is organized into several main sections:

Dashboard

The dashboard provides an overview of your Frontier deployment:

System Health: Server status and version information
User Statistics: Total users, active sessions, recent sign-ups
Organization Stats: Total organizations and projects
Recent Activity: Latest audit log entries

Organizations Tab

Manage all organizations in your system:

View Organizations

Lists all organizations with metadata
Search and filter by name, status, or creation date
See member counts and project counts
View organization state (enabled/disabled)

Create Organization

Click Create Organization
Fill in required fields:
- Name: Unique identifier (slug)
- Title: Display name
- Metadata: Additional key-value pairs
Click Create

The organization is created with the current user as owner.

Manage Organization Members

Click on an organization
Go to Members tab
You can:
- View all members and their roles
- Add new members by email
- Assign roles to members
- Remove members

Configure Projects

Select an organization
Go to Projects tab
Create, edit, or delete projects
Manage project-level permissions

Manage Groups

Select an organization
Go to Groups tab
Create groups for team organization
Add users to groups
Assign roles to groups

Users Tab

Administer user accounts:

View All Users

See all registered users
Filter by email, status, or registration date
View authentication methods used
See last login timestamps

User Details

Click on a user to see:

Profile information and metadata
Organization memberships
Assigned roles across organizations
Authentication methods linked
Recent activity

Manage User Roles

Select a user
Go to Roles section
Choose an organization context
Assign or remove roles
Changes take effect immediately

Create Service Users

Service users are for API access:

Go to Service Users tab
Click Create Service User
Provide:
- Title/description
- Associated organization (optional)
Save the generated credentials securely

Authentication Tab

Configure authentication methods:

OIDC Provider Configuration

Visual interface for configuring:

Google OIDC
GitHub OAuth
Azure AD / Microsoft Entra ID
Custom OIDC providers

Each provider requires:

Client ID
Client Secret
Issuer URL
Callback URL configuration

Email Authentication

Configure:

Magic link settings
OTP (One-Time Password) settings
Email templates
Validity periods

Domain Verification

Manage organization domains:

Navigate to organization domains
Add a domain (e.g., acme.com)
Verify ownership via DNS TXT record or file upload
Enable auto-join for verified domains
Configure default roles for auto-joined users

Preferences Tab

Set platform-wide preferences:

Example Preferences

disable_orgs_on_create: true
disable_orgs_listing: false
disable_users_listing: false
invite_with_roles: true
invite_mail_template_subject: "Join our platform"

Organization Preferences
User Preferences
Email Templates

disable_orgs_on_create: New orgs require admin approval
disable_orgs_listing: Hide org list from non-admins
invite_with_roles: Allow role assignment during invitation

Audit Logs Tab

Monitor all system activity:

View Audit Logs

See all recorded events:

User actions (create, update, delete)
Permission checks
Organization changes
Authentication events

Each log entry shows:

Timestamp
Actor (who performed the action)
Action type
Target resource
Additional metadata

Filter and Search

Filter logs by:

Date range
Actor (user)
Action type
Organization
Resource type

Use the search box for text search across all fields.

Export Logs

Export audit logs for compliance:

Apply filters as needed
Click Export
Choose format (CSV, JSON)
Download the file

Webhooks Tab

Manage webhook endpoints:

List Webhooks

View all configured webhooks:

Endpoint URL
Subscribed events
State (enabled/disabled)
Last delivery status

Create Webhook

Click Create Webhook
Configure:
- URL: Your webhook endpoint
- Description: What this webhook is for
- Events: Which events to send
- Headers: Custom headers (e.g., Authorization)
Save and receive the signing secret
Use the secret to verify webhook signatures

Test Webhook

Select a webhook
Click Test
Choose an event type
Send a test event
View the response

Monitor Deliveries

For each webhook:

View recent deliveries
See success/failure status
Inspect request/response
Retry failed deliveries

Billing Tab (Optional)

If billing is enabled:

View billing accounts
Check subscription status
Monitor usage and credits
View invoices
Manage payment methods

Common Administrative Tasks

Creating an Organization with Teams

Create the organization

Go to Organizations tab
Click Create Organization
Fill in name and details

Add members

Open the organization
Go to Members tab
Click Invite Member
Enter email addresses
Assign initial roles

Create teams (groups)

Go to Groups tab
Create groups like:
- engineering-team
- design-team
- product-team

Assign members to groups

Open each group
Add members
Assign group-level roles

Set up projects

Go to Projects tab
Create projects
Assign projects to groups

Configuring Domain-Based Auto-Join

Navigate to organization domains

Select an organization
Go to Domains tab

Add domain

Click Add Domain
Enter domain (e.g., acme.com)
Click Add

Verify the domain

Two verification methods:DNS TXT Record:

Add TXT record to your DNS:

_frontier-verification.acme.com TXT "verification-token-here"

Wait for DNS propagation
Click Verify

File Upload:

Download verification file
Upload to https://acme.com/.well-known/frontier-verification.txt
Click Verify

Enable auto-join

After verification, toggle Auto-join
Configure default roles for new members
Save settings

Now users with @acme.com email addresses automatically join the organization on first login.

Setting Up Role-Based Access Control

Define roles

Go to Roles section
Create custom roles like:
- project-manager
- developer
- viewer

Assign permissions to roles

For each role, select permissions:

project-manager:
  - app.project.create
  - app.project.update
  - app.group.create

developer:
  - app.project.get
  - app.resource.create
  - app.resource.update

viewer:
  - app.project.get
  - app.resource.get

Assign roles to users

Go to organization Members
For each member, assign appropriate roles
Or assign roles to groups

Production Deployment

Building for Production

# Build optimized production bundle
npm run build

# Preview production build locally
npm run preview

The build output goes to dist/ directory.

Deployment Options

Nginx
Docker
Static Hosting

nginx.conf

server {
    listen 80;
    server_name admin.your-domain.com;
    root /var/www/frontier-admin/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    # API proxy (optional)
    location /api/ {
        proxy_pass http://frontier-server:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Dockerfile

FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

Build and run:

docker build -t frontier-admin .
docker run -p 80:80 \
  -e FRONTIER_API_URL=https://api.your-domain.com \
  frontier-admin

Deploy to:

Vercel: Connect your repo and deploy
Netlify: Drag and drop dist/ folder
AWS S3 + CloudFront: Upload to S3 bucket
Google Cloud Storage: Upload and configure CDN

Set environment variables in your platform:

FRONTIER_API_URL=https://api.your-domain.com
FRONTIER_CONNECTRPC_URL=https://grpc.your-domain.com

Security Considerations

Production Checklist:

✅ Use HTTPS for both portal and API
✅ Configure CORS properly on Frontier server
✅ Set secure cookies (session.secure: true)
✅ Implement CSP (Content Security Policy) headers
✅ Enable rate limiting on Frontier API
✅ Use authentication (disable identity_proxy_header)
✅ Regular security updates for dependencies
✅ Monitor access logs

Troubleshooting

Cannot connect to Frontier server

Error: Network error or timeoutSolutions:

Verify Frontier server is running: curl http://localhost:8000/v1beta1/ping
Check FRONTIER_API_URL in .env matches server address

Ensure CORS is configured in Frontier config:

app:
  cors:
    allowed_origins:
      - "http://localhost:5173"

Check firewall rules allow connections

Logged in but seeing 'Access Denied'

Issue: User is authenticated but lacks admin privilegesSolution:

Add user to admin list in Frontier config:

app:
  admin:
    users:
      - "[email protected]"

Restart Frontier server
Log out and log back in to the portal

Portal UI shows outdated data

Issue: Changes made via API don’t appear in portalSolutions:

Hard refresh the page (Ctrl/Cmd + Shift + R)
Clear browser cache
Check browser console for errors
Verify API responses in Network tab

Build fails with module errors

Error: Module not found or type errorsSolutions:

Delete node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Ensure Node.js version is 18+
Check for TypeScript errors: npm run type-check

Customization

The Admin Portal can be customized:

Branding

Edit src/config/branding.ts:

export const branding = {
  name: 'Your Company Portal',
  logo: '/path/to/logo.svg',
  primaryColor: '#3B82F6',
  favicon: '/favicon.ico'
};

Adding Custom Pages

Create component in src/pages/
Add route in src/App.tsx
Add navigation item if needed

Extending with Plugins

The portal supports plugins for additional functionality. Check the plugin documentation for details.

Next Steps

Configure Webhooks

Set up webhooks from the admin portal

Monitor Audit Logs

Use audit logs for compliance and security

Platform Preferences

Deep dive into platform settings

API Reference

Learn the API behind the portal

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

​Overview

​Features

​Prerequisites

​Installation and Setup

​First-Time Login

​Portal Navigation

​Dashboard

​Organizations Tab

​Users Tab

​Authentication Tab

​Preferences Tab

​Audit Logs Tab

​Webhooks Tab

​Billing Tab (Optional)

​Common Administrative Tasks

​Creating an Organization with Teams

​Configuring Domain-Based Auto-Join

​Setting Up Role-Based Access Control

​Production Deployment

​Building for Production

​Deployment Options

​Security Considerations

​Troubleshooting

​Customization

​Branding

​Adding Custom Pages

​Extending with Plugins

​Next Steps

Configure Webhooks

Monitor Audit Logs

Platform Preferences

API Reference

Build docs developers (and LLMs) love

Overview

Features

Prerequisites

Installation and Setup

First-Time Login

Portal Navigation

Dashboard

Organizations Tab

Users Tab

Authentication Tab

Preferences Tab

Audit Logs Tab

Webhooks Tab

Billing Tab (Optional)

Common Administrative Tasks

Creating an Organization with Teams

Configuring Domain-Based Auto-Join

Setting Up Role-Based Access Control

Production Deployment

Building for Production

Deployment Options

Security Considerations

Troubleshooting

Customization

Branding

Adding Custom Pages

Extending with Plugins

Next Steps