headplane/docs/OIDC-Authentication.md

OIDC Authentication and Role Mapping

Headplane supports authentication via external identity providers using OpenID Connect (OIDC), with automatic role assignment based on group membership. This enables enterprise-grade, role-based access control integrated with your existing identity infrastructure.

Features

• Single Sign-On (SSO): Seamless authentication with popular identity providers
• Automatic Role Assignment: Users receive appropriate roles based on OIDC group membership
• Zero-Trust Security: New users get minimal access until proper groups are assigned
• Dynamic Updates: User roles update automatically on each login
• Configurable Mapping: Customize which groups map to which roles for your organization

Basic Configuration

1. Identity Provider Setup

First, configure your identity provider to work with Headplane:

=== "Keycloak" 1. Create a new client for Headplane 2. Set client protocol to openid-connect 3. Set access type to confidential 4. Add redirect URI: https://your-headplane.com/admin/oidc/callback 5. Configure group membership mapper (see Group Configuration)

=== "Azure AD" 1. Create new App Registration 2. Add redirect URI: https://your-headplane.com/admin/oidc/callback 3. Enable ID tokens 4. Configure API permissions for GroupMember.Read.All 5. Add groups claim to ID tokens

=== "Okta" 1. Create new Web Application 2. Add redirect URI: https://your-headplane.com/admin/oidc/callback 3. Configure group claims in token 4. Set grant types to Authorization Code

2. Headplane Configuration

Configure OIDC in your config.yaml:

oidc:
  # OIDC provider configuration
  issuer: "https://your-provider.com/realm"
  client_id: "headplane-client"
  client_secret: "your-client-secret"
  
  # Include groups scope for role mapping
  scope: "openid email profile groups"
  
  # Headplane callback URL
  redirect_uri: "https://your-headplane.com/admin/oidc/callback"
  
  # API key for Headscale communication
  headscale_api_key: "your-headscale-api-key"
  
  # Optional: Disable API key login (force OIDC only)
  disable_api_key_login: false

3. Headscale Configuration

Ensure Headscale is configured to extract and store OIDC groups:

oidc:
  issuer: "https://your-provider.com/realm"
  client_id: "headscale-client"
  client_secret: "your-client-secret"
  scope: ["openid", "profile", "email", "groups"]  # Include groups

Role Mapping

Default Role Hierarchy

Headplane uses a hierarchical role system where the highest privilege group determines the final role:

1. Owner - Full system access including user management
2. Admin - Administrative access to all features
3. Network Admin - Network configuration and routing
4. IT Admin - Machine and user management
5. Auditor - Read-only access for compliance
6. Member - Zero capabilities (no UI access)

Configuring Role Mapping

Add role mapping configuration to automatically assign roles based on OIDC groups:

oidc:
  # ... other OIDC configuration ...
  
  # Custom role mapping for your organization
  role_mapping:
    owner: ["ceo", "cto", "headplane-owners"]
    admin: ["it-admins", "platform-team", "administrators"]
    network_admin: ["network-team", "devops", "infrastructure"]
    it_admin: ["helpdesk", "support-team", "it-staff"]
    auditor: ["compliance", "audit-team", "security"]

Group Matching

Groups are matched using several strategies:

1. Exact Match: Group name exactly matches mapping configuration
2. Case Insensitive: Admin, admin, and ADMIN all match
3. Partial Match: Groups containing keywords like admin, network, audit

Example Role Mappings by Organization Type

=== "Corporate IT" yaml role_mapping: owner: ["cto", "it-director"] admin: ["senior-admin", "platform-lead"] network_admin: ["network-ops", "infrastructure"] it_admin: ["helpdesk", "desktop-support"] auditor: ["compliance", "security-team"]

=== "Healthcare" yaml role_mapping: owner: ["chief-information-officer"] admin: ["hipaa-admin", "system-admin"] network_admin: ["clinical-infrastructure"] it_admin: ["medical-devices", "clinical-support"] auditor: ["hipaa-compliance", "privacy-officer"]

=== "Financial Services" yaml role_mapping: owner: ["compliance-officer", "risk-management"] admin: ["fintech-admin", "trading-systems"] network_admin: ["market-data", "trading-infrastructure"] it_admin: ["client-support", "operations"] auditor: ["sox-audit", "regulatory-compliance"]

Group Configuration

Keycloak Group Setup

