Embedded DEX and IdP Docs

[TechHutTV]

Summary

This PR updates the self-hosted documentation to reflect the new local user management functionality introduced in PR #5008. NetBird self-hosted deployments no longer require an external identity provider—users can be created and managed directly from the Dashboard.

To Do

• All steps in instructions need to be reviewed and tested
• Verify new API docs for accuracy
• Replace X.XX version placeholders with actual version
• Verify script name (getting-started.sh) matches implementation
• Verify /setup endpoint and onboarding flow matches implementation
• Verify API endpoints in api-reference.mdx match implementation
• Review Dashboard UI terminology (Settings → Identity Providers, etc.)
• Add any new screenshots

Key Changes

New Default: Local User Management

• No external IdP required - The Management service now supports creating local users directly
• Onboarding flow - New instances start without users; first user created via /setup wizard
• Multiple external IdPs - Optionally connect multiple OIDC-compatible providers (Google, Microsoft, Okta, etc.)
• Simplified deployment - Fewer containers, lower resource requirements (~1GB vs 2-4GB previously)

Documentation Structure Changes

New pages:

• identity-providers/embedded-idp.mdx - Comprehensive guide for the built-in user management feature
• identity-providers/idp-connectors.mdx - Guide for adding external identity providers alongside local users
• identity-providers/api-reference.mdx - API documentation for IdP management endpoints

Updated pages:

• selfhosted-quickstart.mdx - Complete rewrite with local users as default; Zitadel moved to legacy section
• selfhosted-guide.mdx - Positioned as advanced guide for standalone IdP setups; added migration notes
• identity-providers/index.mdx - Restructured overview with embedded IdP as primary option; updated links
• self-hosted-vs-cloud-netbird.mdx - Added "No External IdP Required" section and updated comparison
• troubleshooting.mdx - Added comprehensive "Embedded IdP Issues" troubleshooting section

Provider pages (all 9 updated with unified structure):

• google.mdx - Added "Connector Setup (Recommended)" section before standalone setup
• microsoft.mdx - Added connector setup with microsoft/entra type distinction
• keycloak.mdx - Added connector setup instructions
• zitadel.mdx - Added connector setup + migration notes from quickstart
• authentik.mdx - Added connector setup instructions
• okta.mdx - Added connector setup instructions
• auth0.mdx - Added connector setup instructions
• jumpcloud.mdx - Added connector setup instructions
• pocketid.mdx - Added connector setup instructions

All provider pages now include:

• "Connector Setup (Recommended)" section for adding providers to embedded IdP
• Existing "Standalone Setup (Advanced)" sections preserved
• Clear distinction between connector and standalone approaches

API Documentation Updates

New IPA API Resource:

• ipa/resources/identity-providers.mdx - Full CRUD documentation for identity provider connector management:
  • GET /api/identity-providers (list all)
  • GET /api/identity-providers/{id} (get single)
  • POST /api/identity-providers (create)
  • PUT /api/identity-providers/{id} (update)
  • DELETE /api/identity-providers/{id} (delete)
  • Includes multi-language code examples and provider type documentation

Updated IPA API Resources:

• ipa/resources/accounts.mdx - Added instance setup endpoints at the beginning:
  • GET /api/instance (check if setup required)
  • POST /api/instance/setup (complete initial setup)
• ipa/resources/users.mdx - Enhanced user creation documentation:
  • Added embedded IdP behavior notes
  • Documented password field (only returned once at creation)
  • Documented idp_id field for SSO-authenticated users

Navigation Updates

Documentation Navigation (NavigationDocs.jsx):

• Reorganized "SELF-HOST NETBIRD" section above "USE CASES" for better visibility
• Moved "Supported IdPs" subsection above "Advanced guide" within SELF-HOST NETBIRD
• Added three new pages under "Supported IdPs": Embedded IdP, Connectors, API Reference
• Renamed "Connectors" link to point to idp-connectors.mdx

API Navigation (NavigationAPI.jsx):

• Added "Identity Providers" to the Resources section (positioned after "Users", before "Tokens")

New Quickstart Flow

1. Run getting-started.sh script (no Zitadel)
2. Navigate to Dashboard → redirected to /setup
3. Create first admin user
4. Log in and start using NetBird
5. (Optional) Add more local users from Dashboard
6. (Optional) Connect external identity providers for SSO

Provider Page Structure

Each provider page now follows a unified structure:

# Provider Name

Brief description of the provider.

## Connector Setup (Recommended)
- Step 1: Create OAuth app in provider
- Step 2: Add provider in NetBird Dashboard  
- Step 3: Configure redirect URI
- Step 4: Test connection

---

## Standalone Setup (Advanced)
[Full original documentation preserved]

## Troubleshooting
[Common issues and solutions]

## Related Resources
[Links to provider docs, API reference, etc.]

Files Changed

Self-Hosted Documentation

selfhosted/
├── identity-providers/index.mdx              # Updated - restructured overview
├── selfhosted-quickstart.mdx                 # Major rewrite
├── selfhosted-guide.mdx                      # Updated with embedded IdP references
├── self-hosted-vs-cloud-netbird.mdx          # Updated
├── troubleshooting.mdx                       # Expanded with embedded IdP section
└── identity-providers/
    ├── embedded-idp.mdx                      # New
    ├── idp-connectors.mdx                    # New (renamed from connectors.mdx)
    ├── api-reference.mdx                     # New
    ├── google-workspace.mdx                  # Updated - added connector setup
    ├── microsoft-entra-id.mdx                # Updated - added connector setup
    ├── keycloak.mdx                          # Updated - added connector setup
    ├── zitadel.mdx                           # Updated - added connector setup
    ├── authentik.mdx                         # Updated - added connector setup
    ├── okta.mdx                              # Updated - added connector setup
    ├── auth0.mdx                             # Updated - added connector setup
    ├── jumpcloud.mdx                         # Updated - added connector setup
    └── pocketid.mdx                          # Updated - added connector setup

API Documentation

ipa/resources/
├── identity-providers.mdx                    # New - full IdP connector API docs
├── accounts.mdx                              # Updated - added instance setup endpoints
└── users.mdx                                 # Updated - embedded IdP behavior docs

Navigation

components/
├── NavigationDocs.jsx                        # Updated - reorganized sections, added new pages
└── NavigationAPI.jsx                         # Updated - added Identity Providers resource

Notes

• All existing standalone IdP documentation is preserved in the "Standalone Setup (Advanced)" sections
• Screenshot references maintained for all provider pages
• Version placeholder X.XX used throughout - replace with actual version number before merge
• Script name getting-started.sh assumed - verify against actual implementation
• All API documentation follows existing IPA format with multi-language code examples

Related

netbirdio/netbird#5008
netbirdio/dashboard#523