A command-line tool to automate GitHub Enterprise Cloud SAML SSO setup with Microsoft Entra ID.

• 🏢 Automated Entra ID Setup: Creates and configures GitHub Enterprise Managed User application
• 🔧 SAML Configuration: Automates SAML settings, certificates, and URLs in Entra ID
• 👥 User Assignment: Automatically assigns current user with Enterprise Owner role
• 🔄 SCIM Provisioning: Interactive setup for automatic user provisioning
• 📋 Manual Guidance: Provides exact values and opens GitHub SAML settings page
• ✅ Validation: Built-in checks for enterprise access and prerequisites
• 🛡️ Safe Setup: Dry-run mode and confirmation prompts for critical actions

This tool automates the complex process described in Microsoft's GitHub Enterprise SSO documentation. Always verify your configuration in both GitHub and Entra ID admin portals after setup.

• Node.js 16 or higher - Download here
• Git (for GitHub installation method) - Download here

# Install directly from GitHub repository
npm install -g git+https://github.com/benleane83/ghec-sso-setup.git

# Clone the repository
git clone https://github.com/benleane83/ghec-sso-setup.git
cd ghec-sso-setup

# Install dependencies and build
npm install
npm run build

# Install globally
npm install -g .

# Check if the tool is installed correctly
ghec-sso --help

# Check version
ghec-sso --version

# To update to the latest version
npm uninstall -g ghec-sso-cli
npm install -g git+https://github.com/benleane83/ghec-sso-setup.git

1. Authenticate with Azure:

   ghec-sso auth login

2. Set up SSO for your enterprise:

   ghec-sso setup --enterprise mycompany --domain mycompany.onmicrosoft.com

3. Follow the interactive prompts for SCIM setup after GitHub SAML is configured

Automate Entra ID configuration and guide GitHub SAML setup.

ghec-sso setup [options]

Options:
  -e, --enterprise <name>   GitHub Enterprise name (e.g. for /enterprises/my-company, use my-company)
  -d, --domain <domain>     Organization domain (e.g. for company.onmicrosoft.com, use company)
  --dry-run                 Show what would be done without making changes
  --force                   Force setup even if validation fails

What it does:

1. ✅ Validates access
2. 🏢 Creates GitHub Enterprise Managed User app in Entra ID
3. ⚙️ Configures SAML settings (URLs, certificates, claims)
4. 👤 Assigns current user as Enterprise Owner
5. 📋 Outputs SAML values for manual GitHub configuration
6. 🌐 Opens GitHub Enterprise SAML settings page
7. 🔄 Optionally configures SCIM provisioning (interactive)

Example:

# Interactive setup
ghec-sso setup

# With parameters  
ghec-sso setup --enterprise mycompany --domain company

# Dry run to see what would happen
ghec-sso setup --enterprise mycompany --domain company --dry-run

Manage authentication with Azure.

# Login to Azure
ghec-sso auth login

# Check authentication status and show enterprise access
ghec-sso auth status

# Clear stored authentication
ghec-sso auth logout

Validate enterprise access and SSO prerequisites.

# Validate current enterprise
ghec-sso validate

# Validate specific enterprise  
ghec-sso validate --enterprise mycompany --force

GitHub:

• Personal Access Token with scopes:
  • admin:enterprise (Enterprise administration)
  • admin:org (Organization management)
  • repo (Repository access)
• Enterprise Owner role on the target enterprise

Azure/Entra ID:

• Global Administrator or Application Administrator role
• Permission to create Enterprise Applications
• Permission to configure SAML and provisioning

• GitHub Enterprise name (e.g., mycompany)
• Organization domain (e.g., mycompany.com)
• Admin access to both platforms

The CLI uses different authentication methods optimized for enterprise access:

1. Azure: Device flow or Azure CLI credentials
   • Attempts Azure CLI first for seamless experience
   • Falls back to device flow authentication

1. 🔍 Finds GitHub Enterprise Managed User template in application gallery
2. 🏢 Creates Enterprise Application with proper naming
3. ⚙️ Configures SAML settings:
   • Entity ID: https://github.com/enterprises/{enterprise}
   • Reply URL: https://github.com/enterprises/{enterprise}/saml/consume
   • Sign-on URL: https://github.com/enterprises/{enterprise}/sso
4. 🔐 Generates SAML signing certificate
5. 👤 Assigns current user with Enterprise Owner role
6. 📋 Extracts SAML configuration values

7. 🌐 Opens GitHub Enterprise SAML settings page automatically
8. 📋 Provides exact values to copy into GitHub:
   • Sign-On URL
   • Issuer (Entity ID)
   • Certificate (Base64)

9. ⏸️ Pauses for GitHub SAML configuration
10. 🔄 Configures SCIM provisioning (if confirmed):
    • Auto-generates SCIM endpoint: https://api.github.com/scim/v2/enterprises/{enterprise}/
    • Configures provided SCIM token
    • Creates synchronization job
    • Tests SCIM connection
    • Optionally starts automatic provisioning

• ✅ GitHub Enterprise Cloud - Fully supported
• ✅ Trial Enterprises - Fully supported
• ❌ Organizations - Not supported (use organization SAML instead)

• 🔄 Automatic Setup - CLI configures everything in Entra ID
• 📋 Manual GitHub Setup Required - Must enable SAML SSO in GitHub first
• 🔗 Auto-generated Endpoint - No need to manually construct SCIM URL
• ⚡ Optional Auto-start - Can immediately begin provisioning with confirmation

⚠️ Before running setup:

• Ensure you have recovery access to GitHub Enterprise
• This configures SSO for the entire enterprise
• All users will need Entra ID accounts after setup

⚠️ After setup:

• Add additional users/groups to the Entra ID application
• Assign Copilot seats to users in GitHub if required

Local configuration is stored securely:

• Windows: %APPDATA%\ghec-sso-cli\config.json
• macOS: ~/Library/Preferences/ghec-sso-cli/config.json
• Linux: ~/.config/ghec-sso-cli/config.json

Contains:

• Enterprise configurations and last setup status

"Bad credentials" or 401 errors:

# Check current authentication
ghec-sso auth status

# Re-authenticate
ghec-sso auth logout
ghec-sso auth login

Entra ID application creation fails:

• Verify Azure permissions (Application Administrator role)
• Check tenant settings allow enterprise app creation
• Try manual creation if automated approach fails

SCIM provisioning fails:

• Ensure GitHub SAML SSO is enabled first
• Verify SCIM token has correct permissions
• Check SCIM endpoint URL is accessible

# Clone and install dependencies
git clone <repository>
cd ghec-sso-setup
npm install

# Build the project
npm run build

# Run in development mode  
npm run dev -- auth status

# Test specific command
npm run dev -- setup --dry-run -e test -d test.com

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

MIT License - see LICENSE file for details.

This tool handles sensitive authentication data:

• 🔑 Azure tokens are temporary and not persisted
• 📜 SAML certificates are only displayed, not stored
• 🚫 No data is sent to external services

Best Practices:

• Use dedicated PATs with minimal required scopes
• Run ghec-sso auth logout when finished
• Regularly rotate PATs and SAML certificates
• Verify all changes in admin portals