[management, infrastructure, idp] Simplified IdP Management - Embedded IdP (#5008)

Embed Dex as a built-in IdP to simplify self-hosting setup. Adds an embedded OIDC Identity Provider (Dex) with local user management and optional external IdP connectors (Google/GitHub/OIDC/SAML), plus device-auth flow for CLI login. Introduces instance onboarding/setup endpoints (including owner creation), field-level encryption for sensitive user data, a streamlined self-hosting provisioning script, and expanded APIs + test coverage for IdP management. more at https://github.com/netbirdio/netbird/pull/5008#issuecomment-3718987393
2026-04-16 07:16:38 +00:00 · 2026-01-07 08:52:32 -05:00
parent 5393ad948f
commit e586c20e36
90 changed files with 7702 additions and 517 deletions
--- a/shared/management/client/client_test.go
+++ b/shared/management/client/client_test.go
@@ -129,7 +129,7 @@ func startManagement(t *testing.T) (*grpc.Server, net.Listener) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, secretsManager, nil, nil, mgmt.MockIntegratedValidator{}, networkMapController)
+	mgmtServer, err := nbgrpc.NewServer(config, accountManager, settingsMockManager, secretsManager, nil, nil, mgmt.MockIntegratedValidator{}, networkMapController, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
--- a/shared/management/http/api/openapi.yml
+++ b/shared/management/http/api/openapi.yml
@@ -32,6 +32,10 @@ tags:
  - name: Ingress Ports
    description: Interact with and view information about the ingress peers and ports.
    x-cloud-only: true
+  - name: Identity Providers
+    description: Interact with and view information about identity providers.
+  - name: Instance
+    description: Instance setup and status endpoints for initial configuration.
 components:
  schemas:
    Account:
@@ -149,6 +153,11 @@ components:
          description: Set Clients auto-update version. "latest", "disabled", or a specific version (e.g "0.50.1")
          type: string
          example: "0.51.2"
+        embedded_idp_enabled:
+          description: Indicates whether the embedded identity provider (Dex) is enabled for this account. This is a read-only field.
+          type: boolean
+          readOnly: true
+          example: false
      required:
        - peer_login_expiration_enabled
        - peer_login_expiration
@@ -206,6 +215,10 @@ components:
          description: User's email address
          type: string
          example: demo@netbird.io
+        password:
+          description: User's password. Only present when user is created (create user endpoint is called) and only when IdP supports user creation with password.
+          type: string
+          example: super_secure_password
        name:
          description: User's name from idp provider
          type: string
@@ -252,6 +265,10 @@ components:
          description: How user was issued by API or Integration
          type: string
          example: api
+        idp_id:
+          description: Identity provider ID (connector ID) that the user authenticated with. Only populated for users with Dex-encoded user IDs.
+          type: string
+          example: okta-abc123
        permissions:
          $ref: '#/components/schemas/UserPermissions'
      required:
@@ -2250,6 +2267,118 @@ components:
        - page_size
        - total_records
        - total_pages
+    IdentityProviderType:
+      type: string
+      description: Type of identity provider
+      enum:
+        - oidc
+        - zitadel
+        - entra
+        - google
+        - okta
+        - pocketid
+        - microsoft
+      example: oidc
+    IdentityProvider:
+      type: object
+      properties:
+        id:
+          description: Identity provider ID
+          type: string
+          example: ch8i4ug6lnn4g9hqv7l0
+        type:
+          $ref: '#/components/schemas/IdentityProviderType'
+        name:
+          description: Human-readable name for the identity provider
+          type: string
+          example: My OIDC Provider
+        issuer:
+          description: OIDC issuer URL
+          type: string
+          example: https://accounts.google.com
+        client_id:
+          description: OAuth2 client ID
+          type: string
+          example: 123456789.apps.googleusercontent.com
+      required:
+        - type
+        - name
+        - issuer
+        - client_id
+    IdentityProviderRequest:
+      type: object
+      properties:
+        type:
+          $ref: '#/components/schemas/IdentityProviderType'
+        name:
+          description: Human-readable name for the identity provider
+          type: string
+          example: My OIDC Provider
+        issuer:
+          description: OIDC issuer URL
+          type: string
+          example: https://accounts.google.com
+        client_id:
+          description: OAuth2 client ID
+          type: string
+          example: 123456789.apps.googleusercontent.com
+        client_secret:
+          description: OAuth2 client secret
+          type: string
+          example: secret123
+      required:
+        - type
+        - name
+        - issuer
+        - client_id
+        - client_secret
+    InstanceStatus:
+      type: object
+      description: Instance status information
+      properties:
+        setup_required:
+          description: Indicates whether the instance requires initial setup
+          type: boolean
+          example: true
+      required:
+        - setup_required
+    SetupRequest:
+      type: object
+      description: Request to set up the initial admin user
+      properties:
+        email:
+          description: Email address for the admin user
+          type: string
+          example: admin@example.com
+        password:
+          description: Password for the admin user (minimum 8 characters)
+          type: string
+          format: password
+          minLength: 8
+          example: securepassword123
+        name:
+          description: Display name for the admin user (defaults to email if not provided)
+          type: string
+          example: Admin User
+      required:
+        - email
+        - password
+        - name
+    SetupResponse:
+      type: object
+      description: Response after successful instance setup
+      properties:
+        user_id:
+          description: The ID of the created user
+          type: string
+          example: abc123def456
+        email:
+          description: Email address of the created user
+          type: string
+          example: admin@example.com
+      required:
+        - user_id
+        - email
  responses:
    not_found:
      description: Resource not found
@@ -2287,6 +2416,48 @@ security:
  - BearerAuth: [ ]
  - TokenAuth: [ ]
 paths:
+  /api/instance:
+    get:
+      summary: Get Instance Status
+      description: Returns the instance status including whether initial setup is required. This endpoint does not require authentication.
+      tags: [ Instance ]
+      security: [ ]
+      responses:
+        '200':
+          description: Instance status information
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InstanceStatus'
+        '500':
+          "$ref": "#/components/responses/internal_error"
+  /api/setup:
+    post:
+      summary: Setup Instance
+      description: Creates the initial admin user for the instance. This endpoint does not require authentication but only works when setup is required (no accounts exist and embedded IDP is enabled).
+      tags: [ Instance ]
+      security: [ ]
+      requestBody:
+        description: Initial admin user details
+        required: true
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/SetupRequest'
+      responses:
+        '200':
+          description: Setup completed successfully
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SetupResponse'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '412':
+          description: Setup already completed
+          content: { }
+        '500':
+          "$ref": "#/components/responses/internal_error"
  /api/accounts:
    get:
      summary: List all Accounts
@@ -4877,3 +5048,147 @@ paths:
          "$ref": "#/components/responses/forbidden"
        '500':
          "$ref": "#/components/responses/internal_error"
+  /api/identity-providers:
+    get:
+      summary: List all Identity Providers
+      description: Returns a list of all identity providers configured for the account
+      tags: [ Identity Providers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      responses:
+        '200':
+          description: A JSON array of identity providers
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/IdentityProvider'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    post:
+      summary: Create an Identity Provider
+      description: Creates a new identity provider configuration
+      tags: [ Identity Providers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      requestBody:
+        description: Identity provider configuration
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/IdentityProviderRequest'
+      responses:
+        '200':
+          description: An Identity Provider object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdentityProvider'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+  /api/identity-providers/{idpId}:
+    get:
+      summary: Retrieve an Identity Provider
+      description: Get information about a specific identity provider
+      tags: [ Identity Providers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: idpId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of an identity provider
+      responses:
+        '200':
+          description: An Identity Provider object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdentityProvider'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    put:
+      summary: Update an Identity Provider
+      description: Update an existing identity provider configuration
+      tags: [ Identity Providers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: idpId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of an identity provider
+      requestBody:
+        description: Identity provider update
+        content:
+          'application/json':
+            schema:
+              $ref: '#/components/schemas/IdentityProviderRequest'
+      responses:
+        '200':
+          description: An Identity Provider object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IdentityProvider'
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
+    delete:
+      summary: Delete an Identity Provider
+      description: Delete an identity provider configuration
+      tags: [ Identity Providers ]
+      security:
+        - BearerAuth: [ ]
+        - TokenAuth: [ ]
+      parameters:
+        - in: path
+          name: idpId
+          required: true
+          schema:
+            type: string
+          description: The unique identifier of an identity provider
+      responses:
+        '200':
+          description: Delete status code
+          content: { }
+        '400':
+          "$ref": "#/components/responses/bad_request"
+        '401':
+          "$ref": "#/components/responses/requires_authentication"
+        '403':
+          "$ref": "#/components/responses/forbidden"
+        '500':
+          "$ref": "#/components/responses/internal_error"
--- a/shared/management/http/api/types.gen.go
+++ b/shared/management/http/api/types.gen.go
@@ -83,6 +83,17 @@ const (
 	GroupMinimumIssuedJwt         GroupMinimumIssued = "jwt"
 )

+// Defines values for IdentityProviderType.
+const (
+	IdentityProviderTypeEntra     IdentityProviderType = "entra"
+	IdentityProviderTypeGoogle    IdentityProviderType = "google"
+	IdentityProviderTypeMicrosoft IdentityProviderType = "microsoft"
+	IdentityProviderTypeOidc      IdentityProviderType = "oidc"
+	IdentityProviderTypeOkta      IdentityProviderType = "okta"
+	IdentityProviderTypePocketid  IdentityProviderType = "pocketid"
+	IdentityProviderTypeZitadel   IdentityProviderType = "zitadel"
+)
+
 // Defines values for IngressPortAllocationPortMappingProtocol.
 const (
 	IngressPortAllocationPortMappingProtocolTcp    IngressPortAllocationPortMappingProtocol = "tcp"
@@ -298,8 +309,11 @@ type AccountSettings struct {
 	AutoUpdateVersion *string `json:"auto_update_version,omitempty"`

 	// DnsDomain Allows to define a custom dns domain for the account
-	DnsDomain *string               `json:"dns_domain,omitempty"`
-	Extra     *AccountExtraSettings `json:"extra,omitempty"`
+	DnsDomain *string `json:"dns_domain,omitempty"`
+
+	// EmbeddedIdpEnabled Indicates whether the embedded identity provider (Dex) is enabled for this account. This is a read-only field.
+	EmbeddedIdpEnabled *bool                 `json:"embedded_idp_enabled,omitempty"`
+	Extra              *AccountExtraSettings `json:"extra,omitempty"`

 	// GroupsPropagationEnabled Allows propagate the new user auto groups to peers that belongs to the user
 	GroupsPropagationEnabled *bool `json:"groups_propagation_enabled,omitempty"`
@@ -520,6 +534,45 @@ type GroupRequest struct {
 	Resources *[]Resource `json:"resources,omitempty"`
 }

+// IdentityProvider defines model for IdentityProvider.
+type IdentityProvider struct {
+	// ClientId OAuth2 client ID
+	ClientId string `json:"client_id"`
+
+	// Id Identity provider ID
+	Id *string `json:"id,omitempty"`
+
+	// Issuer OIDC issuer URL
+	Issuer string `json:"issuer"`
+
+	// Name Human-readable name for the identity provider
+	Name string `json:"name"`
+
+	// Type Type of identity provider
+	Type IdentityProviderType `json:"type"`
+}
+
+// IdentityProviderRequest defines model for IdentityProviderRequest.
+type IdentityProviderRequest struct {
+	// ClientId OAuth2 client ID
+	ClientId string `json:"client_id"`
+
+	// ClientSecret OAuth2 client secret
+	ClientSecret string `json:"client_secret"`
+
+	// Issuer OIDC issuer URL
+	Issuer string `json:"issuer"`
+
+	// Name Human-readable name for the identity provider
+	Name string `json:"name"`
+
+	// Type Type of identity provider
+	Type IdentityProviderType `json:"type"`
+}
+
+// IdentityProviderType Type of identity provider
+type IdentityProviderType string
+
 // IngressPeer defines model for IngressPeer.
 type IngressPeer struct {
 	AvailablePorts AvailablePorts `json:"available_ports"`
@@ -653,6 +706,12 @@ type IngressPortAllocationRequestPortRange struct {
 // IngressPortAllocationRequestPortRangeProtocol The protocol accepted by the port range
 type IngressPortAllocationRequestPortRangeProtocol string

+// InstanceStatus Instance status information
+type InstanceStatus struct {
+	// SetupRequired Indicates whether the instance requires initial setup
+	SetupRequired bool `json:"setup_required"`
+}
+
 // Location Describe geographical location information
 type Location struct {
 	// CityName Commonly used English name of the city
@@ -1833,6 +1892,27 @@ type SetupKeyRequest struct {
 	Revoked bool `json:"revoked"`
 }

+// SetupRequest Request to set up the initial admin user
+type SetupRequest struct {
+	// Email Email address for the admin user
+	Email string `json:"email"`
+
+	// Name Display name for the admin user (defaults to email if not provided)
+	Name string `json:"name"`
+
+	// Password Password for the admin user (minimum 8 characters)
+	Password string `json:"password"`
+}
+
+// SetupResponse Response after successful instance setup
+type SetupResponse struct {
+	// Email Email address of the created user
+	Email string `json:"email"`
+
+	// UserId The ID of the created user
+	UserId string `json:"user_id"`
+}
+
 // User defines model for User.
 type User struct {
 	// AutoGroups Group IDs to auto-assign to peers registered by this user
@@ -1844,6 +1924,9 @@ type User struct {
 	// Id User ID
 	Id string `json:"id"`

+	// IdpId Identity provider ID (connector ID) that the user authenticated with. Only populated for users with Dex-encoded user IDs.
+	IdpId *string `json:"idp_id,omitempty"`
+
 	// IsBlocked Is true if this user is blocked. Blocked users can't use the system
 	IsBlocked bool `json:"is_blocked"`

@@ -1862,6 +1945,9 @@ type User struct {
 	// Name User's name from idp provider
 	Name string `json:"name"`

+	// Password User's password. Only present when user is created (create user endpoint is called) and only when IdP supports user creation with password.
+	Password *string `json:"password,omitempty"`
+
 	// PendingApproval Is true if this user requires approval before being activated. Only applicable for users joining via domain matching when user_approval_required is enabled.
 	PendingApproval bool             `json:"pending_approval"`
 	Permissions     *UserPermissions `json:"permissions,omitempty"`
@@ -2003,6 +2089,12 @@ type PostApiGroupsJSONRequestBody = GroupRequest
 // PutApiGroupsGroupIdJSONRequestBody defines body for PutApiGroupsGroupId for application/json ContentType.
 type PutApiGroupsGroupIdJSONRequestBody = GroupRequest

+// PostApiIdentityProvidersJSONRequestBody defines body for PostApiIdentityProviders for application/json ContentType.
+type PostApiIdentityProvidersJSONRequestBody = IdentityProviderRequest
+
+// PutApiIdentityProvidersIdpIdJSONRequestBody defines body for PutApiIdentityProvidersIdpId for application/json ContentType.
+type PutApiIdentityProvidersIdpIdJSONRequestBody = IdentityProviderRequest
+
 // PostApiIngressPeersJSONRequestBody defines body for PostApiIngressPeers for application/json ContentType.
 type PostApiIngressPeersJSONRequestBody = IngressPeerCreateRequest

@@ -2057,6 +2149,9 @@ type PostApiRoutesJSONRequestBody = RouteRequest
 // PutApiRoutesRouteIdJSONRequestBody defines body for PutApiRoutesRouteId for application/json ContentType.
 type PutApiRoutesRouteIdJSONRequestBody = RouteRequest

+// PostApiSetupJSONRequestBody defines body for PostApiSetup for application/json ContentType.
+type PostApiSetupJSONRequestBody = SetupRequest
+
 // PostApiSetupKeysJSONRequestBody defines body for PostApiSetupKeys for application/json ContentType.
 type PostApiSetupKeysJSONRequestBody = CreateSetupKeyRequest