Auth Commands

Manage authentication providers in your PearDrop application.

peardrop auth add-entra

Add Microsoft Entra ID (Azure AD) as an authentication provider.

Prerequisite: If authentication hasn't been injected yet, run:

peardrop feature auth

# Interactive mode
peardrop auth add-entra

# Non-interactive mode
peardrop auth add-entra \
  --client-id "12345678-1234-1234-1234-123456789abc" \
  --tenant-id "87654321-4321-4321-4321-cba987654321" \
  --client-secret "your-client-secret" \
  --display-name "Company Azure AD"

What It Does:

1. Registers Entra ID provider in PearDrop authentication configuration
2. Adds OAuth configuration to appsettings.json
3. Configures redirect URIs for OAuth flow
4. Updates login UI with "Sign in with Microsoft" button

Generated configuration:

{
  "PearDrop": {
    "Authentication": {
      "ExternalProviders": {
        "Entra": [
          {
            "Id": "entra-company",
            "DisplayName": "Company Azure AD",
            "ClientId": "12345678-1234-1234-1234-123456789abc",
            "TenantId": "87654321-4321-4321-4321-cba987654321",
            "ClientSecret": "your-client-secret",
            "Enabled": true
          }
        ]
      }
    }
  }
}

Options

Option	Description	Required
--client-id	Azure app registration client ID	Yes
--tenant-id	Azure tenant ID	Yes
--client-secret	Client secret from Azure	Yes
--display-name	Name shown on login button	No (defaults to "Microsoft")
--no-interactive	Skip prompts	No

Azure Portal Setup

Before running this command, you must create an app registration in Azure:

1. Navigate to Azure Portal → Azure Active Directory → App registrations
2. New registration:
   • Name: Your app name
   • Supported account types: Choose based on requirements
   • Redirect URI: https://yourapp.com/signin-oidc
3. Copy Client ID from Overview page
4. Copy Tenant ID from Overview page
5. Create Client Secret:
   • Certificates & secrets → New client secret
   • Copy secret value (only shown once!)
6. API permissions:
   • Add openid, profile, email
   • Grant admin consent

Use Cases

Enterprise SSO:

# Add company Azure AD for employee login
peardrop auth add-entra \
  --client-id "$AZURE_CLIENT_ID" \
  --tenant-id "$AZURE_TENANT_ID" \
  --client-secret "$AZURE_CLIENT_SECRET" \
  --display-name "Company SSO"

Multi-organization Support:

# Add multiple Entra providers for different customers
peardrop auth add-entra --display-name "Customer A Azure AD"
peardrop auth add-entra --display-name "Customer B Azure AD"

peardrop auth toggle-internal

Enable or disable internal (username/password) authentication.

# Disable internal auth (external-only)
peardrop auth toggle-internal --disable

# Enable internal auth
peardrop auth toggle-internal --enable

# Interactive mode (prompts for action)
peardrop auth toggle-internal

What It Does:

1. Updates authentication configuration in appsettings.json
2. Shows/hides registration form based on internal auth status
3. Requires external provider when internal disabled

Updated configuration:

{
  "PearDrop": {
    "Authentication": {
      "InternalProvider": {
        "Enabled": false
      }
    }
  }
}

Options

Option	Description
--enable	Enable internal authentication
--disable	Disable internal authentication

Use Cases

External-Only Authentication:

# Force all users to use Azure AD/Entra
peardrop feature auth
peardrop auth add-entra --display-name "Company SSO"
peardrop auth toggle-internal --disable

Hybrid Authentication:

# Allow both internal and external login
peardrop auth add-entra
peardrop auth toggle-internal --enable

Development → Production:

# Development: Use internal auth for testing
peardrop auth toggle-internal --enable

# Production: Disable internal, require SSO
peardrop auth toggle-internal --disable

Safety Warning

⚠️ Disabling internal auth when external providers are not configured will lock out all users!

Before disabling internal auth:

1. Add at least one external provider (peardrop auth add-entra)
2. Test external login with a test user
3. Verify external provider is working
4. Only then disable internal auth

peardrop auth list-entra

List all configured Entra ID authentication providers.

peardrop auth list-entra

Example Output:

Configured Entra ID Providers:
┌──────────────────┬─────────────────────┬─────────────────────────────────────┬─────────┐
│ ID               │ Display Name        │ Tenant ID                           │ Enabled │
├──────────────────┼─────────────────────┼─────────────────────────────────────┼─────────┤
│ entra-company    │ Company Azure AD    │ 87654321-4321-4321-4321-cba987654321│ Yes     │
│ entra-customer-a │ Customer A SSO      │ 12345678-1234-1234-1234-123456789abc│ Yes     │
│ entra-customer-b │ Customer B SSO      │ abcdefab-abcd-abcd-abcd-abcdefabcdef│ No      │
└──────────────────┴─────────────────────┴─────────────────────────────────────┴─────────┘

Total: 3 providers (2 enabled)

Use Cases

Audit Authentication Setup:

# Check which providers are configured
peardrop auth list-entra

Before Disabling Internal Auth:

# Verify at least one provider is enabled
peardrop auth list-entra
# If count > 0 and enabled, safe to disable internal
peardrop auth toggle-internal --disable

peardrop auth remove-entra

Remove a configured Entra ID authentication provider.

# Interactive mode (shows list, select to remove)
peardrop auth remove-entra

# Direct removal by ID
peardrop auth remove-entra --id entra-company

What It Does:

1. Removes provider configuration from appsettings.json
2. Removes login button from UI
3. Prevents new logins via that provider
4. Does NOT delete existing users who logged in via that provider

Options

Option	Description
--id	Provider ID to remove

Use Cases

Remove Unused Provider:

# List providers
peardrop auth list-entra

# Remove specific provider
peardrop auth remove-entra --id entra-old-customer

Customer Offboarding:

# Customer no longer needs access
peardrop auth remove-entra --id entra-customer-xyz

# If they were the only external provider, enable internal auth
peardrop auth toggle-internal --enable

Safety Warning

⚠️ Removing the last external provider when internal auth is disabled will lock out users!

Safe removal workflow:

# 1. Check current providers
peardrop auth list-entra

# 2. If removing last provider, enable internal auth first
peardrop auth toggle-internal --enable

# 3. Now safe to remove provider
peardrop auth remove-entra --id last-provider

Complete Authentication Scenarios

Scenario 1: Enterprise SSO Setup

# 1. Start with auth feature
peardrop feature auth

# 2. Add company Entra ID
peardrop auth add-entra \
  --client-id "$AZURE_CLIENT_ID" \
  --tenant-id "$AZURE_TENANT_ID" \
  --client-secret "$AZURE_CLIENT_SECRET" \
  --display-name "Company SSO"

# 3. Test external login
# ... test in browser ...

# 4. Disable internal auth (SSO only)
peardrop auth toggle-internal --disable

# 5. Verify configuration
peardrop auth list-entra

Scenario 2: Multi-Tenant SaaS with Per-Customer SSO

# 1. Enable multitenancy + auth
peardrop feature auth
peardrop feature multitenancy --strategy host

# 2. Add Entra providers for each customer
peardrop auth add-entra --display-name "Customer A Azure AD"
peardrop auth add-entra --display-name "Customer B Azure AD"

# 3. Keep internal auth enabled for customers without SSO
peardrop auth toggle-internal --enable

# 4. List all providers
peardrop auth list-entra

Scenario 3: Development → Production Migration

# Development: Internal auth only
peardrop feature auth
peardrop auth toggle-internal --enable

# ... develop application ...

# Production: Add SSO, disable internal
peardrop auth add-entra --display-name "Production SSO"
peardrop auth toggle-internal --disable

Troubleshooting

Entra ID Login Fails

Problem: Users see "AADSTS50011: Invalid redirect URI" error

Solution:

1. Check Azure app registration redirect URIs
2. Add your app's callback URL: https://yourapp.com/signin-oidc
3. Include both production and development URLs if needed

Cannot Remove Provider

Problem: peardrop auth remove-entra command fails

Solution:

# Enable internal auth first (safety measure)
peardrop auth toggle-internal --enable

# Now remove provider
peardrop auth remove-entra --id provider-id

# Verify removal
peardrop auth list-entra

Client Secret Expired

Problem: Entra login suddenly stops working

Solution:

1. Check Azure Portal → App registration → Certificates & secrets
2. Create new client secret
3. Update appsettings.json with new secret
4. Restart application

Multiple Providers Show Same Display Name

Problem: Can't distinguish between providers on login page

Solution:

# Remove ambiguous provider
peardrop auth remove-entra --id old-provider

# Re-add with clear display name
peardrop auth add-entra --display-name "Customer A - Production Azure AD"

Next Steps

• Feature Commands - Add auth feature if not already present
• Utility Commands - Update and maintain your app
• Authentication Guide - Learn authentication concepts