1. Create Groups: Create groups in Keycloak that match your role mapping
2. Group Membership Mapper:
   • Name: groups
   • Mapper Type: Group Membership
   • Token Claim Name: groups
   • Add to ID token: ✓
   • Add to access token: ✓
   • Add to userinfo: ✓
   • Full group path: ✗ (recommended)

Azure AD Group Setup

1. Create Security Groups: Create groups in Azure AD
2. Configure Group Claims:
   • Go to Token Configuration
   • Add groups claim
   • Select "Security groups"
   • Include in ID tokens and Access tokens

Okta Group Setup

1. Create Groups: Create groups in Okta
2. Configure Claims:
   • Go to Claims (ID Token)
   • Add claim named groups
   • Value type: Groups
   • Filter: Matches regex .*

Security Model

Zero-Trust Approach

• Default Deny: New users receive member role with zero capabilities
• Explicit Allow: Only users with recognized groups get elevated privileges
• Regular Validation: Group membership checked on every login
• Audit Trail: All role assignments logged for compliance

First User Bootstrap

The first OIDC user automatically receives the owner role regardless of group membership, ensuring administrative access is available for initial setup.

Role Capabilities

Role	Capabilities
Owner	Full access + user management + system configuration
Admin	All features except owner-level user management
Network Admin	Network configuration, DNS, routing, machine management
IT Admin	Machine management, user support, limited network access
Auditor	Read-only access to all features for compliance
Member	No UI access (can only use Tailscale client)

Advanced Configuration

Custom Profile Picture Sources

Choose where profile pictures are sourced from:

oidc:
  # Use OIDC provider pictures (default)
  profile_picture_source: "oidc"
  
  # Or use Gravatar based on email
  profile_picture_source: "gravatar"

Extra Authentication Parameters

Pass additional parameters to the authorization endpoint:

oidc:
  extra_params:
    prompt: "select_account"  # Force account selection
    domain_hint: "example.com"  # Azure AD domain hint
    acr_values: "mfa"  # Request multi-factor auth

Token Endpoint Configuration

Customize how tokens are exchanged:

oidc:
  # Method for client authentication
  token_endpoint_auth_method: "client_secret_post"  # or "client_secret_basic"
  
  # Manual endpoint configuration (if discovery fails)
  authorization_endpoint: "https://provider.com/auth"
  token_endpoint: "https://provider.com/token"
  userinfo_endpoint: "https://provider.com/userinfo"

Monitoring and Troubleshooting

Enable Debug Logging

Set environment variable for detailed OIDC logs:

HEADPLANE_DEBUG_LOG=true

Common Issues

Groups not appearing in roles:

• Verify groups scope is included in OIDC configuration
• Check identity provider group mapper configuration
• Ensure user is member of mapped groups

Wrong role assigned:

• Review role mapping configuration for group name matching
• Check for case sensitivity issues
• Verify group hierarchy (highest privilege wins)

First login fails:

• Ensure redirect URI matches exactly in identity provider
• Check client secret is correct
• Verify Headscale API key is valid and has sufficient permissions

Validation Steps

1. Test OIDC Flow: Use identity provider's test tools to verify token contents
2. Check Groups: Verify groups claim appears in ID token or UserInfo response
3. Review Logs: Check Headplane logs for role assignment messages
4. Database Check: Verify groups are stored in Headplane user database

Migration from Manual Roles

Gradual Migration Strategy

1. Deploy with Feature Disabled: Deploy OIDC role mapping but keep manual roles
2. Test with Pilot Users: Enable role mapping for select test users
3. Validate Mappings: Ensure all groups map to expected roles
4. Full Rollout: Enable role mapping for all users
5. Cleanup: Remove manual role assignments after validation

Backup and Rollback

Before enabling OIDC role mapping:

# Backup current user roles
sqlite3 /var/lib/headplane/headplane.db \
  "SELECT id, sub, caps FROM users;" > user_roles_backup.sql

# Rollback if needed
sqlite3 /var/lib/headplane/headplane.db < user_roles_backup.sql

Integration with Headscale

Headplane's OIDC role mapping works in conjunction with Headscale's OIDC group storage:

1. Headscale extracts groups from OIDC claims and stores them in the database
2. Headplane reads groups from Headscale users and maps them to roles
3. Dynamic Updates ensure role changes take effect on next login
4. Consistent State between Headscale groups and Headplane roles

This integration provides a complete enterprise identity solution while maintaining separation of concerns between the VPN control plane (Headscale) and management interface (Headplane).

For more information about Headscale OIDC configuration, see the Headscale OIDC documentation.