idplease

🪪 IDPlease

A tiny OIDC Identity Provider for development and pilot deployments.

What is this?

IDPlease is a drop-in replacement for Microsoft Entra ID (formerly Azure AD) designed for local development, testing, and small pilot deployments. Instead of configuring a real Entra tenant with app registrations, redirect URIs, and user assignments, just run IDPlease and get a fully functional OIDC provider in seconds.

Why use it?

• 🏗️ Local development — No internet, no Azure subscription, no app registration dance
• 🧪 Integration testing — Spin up a predictable auth server in CI
• 🚀 Pilot deployments — Lightweight auth for internal tools before committing to Entra
• 🔌 Entra-compatible claims — oid, upn, roles, groups, tid — your app won't know the difference
• 📦 Single binary — No external dependencies, just one executable with embedded SQLite

Features:

• OpenID Connect Authorization Code flow with PKCE (S256)
• Client Credentials flow (machine-to-machine)
• Refresh token support with rotation
• Client registry with public and confidential clients
• UserInfo endpoint
• Token revocation (RFC 7009)
• End session / logout endpoint
• Standard discovery (/.well-known/openid-configuration) and JWKS endpoints
• RS256-signed JWTs with auto-generated keys
• User and role management via CLI and web-based Admin UI
• Client management via CLI and Admin UI
• Rate limiting on login attempts (per-user and per-IP)
• CORS support with configurable origins
• Health check endpoint
• First-run bootstrap user
• Structured logging (slog)
• SQLite-backed storage (no external database needed)
• Works behind reverse proxies with configurable base path

Quick Start

1. Get the binary

Download from Releases, or build from source:

go install github.com/jclement/idplease@latest

Or use Docker:

docker run -p 8080:8080 -v $(pwd)/data:/data ghcr.io/jclement/idplease:latest

2. Start the server

./idplease server

On first start, IDPlease will:

• Create an idplease.db SQLite database
• Generate an RSA signing key (idplease-key.json)
• Generate a one-time admin key and print it to the console
• Create a bootstrap admin user with a random password (printed to stdout)

Override bootstrap credentials with environment variables:

IDPLEASE_ADMIN_USER=myadmin IDPLEASE_ADMIN_PASSWORD=mypassword ./idplease server

3. Open the Admin UI

Navigate to http://localhost:8080/admin and enter the admin key shown in the console output.

From the admin UI you can:

• Manage users — add, edit, delete users; reset passwords
• Manage roles for each user
• Manage OAuth clients — add, edit, delete clients (public or confidential)
• Configure settings — issuer, token lifetimes, redirect URIs, CORS origins, group mappings, etc.

4. Or use the CLI

# Add a user
./idplease user add bob

# Add some roles
./idplease role add bob Admin
./idplease role add bob Reader

# Add an OAuth client
./idplease client add my-spa

# List clients
./idplease client list

5. Point your app at it

Discovery URL: http://localhost:8080/.well-known/openid-configuration

That's it. Your app can now authenticate users against IDPlease.

OIDC Endpoints

All endpoints are relative to the configured base path (default /).

Token Endpoint Grant Types

• authorization_code — Standard OIDC auth code exchange, optionally with PKCE
• refresh_token — Refresh token rotation (issues new access + refresh token, revokes old)
• client_credentials — Machine-to-machine (confidential clients only, no id_token/refresh_token)

CORS

CORS headers are applied to /token, /userinfo, /revoke, and JWKS endpoints. Configure allowed origins via Admin UI or config (default: ["*"]).

Rate Limiting

Login attempts are rate-limited:

• Per username: 5 attempts per minute
• Per IP: 20 attempts per minute

Exceeding the limit shows a "too many attempts" error on the login form.

Admin UI

IDPlease includes a built-in web admin interface at {basePath}/admin.

Admin Key

The admin UI is protected by an admin key. You can set it in several ways (in order of priority):

1. CLI flag: ./idplease server --admin-key=mysecret
2. Environment variable: IDPLEASE_ADMIN_KEY=mysecret
3. Config file: "adminKey": "mysecret" in idplease.json
4. Auto-generated: If none of the above are set, a random key is generated and printed to stdout on startup

Admin Pages

• Dashboard — Overview: user count, client count, configured issuer
• Settings — Edit: display name, issuer URL, client IDs, tenant ID, access/refresh token lifetimes, redirect URIs, CORS origins, group mappings, session secret
• Users — List, add, edit, delete users; reset passwords
• Roles — Per-user role management: add/remove roles
• Clients — List, add, delete OAuth clients (public or confidential)

CLI Reference

All commands support --config <path> to specify an alternate config file (default: idplease.json).

Server

./idplease server
./idplease server --admin-key=mysecretkey
./idplease server --config /etc/idplease/config.json

User Management

./idplease user add alice       # Interactive: prompts for email, display name, password
./idplease user list
./idplease user delete alice
./idplease user reset bob       # Prompts for new password

Role Management

./idplease role add bob Admin
./idplease role list bob
./idplease role remove bob Admin

Client Management

./idplease client add my-app    # Interactive: prompts for name, type, redirect URIs
./idplease client list
./idplease client delete my-app

Configuration

./idplease config set issuer https://idp.example.com
./idplease config get issuer
./idplease config list

Configuration

IDPlease uses a JSON config file (idplease.json) for server-level settings and SQLite for OIDC/user configuration.

Config File (idplease.json)

OIDC Settings (in SQLite, managed via Admin UI or CLI)

Example: idplease.json

{
  "port": 8080,
  "adminKey": "my-secret-admin-key",
  "dbFile": "/data/idplease.db",
  "keyFile": "/data/idplease-key.json"
}

Environment Variables

Token Claims

IDPlease tokens include the following claims, designed for compatibility with Microsoft Entra ID:

First-Run Bootstrap

On first startup with an empty database, IDPlease automatically creates an admin user with:

• A randomly generated 16-character password
• The IDPlease.Admin role

Credentials are printed prominently to stdout. Override with IDPLEASE_ADMIN_USER and IDPLEASE_ADMIN_PASSWORD environment variables.

Docker

docker run -p 8080:8080 -v $(pwd)/data:/data ghcr.io/jclement/idplease:latest

The SQLite database, key file, and config are all stored in /data.

Docker Compose with Cloudflare Tunnel

See docker-compose.yml for a complete example pairing IDPlease with a Cloudflare Tunnel.

docker compose up -d
docker compose exec idplease idplease user add bob
docker compose exec idplease idplease role add bob Admin

Data Files

⚠️ Backup idplease-key.json if token continuity matters. Regenerating the key invalidates all previously issued tokens.

Building from Source

git clone https://github.com/jclement/idplease.git
cd idplease
go build -o idplease .

# With version info
go build -ldflags "-X github.com/jclement/idplease/internal/config.Version=1.0.0" -o idplease .

Running Tests

go test ./...

License

MIT — Copyright (c) 2026 Jeff Clement