NanoIDP

Test real OAuth2/OIDC, SAML 2.0 and MCP authorization flows locally,
without running a production IAM stack.

📖 Documentation

Design principles, non-goals and medium-term direction live in VISION.md.

Need a real OAuth2/OIDC or SAML counterpart for an integration test, a demo or an agent, without standing up Keycloak or provisioning a cloud tenant?

NanoIDP is an identity test environment: a spec-honest OAuth2/OIDC and SAML 2.0 provider you install with pip, configure with two YAML files and throw away when the test is done. What it advertises is what it implements, so your client is tested against the specification, not against a mock's guesses. It is a development and testing tool, not a production IdP.

Quick Start

pip install nanoidp

python -m nanoidp init    # create ./config (users, settings, keys)
python -m nanoidp         # serve on http://localhost:8000

Get a first token:

curl -X POST 'http://localhost:8000/token' \
  -u 'demo-client:demo-secret' \
  -d 'grant_type=client_credentials'

The admin UI runs at http://localhost:8000. Prefer Docker?

docker run --rm -p 8000:8000 \
  -v $(pwd)/config:/app/config \
  ghcr.io/cdelmonte-zg/nanoidp:latest

From here: the Quickstart walks through users, clients and the Authorization Code + PKCE flow; Requesting tokens has a copy-paste request for every grant; Install covers the wizard, custom config paths and docker-compose.

What you can test against it

• OAuth2 / OIDC: Authorization Code with PKCE, Client Credentials, Refresh Token with rotation, Device Authorization (RFC 8628) and the Password grant for legacy clients; introspection (RFC 7662), revocation (RFC 7009) and RP-initiated logout; per-client scopes and audiences, claims mapping and authority prefixes; an opt-in oauth21 profile that enforces draft OAuth 2.1 strictness.
• SAML 2.0: SSO and AttributeQuery with signed assertions, and opt-in verification of signed AuthnRequests.
• Agents and MCP: an MCP server that lets an agent create users and clients, mint tokens and read the audit log, with a read-only mode; MCP tools and the HTTP API expose the same capabilities.
• Running it: two schema-versioned YAML files with validation, security profiles, a passwordless persona login for demos, an audit log, hooks and plugins for wiring the deploy in, a Docker image.

Every item above has its reference page in the documentation below.

Documentation

The full documentation lives at https://cdelmonte-zg.github.io/nanoidp/:

• Requesting tokens: curl examples for every grant, introspection, revocation
• MCP workflow: drive NanoIDP from Claude Code or any MCP host
• Security guide: profiles, key management, MCP hardening
• Configuration: users.yaml, settings.yaml, logging
• Endpoints: OAuth2/OIDC, SAML, REST API
• Tokens and claims: token structure and aud semantics
• SAML options: bindings, strict mode, signing, canonicalization
• MCP server: all tools and Claude Code/Desktop setup

Security

NanoIDP is a development/testing tool and must NOT be used in production. Defaults favor convenience (plaintext passwords in config, permissive CORS, open redirects); hardening is opt-in via the stricter-dev (runtime) and oauth21 (draft OAuth 2.1 protocol strictness) profiles and explicit settings. The Security guide draws the line precisely.

Development

pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the development setup, the end-to-end test agent, code quality tooling, and the release process.

Adopters

Organizations using NanoIDP in their development or testing workflows:

• World Direct

Listing means NanoIDP is in use there. It does not imply sponsorship or endorsement. If you use it and would like to be listed, open an issue or a pull request against this section.

License

MIT License. See LICENSE for details.

❤️ Support NanoIDP

NanoIDP is maintained as an open-source project.

If it helps you test OAuth2, OpenID Connect, or SAML flows, you can support its development here:

• 💖 GitHub Sponsors: https://github.com/sponsors/cdelmonte-zg
• ☕ Buy Me a Coffee: https://buymeacoffee.com/nanoidp