Vaultx.Auth.GitHub (Vaultx v0.7.0)

View Source

GitHub authentication method for HashiCorp Vault.

This module implements the GitHub authentication method for Vault, providing secure authentication using GitHub personal access tokens with comprehensive support for organization membership, team-based policies, and user-specific permissions.

Features

  • Token Authentication: GitHub personal access token-based authentication
  • Organization Membership: Verify users belong to configured GitHub organization
  • Team-Based Policies: Map GitHub teams to Vault policies
  • User-Specific Policies: Assign policies to individual GitHub users
  • Enterprise Support: Works with GitHub Enterprise Server
  • Audit Integration: Comprehensive audit logging for security compliance

API Compliance

Fully implements HashiCorp Vault GitHub authentication:

Usage Examples

Basic Authentication

{:ok, auth_response} = Vaultx.Auth.GitHub.authenticate(%{
  token: "ghp_xxxxxxxxxxxxxxxxxxxx"
})

Authentication with Custom Mount Path

{:ok, auth_response} = Vaultx.Auth.GitHub.authenticate(%{
  token: "ghp_xxxxxxxxxxxxxxxxxxxx"
}, mount_path: "custom-github")

Authentication with Additional Options

{:ok, auth_response} = Vaultx.Auth.GitHub.authenticate(%{
  token: "ghp_xxxxxxxxxxxxxxxxxxxx"
}, [
  mount_path: "github",
  timeout: 30_000,
  retry_attempts: 3
])

Vault Configuration

Before using this authentication method, configure it in Vault:

# Enable GitHub auth method
vault auth enable github

# Configure GitHub organization
vault write auth/github/config \
  organization="my-org" \
  base_url="https://api.github.com"

# Map GitHub team to policies
vault write auth/github/map/teams/dev \
  value="dev-policy,default"

# Map GitHub user to policies
vault write auth/github/map/users/john-doe \
  value="admin-policy,default"

GitHub Token Requirements

The GitHub personal access token must have the following permissions:

  • read:org - To verify organization membership
  • read:user - To read user information
  • user:email - To read user email (optional)

Security Considerations

  • Use personal access tokens with minimal required scopes
  • Regularly rotate GitHub tokens
  • Monitor authentication events in Vault audit logs
  • Configure appropriate team and user mappings
  • Use least privilege principle for policy assignments
  • Consider token expiration policies