Authentication Setup Guide

Detailed authentication configuration for SSO, OAuth, and MFA

Authentication Architecture

Authentication Methods

Email & Password

Configuration:

auth:
  email:
    enabled: true
    verification: required
    passwordPolicy:
      minLength: 8
      requireUppercase: true
      requireLowercase: true
      requireNumbers: true
      requireSpecialChars: true
    lockout:
      maxAttempts: 5
      duration: 15m

Password Requirements:

Minimum 8 characters
Mix of uppercase and lowercase
At least one number
At least one special character

Multi-Factor Authentication (MFA)

Supported Methods:

Method	Description
TOTP	Time-based OTP (Google Authenticator, Authy)
SMS	Text message codes
Email	Email verification codes
WebAuthn	Hardware tokens (FIDO2)

Configuration:

auth:
  mfa:
    enabled: true
    required: false  # Set to true to enforce
    methods:
      - totp
      - email
    gracePeriod: 7d  # Time before enforcement

OAuth 2.0 Providers

Supported Providers:

Microsoft / Azure AD / Entra ID
Google / Google Workspace
GitHub
Okta
Custom OAuth 2.0

SSO Integration

Azure AD / Entra ID

Step 1: Azure Portal Configuration

Navigate to Azure Portal → Azure Active Directory
App registrations → New registration
Configure:
- Name: GraphPolaris
- Supported account types: Single tenant or Multi-tenant
- Redirect URI: https://your-instance.com/auth/callback/azure

Step 2: Configure Permissions

Add required permissions:

openid
profile
email
User.Read

Step 3: Create Client Secret

Certificates & secrets → New client secret
Copy the secret value immediately
Store securely

Step 4: GraphPolaris Configuration

auth:
  providers:
    azure:
      enabled: true
      clientId: "<application-id>"
      clientSecret: "<client-secret>"
      tenantId: "<tenant-id>"
      scopes:
        - openid
        - profile
        - email
      claims:
        email: email
        name: name
        firstName: given_name
        lastName: family_name

Okta

Step 1: Okta Admin Configuration

Applications → Create App Integration
Select: OIDC - OpenID Connect
Application type: Web Application
Configure:
- App name: GraphPolaris
- Sign-in redirect URIs: https://your-instance.com/auth/callback/okta
- Sign-out redirect URIs: https://your-instance.com/auth/signout

Step 2: GraphPolaris Configuration

auth:
  providers:
    okta:
      enabled: true
      clientId: "<client-id>"
      clientSecret: "<client-secret>"
      domain: "<your-org>.okta.com"
      scopes:
        - openid
        - profile
        - email

Google Workspace

Step 1: Google Cloud Console

APIs & Services → Credentials
Create OAuth 2.0 Client ID
Application type: Web application
Authorized redirect URIs: https://your-instance.com/auth/callback/google

Step 2: GraphPolaris Configuration

auth:
  providers:
    google:
      enabled: true
      clientId: "<client-id>"
      clientSecret: "<client-secret>"
      hostedDomain: "yourcompany.com"  # Optional: restrict to domain

Generic OIDC Provider

auth:
  providers:
    oidc:
      enabled: true
      name: "Corporate SSO"
      issuer: "https://sso.company.com"
      clientId: "<client-id>"
      clientSecret: "<client-secret>"
      scopes:
        - openid
        - profile
        - email
      claims:
        email: email
        name: name
        groups: groups  # Optional: for role mapping

Session Management

Configuration

session:
  store: redis
  duration: 8h
  idleTimeout: 30m
  rememberMe:
    enabled: true
    duration: 30d
  concurrent:
    enabled: true
    maxSessions: 5
  cookie:
    secure: true
    httpOnly: true
    sameSite: lax

Session Security Features

Feature	Description
Device Fingerprinting	Track login devices
IP Validation	Optional IP binding
Concurrent Limits	Max sessions per user
Force Logout	Admin session revocation

Role-Based Access Control

Default Roles

Role	Permissions
Admin	Full organizational control
Editor	Create/modify graphs, queries
Viewer	Read-only access

Group Mapping

Map identity provider groups to GraphPolaris roles:

auth:
  roleMapping:
    enabled: true
    claim: groups
    mappings:
      - group: "graphpolaris-admins"
        role: admin
      - group: "graphpolaris-editors"
        role: editor
      - group: "graphpolaris-viewers"
        role: viewer
    defaultRole: viewer

Azure AD Group Mapping

auth:
  providers:
    azure:
      groupsClaim: groups
      groupMappings:
        "<admin-group-object-id>": admin
        "<editor-group-object-id>": editor

Just-in-Time Provisioning

Automatic User Creation:

auth:
  jit:
    enabled: true
    defaultRole: viewer
    attributes:
      - email
      - firstName
      - lastName
      - department
    syncOnLogin: true  # Update attributes on each login

API Authentication

JWT Tokens

auth:
  jwt:
    secret: "<jwt-secret>"  # Use Kubernetes secret
    algorithm: HS256
    accessTokenExpiry: 15m
    refreshTokenExpiry: 7d
    issuer: "https://your-instance.com"

API Keys (Coming Soon)

auth:
  apiKeys:
    enabled: true
    prefix: "gp_"
    hashAlgorithm: sha256
    rateLimit: 1000/hour

Security Best Practices

For Administrators

Enable MFA - Require for all users
Use SSO - Centralize authentication
Regular Access Reviews - Audit quarterly
Least Privilege - Minimal permissions
Monitor Logs - Review authentication events
Session Timeouts - Configure appropriate limits

Hardening Checklist

Troubleshooting

Common Issues

"Invalid credentials"

Verify username/email
Check password (case-sensitive)
Account may be locked

"SSO configuration error"

Verify redirect URIs match exactly
Check client secret is current
Ensure user is assigned to application

"Session expired"

Normal after idle timeout
Re-authenticate
Enable "Remember Me" for longer sessions

Debug Logging

Enable debug logging for authentication:

logging:
  auth:
    level: debug
    includeTokens: false  # Never log tokens

Health Check

# Check auth service
curl https://your-instance.com/auth/health

# Verify OIDC discovery
curl https://your-instance.com/.well-known/openid-configuration

Migration Guide

From Basic Auth to SSO

Configure SSO provider
Test with pilot users
Enable JIT provisioning
Communicate to users
Set grace period
Disable password auth (optional)

User Account Linking

auth:
  accountLinking:
    enabled: true
    strategy: email  # Link by email address
    requireVerification: true

Contact

Enable Advanced Authentication: Contact your account representative with:

Organization details
Authentication requirements
Identity provider information
Timeline

Security Reference

Comprehensive security architecture and configuration guide