login-master¶

Federated identity with Supabase OAuth and zero-trust authentication

Login-master integrates with Supabase Auth to provide OAuth login (Google, GitHub, etc.), enabling users to access F3L1X without creating new passwords. It's the gateway between the public internet and your infrastructure.

What It Does¶

Login-master is your authentication layer:

1. OAuth Integration - Google, GitHub, Microsoft identity providers
2. Session Management - JWT tokens, refresh tokens, session expiry
3. User Profiles - Store user metadata and preferences
4. Team Management - Support for multiple team members with roles
5. Access Control - Role-based and attribute-based access control (RBAC/ABAC)

Think of login-master as your bouncer—verifying identity and controlling who gets access to what.

Key Capabilities¶

Authentication Methods¶

• Google OAuth: Login with existing Google account
• GitHub OAuth: Developer-friendly authentication
• Microsoft Entra: Enterprise identity provider
• Email Link: Passwordless email authentication (backup)
• Magic Links: Time-limited secure login tokens

Session Management¶

• JWT Tokens: Secure, stateless authentication tokens
• Refresh Tokens: Extended sessions without re-login
• Session Expiry: Automatic logout after inactivity (configurable)
• Device Tracking: See which devices user is logged in on
• Logout All: Revoke all sessions with one action

User Profiles¶

• Profile Data: Name, email, avatar, preferences
• Custom Attributes: Store realm-specific user metadata
• Profile Picture: Synced from OAuth provider
• User Roles: Admin, developer, viewer, etc.

Team Management¶

• Team Creation: Users can create teams
• Invitations: Invite team members with email
• Role Assignment: Admin, editor, viewer roles per team
• Team Settings: Manage team configuration and billing

Accessing login-master¶

Login Page¶

URL: http://127.0.0.1:8043/login

The login page shows:
- Google OAuth button
- GitHub OAuth button
- Microsoft Entra button
- Email link option
- Sign up / forgot password links

Admin Dashboard¶

URL: http://127.0.0.1:8043/admin

The admin dashboard shows:
- User list and management
- Team management
- OAuth provider configuration
- Session monitoring
- Audit logs

API Endpoints¶

Common Use Cases¶

Use Case 1: First-Time User Login¶

Goal: New user creates account via Google

1. Navigate to login page
2. Click "Sign in with Google"
3. Google OAuth window opens
4. User grants permission to share email/name
5. Redirects back to F3L1X
6. User profile created automatically
7. Session established, can access dashboard

Use Case 2: Create Team for Collaboration¶

Goal: Set up team workspace for multiple users

1. After login, click "Create Team"
2. Enter team name and description
3. Add team members by email
4. Assign roles (admin, editor, viewer)
5. Team members receive invitations
6. Accept invitation to join team
7. Team workspace ready for collaboration

Use Case 3: Revoke User Access¶

Goal: Remove user from team or system

1. Go to team settings
2. Find user in members list
3. Click "Remove" next to username
4. All sessions revoked immediately
5. User redirected to login page
6. Cannot re-access without re-invitation

Use Case 4: Switch Between Teams¶

Goal: User works on multiple teams

1. Click team selector dropdown
2. Select different team
3. Seamless switch with same JWT token
4. Dashboard updates to show team's realms
5. Permissions updated based on team role

Important Notes¶

OAuth Providers Configuration¶

To use OAuth, you need to:

Google:
1. Go to Google Cloud Console
2. Create OAuth 2.0 credentials
3. Add callback URL: http://localhost:8043/api/auth/callback/google/
4. Get Client ID and Secret
5. Add to .env: GOOGLE_OAUTH_ID=... and GOOGLE_OAUTH_SECRET=...

GitHub:
1. Go to GitHub Settings > Developer Settings > OAuth Apps
2. Create new OAuth App
3. Authorization callback: http://localhost:8043/api/auth/callback/github/
4. Get Client ID and Secret
5. Add to .env: GITHUB_OAUTH_ID=... and GITHUB_OAUTH_SECRET=...

Session & Token Lifecycle¶

Default timing:
- JWT tokens valid for 1 hour
- Refresh tokens valid for 30 days
- Inactivity timeout: 24 hours
- Session cookies: Secure, HttpOnly, SameSite

Token refresh flow:
1. Token expires after 1 hour
2. Client automatically requests new token using refresh token
3. New JWT issued without user re-authentication
4. Refresh token refreshed (extends 30-day window)
5. Seamless background refresh

Security Best Practices¶

For end users:
- Never share your token
- Log out on shared devices
- Use strong passwords on OAuth providers
- Check "Device" page to revoke old sessions

For operators:
- Rotate OAuth secrets regularly (every 90 days)
- Monitor audit logs for suspicious activity
- Require HTTPS in production (enforced)
- Enable 2FA on admin accounts

RBAC (Role-Based Access Control)¶

Roles include:

Troubleshooting¶

"Invalid OAuth credentials" error¶

Symptom: Login fails with OAuth provider error
Fix: Verify Client ID/Secret in .env, check callback URL matches OAuth provider config

Session expires too quickly¶

Symptom: User logged out after short time
Fix: Check token expiry settings in login-master config, may need to adjust timeout

User locked out of team¶

Symptom: User can't access team despite being member
Fix: Check user role permissions, may need to re-invite with correct role

OAuth callback hangs¶

Symptom: After clicking OAuth button, page doesn't respond
Fix: Check if Herald is running (login-master depends on it), verify network connectivity

Profile picture not showing¶

Symptom: Avatar field is blank despite OAuth provider having image
Fix: OAuth provider may not have granted permission to access picture, re-authorize with image permission

Related Realms¶

• herald - Login-master validates tokens through herald auth gateway
• f3l1x-dashboard - Users authenticate to access dashboard
• All realms - Can verify tokens from login-master

Further Reading¶

• OAuth Integration Guide
• Team & Permission Management
• Security Best Practices