Authentication

SPEAR supports multiple authentication methods to integrate with your organization’s identity infrastructure. Configure password-based authentication, OAuth2/OpenID Connect providers, or a combination of both.

---

Authentication Methods

Method	Description	Use Case
Password	Local username/password	Standalone deployments
OAuth2/OIDC	Third-party identity providers	Enterprise SSO
Combined	Both password and OAuth	Flexible access

---

Password Authentication

🖥️ Password Settings Configuration Screenshot

Configuration

Password authentication is enabled by default. Configure settings at Admin > Authentication > Password Settings.

Setting	Description	Default
Minimum Length	Minimum password characters	8
Require Uppercase	Must include uppercase letters	Yes
Require Lowercase	Must include lowercase letters	Yes
Require Numbers	Must include numeric characters	Yes
Require Special	Must include special characters	No
Password Expiry	Days until password expires	0 (never)

Password Reset

Users can reset passwords via email if SMTP is configured:

1. User clicks “Forgot Password” on login page
2. Reset link sent to registered email
3. User sets new password via link
4. Old sessions are invalidated

---

OAuth2 / OpenID Connect

🖥️ OAuth Provider Configuration Screenshot

Supported Providers

SPEAR supports standard OAuth2/OIDC providers:

Provider	Protocol	Notes
Google Workspace	OIDC	Email domain restriction available
Microsoft Entra ID	OIDC	Azure AD / Office 365
GitHub	OAuth2	Organization membership checks
GitLab	OAuth2	Self-hosted supported
Okta	OIDC	Enterprise identity
Custom OIDC	OIDC	Any compliant provider

Configuration Steps

1. Navigate to Admin > Authentication > OAuth Providers
2. Click Add Provider
3. Select provider type
4. Enter configuration:
   • Client ID
   • Client Secret
   • Redirect URI (provided by SPEAR)
   • Additional scopes (if needed)
5. Test the connection
6. Enable the provider

Google Workspace Setup

1. Go to Google Cloud Console
2. Create or select a project
3. Navigate to APIs & Services > Credentials
4. Click Create Credentials > OAuth client ID
5. Select Web application
6. Add authorized redirect URI from SPEAR
7. Copy Client ID and Client Secret to SPEAR

Microsoft Entra ID Setup

1. Go to Azure Portal
2. Navigate to Azure Active Directory > App registrations
3. Click New registration
4. Enter name and select supported account types
5. Add redirect URI from SPEAR
6. Copy Application (client) ID
7. Create client secret under Certificates & secrets
8. Configure in SPEAR

GitHub Setup

1. Go to GitHub Settings > Developer settings > OAuth Apps
2. Click New OAuth App
3. Enter application details
4. Add authorization callback URL from SPEAR
5. Copy Client ID and generate Client Secret
6. Configure in SPEAR

---

Session Management

🖥️ Session Management Settings Screenshot

Session Settings

Configure session behavior at Admin > Authentication > Sessions.

Setting	Description	Default
Session Timeout	Inactive session expiry	24 hours
Max Sessions	Maximum concurrent sessions per user	Unlimited
Remember Me	Extended session duration	30 days
Secure Cookies	Require HTTPS for cookies	Auto

Active Sessions

Users can view and manage their active sessions:

1. Go to Account Settings > Sessions
2. View list of active sessions with:
   • Device/browser information
   • IP address
   • Last activity
3. Click Revoke to end specific sessions
4. Click Revoke All to end all other sessions

Admin Session Management

Administrators can manage user sessions:

1. Navigate to Admin > Security > Active Sessions
2. View all active sessions across users
3. Filter by user, IP, or activity
4. Revoke sessions as needed

---

Multi-Factor Authentication

Coming Soon

MFA support is planned for a future release.

Planned MFA methods:

• TOTP (Google Authenticator, Authy)
• WebAuthn / Passkeys
• Email verification codes

---

Single Sign-On (SSO)

SSO Behavior

When OAuth providers are configured:

1. User clicks provider button on login page
2. Redirected to identity provider
3. User authenticates with provider
4. Redirected back to SPEAR with authorization code
5. SPEAR exchanges code for user information
6. User account created or linked automatically
7. Session established

Account Linking

When a user signs in via OAuth and an account with matching email exists:

• Auto-link enabled: Accounts are automatically linked
• Auto-link disabled: User must verify ownership first

Configure at Admin > Authentication > Account Linking.

Email Domain Restriction

Restrict OAuth sign-ups to specific email domains:

1. Go to Admin > Authentication > OAuth Providers
2. Select provider
3. Add allowed domains (e.g., yourcompany.com)
4. Save changes

Users with non-matching email domains cannot create accounts.

---

Just-In-Time Provisioning

When enabled, new users are automatically created on first OAuth login:

Setting	Description
Auto-create users	Create account on first OAuth login
Default group	Group to assign new users
Email domain filter	Only provision from specific domains

Configure at Admin > Authentication > Provisioning.

---

Security Recommendations

For Password Authentication

• Enable password complexity requirements
• Set password expiry for sensitive environments
• Configure account lockout after failed attempts
• Require password change on first login

For OAuth/SSO

• Use OIDC over plain OAuth2 when available
• Restrict to specific email domains
• Disable password auth if SSO-only desired
• Monitor for unusual login patterns

General

• Enable HTTPS (required for OAuth)
• Set appropriate session timeouts
• Regular audit log review
• Disable unused authentication methods

---

Troubleshooting

OAuth Login Fails

“Redirect URI mismatch”

• Verify redirect URI in provider matches exactly
• Check for http vs https mismatch
• Ensure no trailing slashes

“Invalid client”

• Verify Client ID is correct
• Check if credentials were rotated

“Access denied”

• User may not have permission in identity provider
• Check email domain restrictions

Password Reset Not Working

1. Verify SMTP is configured correctly
2. Check spam/junk folders
3. Verify user email address is correct
4. Check SMTP logs for delivery errors

Session Issues

User logged out unexpectedly

• Check session timeout settings
• Verify secure cookie settings match HTTPS status
• Check for IP address changes (VPN, mobile)

Can’t maintain session

• Clear browser cookies
• Check browser privacy settings
• Verify clock synchronization