Skip to main content

Authentication CLI Commands

PearDrop CLI provides commands to manage authentication providers and settings without manual configuration.

Command Structure​

All authentication commands are under the auth branch:

dotnet tool run peardrop auth <subcommand> [options]

Available Commands​

Toggle Internal Provider​

Enable or disable local username/password authentication.

# Check current status
dotnet tool run peardrop auth toggle-internal

# Enable internal provider
dotnet tool run peardrop auth toggle-internal --enable

# Disable internal provider
dotnet tool run peardrop auth toggle-internal --disable

# Specify project path
dotnet tool run peardrop auth toggle-internal --enable --project ./MyApp

What it does:

  • Updates appsettings.json with internal provider configuration
  • Sets up password rules and account policies
  • Initializes internal authentication provider in auth module
  • Creates default settings for email/SMS MFA thresholds

When to use:

  • Activating password-based authentication
  • Switching authentication strategies
  • Disabling internal auth in favor of external-only systems

Add Entra ID Provider​

Configure Microsoft Entra ID (formerly Azure AD) for enterprise authentication.

# Interactive setup
dotnet tool run peardrop auth add-entra

# Specify project path
dotnet tool run peardrop auth add-entra --project ./MyApp

# Non-interactive (if you have keys)
# See: Configuration & Settings for detailed setup

Interactive Prompts:

  1. Provider instance ID (Guid for multi-provider support)
  2. Application (client) ID from Azure app registration
  3. Client secret (from Azure portal)
  4. Tenant ID for your Azure directory
  5. Button text (how it appears to users)
  6. Icon URL (logo displayed on sign-in)
  7. Internal auth URL (redirect after external auth)

What it does:

  • Registers provider in appsettings.json
  • Configures OAuth/OpenID Connect settings
  • Sets up Entra ID graph service integration
  • Creates sign-in button configuration
  • Enables external user provisioning

Configuration stored in:

{
  "PearDrop": {
    "modules": {
      "authentication": {
        "providers": {
          "external": {
            "entra": {
              "{provider-id-guid}": {
                "clientId": "...",
                "clientSecret": "...",
                "tenantId": "...",
                "buttonText": "Sign in with Entra ID",
                "iconUrl": "https://...",
                "internalAuthUrl": "/auth/callback"
              }
            }
          }
        }
      }
    }
  }
}

List Entra Providers​

View all configured Entra ID providers.

# List providers in current project
dotnet tool run peardrop auth list-entra

# Specify project
dotnet tool run peardrop auth list-entra --project ./MyApp

Output:

Provider ID: {guid}
  Button Text: Sign in with Entra ID
  Tenant ID: {tenant-guid}
  Configured: ✓

Remove Entra Provider​

Delete an Entra ID provider configuration.

# Interactive selection
dotnet tool run peardrop auth remove-entra

# Remove specific provider by ID
dotnet tool run peardrop auth remove-entra --id {provider-id-guid}

# Specify project
dotnet tool run peardrop auth remove-entra --project ./MyApp

What it does:

  • Removes provider section from appsettings.json
  • Disables the external provider in your app
  • Removes sign-in button configuration
  • Prevents users from accessing that provider

Note: Does not affect user accounts already linked to external provider. Users can still use other authentication methods.

Add AAD Provider (Legacy)​

For Azure AD (legacy version), use add-aad:

dotnet tool run peardrop auth add-aad

The command structure is identical to add-entra. Choose based on your Azure setup:

  • Entra ID - Current recommended approach
  • AAD - Legacy Azure AD (older configurations)

Common Workflows​

Enable Password + Entra ID​

# 1. Enable internal (password) authentication
dotnet tool run peardrop auth toggle-internal --enable

# 2. Add Entra ID as external option
dotnet tool run peardrop auth add-entra

# Result: Users can sign in with either password OR Entra ID

External-Only Authentication​

# 1. Skip internal provider
# Don't run toggle-internal

# 2. Add Entra ID
dotnet tool run peardrop auth add-entra

# 3. (Optional) Add additional provider
dotnet tool run peardrop auth add-entra
# (Use different provider ID/settings)

# Result: Users MUST sign in with external provider

Switch from Internal to External​

# 1. Add external provider (Entra ID)
dotnet tool run peardrop auth add-entra

# 2. Test with users
# 3. Disable internal auth
dotnet tool run peardrop auth toggle-internal --disable

# Result: New users can only use external, existing users migrated gradually

Remove a Problematic Provider​

# 1. List current providers
dotnet tool run peardrop auth list-entra

# 2. Remove the problematic one
dotnet tool run peardrop auth remove-entra --id {problem-provider-id}

# 3. Verify removal
dotnet tool run peardrop auth list-entra

Authentication Feature Injection​

For new projects, use the feature injection command:

# Inject auth feature into minimal template
dotnet tool run peardrop feature auth --project ./MyApp

# This:
# - Adds PearDrop.Authentication NuGet package
# - Creates auth module in your project
# - Registers services in Program.cs
# - Sets up default configuration
# - Adds Razor Pages UI (if using RazorPages)

Equivalent to manually:

  • Installing PearDrop.Authentication NuGet
  • Calling AddPearDropAuthentication() in Program.cs
  • Creating auth UI components
  • Configuring appsettings.json

CLI Options Reference​

Global Options​

--project <PATH>         Path to project root (default: current directory)
--help, -h              Show command help
--version               Show CLI version

Provider Options (add-entra, add-aad)​

--project <PATH>        Project to configure
--client-id <ID>        Application client ID (skips interactive prompt)
--tenant-id <ID>        Azure tenant ID (skips interactive prompt)
--secret <SECRET>       Client secret (skips interactive prompt)
--button-text <TEXT>    Sign-in button text (skips interactive prompt)

Next Steps​