Skip to content

README.md

Latest commit

 

History

History
184 lines (127 loc) · 5.83 KB

README.md

File metadata and controls

184 lines (127 loc) · 5.83 KB
Raw

Azure DB Login Helper

Azure DB Login Helper demonstration

A cross-platform tray/menu-bar app for Azure PostgreSQL access tokens after PIM activation. Works on Windows and macOS.

Features

  • Tray / menu bar icon — runs in the background
  • PIM shortcut — opens the Azure PIM group activation page
  • Token copy — MSAL-based tokens (respects PIM group membership when a role is selected)
  • Role switching — read / write (configured in appsettings.local.json), or Plain token (no role check)
  • Group-claim check — warns if the active PIM group is missing from the token

Prerequisites

  • .NET 10 SDK
  • Entra ID account with eligible PIM roles (when using role-based config)

Configuration

Copy the example file and edit your local settings (not committed to git):

cp appsettings.example.json appsettings.local.json

Edit appsettings.local.json.

Plain token (no PIM role switching or group-claim check):

{
  "AzureDbLogin": {
    "TenantId": "your-tenant-id"
  }
}

With PIM roles (menu to switch read/write or Plain token (no role check); verifies the Entra group is in the token when a role is selected):

{
  "AzureDbLogin": {
    "TenantId": "...",
    "PostgresHost": "your-server.postgres.database.azure.com",
    "Database": "yourdb",
    "DefaultRole": "read",
    "Roles": [
      {
        "Key": "read",
        "DisplayName": "Read (SELECT only)",
        "PgUser": "your-read-group-role",
        "GroupObjectId": "..."
      }
    ]
  }
}

PostgresHost / Database / PgUser are optional metadata for your own reference. GroupObjectId is required per role when Roles is configured.

Windows

Run locally

dotnet run
  • Look for the icon in the system tray (click ^ if hidden).
  • Right-click the icon for the menu.
  • Double-click copies a cached token.
  • Quit: tray Exit, or Ctrl+C in the terminal when using dotnet run.

Install at login

scripts\install-startup.bat

Removes with scripts\uninstall-startup.bat.

Troubleshooting (Windows)

  • Build fails (file locked) — exit the app from the tray or Task Manager, then rebuild.
  • Token missing group claim — PIM not active, or stale cache; use Regenerate token.
  • Groups overage — too many Entra groups; token omits groups claim — contact an admin.

macOS

First-time setup

  1. Install the .NET 10 SDK for macOS (Apple Silicon or Intel as appropriate).

  2. Clone or open this repository in a terminal.

  3. Create your config:

    cp appsettings.example.json appsettings.local.json

    Edit appsettings.local.json with your tenant ID, roles, and group object IDs.

Run locally

From the project directory:

dotnet run
  • Look for the menu bar icon at the top right of the screen (blue circle with a database glyph).
  • Click the icon to open the menu (macOS does not use right-click on menu bar items).
  • Use Copy token (use cache) or Regenerate token from the menu.
  • macOS shows short notifications when a token is copied or a role is selected.
  • Quit: choose Exit in the menu, or press Ctrl+C in the terminal when using dotnet run.

If the icon is crowded out, open System Settings → Control Center → Menu Bar and adjust spacing, or drag other menu bar icons to make room.

Build a Release binary

dotnet build -c Release -f net10.0
./bin/Release/net10.0/AzureDbLoginHelper

appsettings.local.json is copied into bin/Release/net10.0/ on build. Keep it next to the executable if you move the app elsewhere.

Install at login (LaunchAgent)

The install script builds Release, registers a user LaunchAgent, and starts the app at login:

chmod +x scripts/install-startup-macos.sh
./scripts/install-startup-macos.sh

This creates ~/Library/LaunchAgents/com.azuredblogin.helper.plist pointing at:

bin/Release/net10.0/AzureDbLoginHelper

Re-run the script after pulling code changes so the binary is rebuilt and the agent is reloaded.

Uninstall:

launchctl unload ~/Library/LaunchAgents/com.azuredblogin.helper.plist
rm ~/Library/LaunchAgents/com.azuredblogin.helper.plist

Stop without uninstalling:

launchctl unload ~/Library/LaunchAgents/com.azuredblogin.helper.plist

Start again:

launchctl load ~/Library/LaunchAgents/com.azuredblogin.helper.plist

Troubleshooting (macOS)

  • Menu bar icon not visible — macOS hides overflow icons when the menu bar is full; free space or use Control Center settings. Confirm the process is running: pgrep -l AzureDbLoginHelper.
  • App exits immediately after install — ensure appsettings.local.json exists before running scripts/install-startup-macos.sh (it must be copied into bin/Release/net10.0/). Check logs: log show --predicate 'process == "AzureDbLoginHelper"' --last 5m or run the binary manually in Terminal to see errors.
  • Browser does not open for sign-in — allow the app when macOS prompts for network or automation; run once via dotnet run to complete the interactive login.
  • Token missing group claim — activate PIM in the portal, select the correct Role in the menu (not Plain token), then Regenerate token.
  • Groups overage — too many Entra groups; token omits groups claim — contact an admin.

Typical workflow

  1. Open PIM activation from the tray/menu
  2. Activate the role in the Azure portal
  3. Select Role in the app (read / write), or Plain token (no role check) if you only need an unscoped token
  4. Regenerate token and paste into your database tool (Azure Data Studio, DBeaver, etc.)