MicroMDM Architecture: Building Enterprise Apple Device Management#

MicroMDM is an open-source Mobile Device Management (MDM) server written in Go, designed to manage Apple devices using the Apple MDM protocol. This comprehensive guide explores its architecture, components, and implementation details, providing insights for building and deploying enterprise-grade Apple device management solutions.

Overview#

MicroMDM serves as a lean “core” MDM engine, providing the essential infrastructure for Apple device management without the overhead of high-level features. Organizations typically build additional functionality on top of it or integrate it with other services to create complete MDM solutions.

Key Design Principles#

Minimalist Core: Focuses on MDM protocol implementation
API-First: HTTP REST API for all operations
Modular Architecture: Clear separation of concerns
Extensible: Designed for customization and integration

Architecture Layers#

1. HTTP Server (Front-End Layer)#

The HTTP server handles all incoming connections and routes them appropriately:

1
// Example endpoint structure
2
type Server struct {
3
    MDMService     MDMService
4
    EnrollService  EnrollmentService
5
    CommandService CommandService
6
    APNSService    APNSService
7
}
8

9
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
10
    switch r.URL.Path {
11
    case "/mdm/enroll":
12
        s.handleEnrollment(w, r)
13
    case "/mdm/checkin":
14
        s.handleCheckin(w, r)
15
    case "/api/v1/commands":
16
        s.handleCommandAPI(w, r)
17
    default:
18
        http.NotFound(w, r)
19
    }
20
}

Key Endpoints:

/mdm/enroll: Serves enrollment profiles
/mdm/checkin: Handles device check-ins
/api/v1/*: Administrative API endpoints

2. Service/Business Logic Layer#

This layer manages the core MDM operations:

1
// Device enrollment service
2
type EnrollmentService interface {
3
    CreateEnrollmentProfile(config ProfileConfig) (*Profile, error)
4
    EnrollDevice(request EnrollmentRequest) (*Device, error)
5
    GetEnrollmentProfile(uuid string) (*Profile, error)
6
}
7

8
// Command processing service
9
type CommandService interface {
10
    QueueCommand(deviceUUID string, command Command) error
11
    GetPendingCommands(deviceUUID string) ([]Command, error)
12
    UpdateCommandStatus(commandUUID string, status CommandStatus) error
13
}

3. Persistence Layer#

MicroMDM uses BoltDB for data storage:

1
// Device storage implementation
2
type BoltDeviceStorage struct {
3
    db *bolt.DB
4
}
5

6
func (s *BoltDeviceStorage) Save(device *Device) error {
7
    return s.db.Update(func(tx *bolt.Tx) error {
8
        b := tx.Bucket([]byte("devices"))
9
        data, err := json.Marshal(device)
10
        if err != nil {
11
            return err
12
        }
13
        return b.Put([]byte(device.UDID), data)
14
    })
15
}

4. APNS Integration#

Apple Push Notification Service integration for device wake-up:

1
type APNSClient struct {
2
    Certificate tls.Certificate
3
    Production  bool
4
}
5

6
func (c *APNSClient) Push(deviceToken string, payload APNSPayload) error {
7
    // Connect to APNS
8
    conn, err := tls.Dial("tcp", c.getAPNSHost(), &tls.Config{
9
        Certificates: []tls.Certificate{c.Certificate},
10
    })
11
    if err != nil {
12
        return err
13
    }
14
    defer conn.Close()
15

16
    // Send push notification
17
    return c.sendPayload(conn, deviceToken, payload)
18
}

Component Deep Dive#

Enrollment Process#

The enrollment flow involves multiple components working together:

1
sequenceDiagram
2
    participant Device
3
    participant EnrollEndpoint
4
    participant EnrollService
5
    participant Storage
6
    participant ProfileSigner
7

8
    Device->>EnrollEndpoint: GET /mdm/enroll
9
    EnrollEndpoint->>EnrollService: RequestEnrollmentProfile()
10
    EnrollService->>ProfileSigner: SignProfile()
11
    ProfileSigner-->>EnrollService: Signed Profile
12
    EnrollService-->>EnrollEndpoint: Enrollment Profile
13
    EnrollEndpoint-->>Device: .mobileconfig
14

15
    Device->>Device: Install Profile
16
    Device->>EnrollEndpoint: POST /mdm/checkin (Authenticate)
17
    EnrollEndpoint->>EnrollService: ProcessAuthentication()
18
    EnrollService->>Storage: CreateDevice()
19
    Storage-->>EnrollService: Device Created
20
    EnrollService-->>EnrollEndpoint: Success
21
    EnrollEndpoint-->>Device: 200 OK

Command Queue Implementation#

Commands are queued and delivered during device check-ins:

1
type CommandQueue struct {
2
    store CommandStore
3
    push  APNSClient
4
}
5

6
func (q *CommandQueue) Enqueue(deviceUUID string, cmd Command) error {
7
    // Save command to store
8
    if err := q.store.Save(deviceUUID, cmd); err != nil {
9
        return err
10
    }
11

12
    // Send push notification to wake device
13
    device, err := q.store.GetDevice(deviceUUID)
14
    if err != nil {
15
        return err
16
    }
17

18
    return q.push.SendMDMPush(device.PushToken)
19
}
20

21
func (q *CommandQueue) GetNextCommand(deviceUUID string) (*Command, error) {
22
    commands, err := q.store.GetPendingCommands(deviceUUID)
23
    if err != nil || len(commands) == 0 {
24
        return nil, err
25
    }
26

27
    // Return oldest command first
28
    return &commands[0], nil
29
}

Check-in Handler#

The check-in process handles both status updates and command delivery:

1
func (s *MDMService) HandleCheckin(r *http.Request) (*CheckinResponse, error) {
2
    // Parse plist payload
3
    var checkin CheckinMessage
4
    if err := plist.NewDecoder(r.Body).Decode(&checkin); err != nil {
5
        return nil, err
6
    }
7

8
    switch checkin.MessageType {
9
    case "Authenticate":
10
        return s.handleAuthenticate(checkin)
11
    case "TokenUpdate":
12
        return s.handleTokenUpdate(checkin)
13
    case "CheckOut":
14
        return s.handleCheckOut(checkin)
15
    default:
16
        return s.handleStatusReport(checkin)
17
    }
18
}
19

20
func (s *MDMService) handleStatusReport(checkin CheckinMessage) (*CheckinResponse, error) {
21
    // Update device status
22
    device, err := s.store.GetDevice(checkin.UDID)
23
    if err != nil {
24
        return nil, err
25
    }
26

27
    device.LastCheckin = time.Now()
28
    if err := s.store.UpdateDevice(device); err != nil {
29
        return nil, err
30
    }
31

32
    // Get next command
33
    cmd, err := s.commandQueue.GetNextCommand(checkin.UDID)
34
    if err != nil || cmd == nil {
35
        return &CheckinResponse{}, nil
36
    }
37

38
    // Return command in response
39
    return &CheckinResponse{
40
        Command: cmd,
41
    }, nil
42
}

Data Flow Architecture#

Complete Flow Diagram#

1
graph TB
2
    subgraph "Apple Devices"
3
        D1[iPhone]
4
        D2[iPad]
5
        D3[Mac]
6
    end
7

8
    subgraph "MicroMDM Server"
9
        subgraph "HTTP Layer"
10
            HE[Enrollment Endpoint]
11
            HC[Check-in Endpoint]
12
            HA[Admin API]
13
        end
14

15
        subgraph "Service Layer"
16
            ES[Enrollment Service]
17
            CS[Command Service]
18
            DS[Device Service]
19
            AS[APNS Service]
20
        end
21

22
        subgraph "Storage Layer"
23
            DB[(BoltDB)]
24
        end
25
    end
26

27
    subgraph "External Services"
28
        APNS[Apple Push Service]
29
        DEP[Apple DEP/ABM]
30
    end
31

32
    subgraph "Admin Tools"
33
        CLI[mdmctl CLI]
34
        API[REST API Client]
35
    end
36

37
    D1 & D2 & D3 -->|HTTPS| HE & HC
38
    DEP -->|Enrollment| HE
39

40
    HE --> ES
41
    HC --> DS & CS
42
    HA --> CS & DS
43

44
    ES & CS & DS --> DB
45
    AS --> APNS
46
    APNS -->|Push| D1 & D2 & D3
47

48
    CLI & API -->|HTTPS| HA

Administrative Interface#

mdmctl CLI Tool#

The command-line interface provides management capabilities:

1
// Command structure
2
type Command struct {
3
    Type    string
4
    UUID    string
5
    Payload interface{}
6
}
7

8
// CLI implementation
9
func main() {
10
    app := &cli.App{
11
        Name: "mdmctl",
12
        Commands: []*cli.Command{
13
            {
14
                Name: "devices",
15
                Subcommands: []*cli.Command{
16
                    {
17
                        Name: "list",
18
                        Action: listDevices,
19
                    },
20
                    {
21
                        Name: "info",
22
                        Action: deviceInfo,
23
                    },
24
                },
25
            },
26
            {
27
                Name: "send",
28
                Action: sendCommand,
29
            },
30
        },
31
    }
32
    app.Run(os.Args)
33
}
34

35
func sendCommand(c *cli.Context) error {
36
    client := NewMDMClient(c.String("server"))
37

38
    cmd := Command{
39
        Type: c.String("type"),
40
        UUID: uuid.New().String(),
41
    }
42

43
    return client.QueueCommand(c.String("device"), cmd)
44
}

REST API Implementation#

Administrative operations via HTTP API:

1
// API routes
2
func (s *Server) setupRoutes() {
3
    r := mux.NewRouter()
4

5
    // Device management
6
    r.HandleFunc("/api/v1/devices", s.listDevices).Methods("GET")
7
    r.HandleFunc("/api/v1/devices/{uuid}", s.getDevice).Methods("GET")
8

9
    // Command management
10
    r.HandleFunc("/api/v1/commands", s.queueCommand).Methods("POST")
11
    r.HandleFunc("/api/v1/commands/{uuid}", s.getCommandStatus).Methods("GET")
12

13
    // Apply authentication middleware
14
    r.Use(s.authMiddleware)
15
}
16

17
func (s *Server) queueCommand(w http.ResponseWriter, r *http.Request) {
18
    var req CommandRequest
19
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
20
        http.Error(w, err.Error(), http.StatusBadRequest)
21
        return
22
    }
23

24
    cmd := Command{
25
        Type:      req.Type,
26
        UUID:      uuid.New().String(),
27
        Payload:   req.Payload,
28
        CreatedAt: time.Now(),
29
    }
30

31
    if err := s.CommandService.QueueCommand(req.DeviceUUID, cmd); err != nil {
32
        http.Error(w, err.Error(), http.StatusInternalServerError)
33
        return
34
    }
35

36
    json.NewEncoder(w).Encode(cmd)
37
}

Security Considerations#

TLS Configuration#

1
// Secure TLS setup
2
func configureTLS() *tls.Config {
3
    return &tls.Config{
4
        MinVersion: tls.VersionTLS12,
5
        CipherSuites: []uint16{
6
            tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
7
            tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
8
            tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
9
            tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
10
        },
11
        PreferServerCipherSuites: true,
12
    }
13
}

Authentication and Authorization#

1
// API authentication middleware
2
func (s *Server) authMiddleware(next http.Handler) http.Handler {
3
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
4
        token := r.Header.Get("Authorization")
5
        if token == "" {
6
            http.Error(w, "Unauthorized", http.StatusUnauthorized)
7
            return
8
        }
9

10
        // Validate token
11
        claims, err := s.validateToken(token)
12
        if err != nil {
13
            http.Error(w, "Invalid token", http.StatusUnauthorized)
14
            return
15
        }
16

17
        // Add claims to context
18
        ctx := context.WithValue(r.Context(), "claims", claims)
19
        next.ServeHTTP(w, r.WithContext(ctx))
20
    })
21
}

Device Trust Verification#

1
// Verify device identity during check-in
2
func (s *MDMService) verifyDevice(checkin CheckinMessage) error {
3
    // Verify certificate chain
4
    if err := s.verifyCertificateChain(checkin.Certificate); err != nil {
5
        return fmt.Errorf("invalid certificate: %w", err)
6
    }
7

8
    // Verify device identity
9
    device, err := s.store.GetDevice(checkin.UDID)
10
    if err != nil {
11
        return fmt.Errorf("unknown device: %w", err)
12
    }
13

14
    // Compare certificate fingerprint
15
    if !bytes.Equal(device.CertFingerprint, checkin.CertFingerprint()) {
16
        return fmt.Errorf("certificate mismatch")
17
    }
18

19
    return nil
20
}

Scalability and High Availability#

Database Considerations#

MicroMDM v1 uses BoltDB, which has limitations:

1
// Single-writer limitation
2
type Store struct {
3
    db    *bolt.DB
4
    mutex sync.Mutex  // Serialize writes
5
}
6

7
func (s *Store) Save(key, value []byte) error {
8
    s.mutex.Lock()
9
    defer s.mutex.Unlock()
10

11
    return s.db.Update(func(tx *bolt.Tx) error {
12
        b := tx.Bucket([]byte("data"))
13
        return b.Put(key, value)
14
    })
15
}

Scaling Strategies#

For larger deployments, consider:

Database Migration: Move to PostgreSQL or MySQL
Horizontal Scaling: Use external queue systems
Caching Layer: Redis for frequently accessed data
Load Balancing: Multiple read-only replicas

Monitoring and Observability#

Metrics Collection#

1
// Prometheus metrics
2
var (
3
    deviceCheckIns = prometheus.NewCounterVec(
4
        prometheus.CounterOpts{
5
            Name: "mdm_device_checkins_total",
6
            Help: "Total number of device check-ins",
7
        },
8
        []string{"status"},
9
    )
10

11
    commandQueue = prometheus.NewGaugeVec(
12
        prometheus.GaugeOpts{
13
            Name: "mdm_queued_commands",
14
            Help: "Number of queued commands",
15
        },
16
        []string{"device"},
17
    )
18
)

Logging Strategy#

1
// Structured logging
2
type Logger interface {
3
    Info(msg string, fields ...Field)
4
    Error(msg string, err error, fields ...Field)
5
}
6

7
func (s *MDMService) logCheckin(device *Device, duration time.Duration) {
8
    s.logger.Info("device checked in",
9
        Field("device_uuid", device.UDID),
10
        Field("device_model", device.Model),
11
        Field("duration_ms", duration.Milliseconds()),
12
    )
13
}

Integration Patterns#

DEP/ABM Integration#

1
// DEP enrollment profile assignment
2
type DEPService struct {
3
    client *dep.Client
4
}
5

6
func (s *DEPService) AssignProfile(devices []string, profileUUID string) error {
7
    return s.client.AssignProfile(dep.ProfileAssignment{
8
        Devices:     devices,
9
        ProfileUUID: profileUUID,
10
    })
11
}

External Service Integration#

1
// Webhook notifications
2
type WebhookNotifier struct {
3
    url    string
4
    client *http.Client
5
}
6

7
func (n *WebhookNotifier) NotifyEnrollment(device *Device) error {
8
    payload := map[string]interface{}{
9
        "event":  "device.enrolled",
10
        "device": device,
11
        "time":   time.Now(),
12
    }
13

14
    data, err := json.Marshal(payload)
15
    if err != nil {
16
        return err
17
    }
18

19
    resp, err := n.client.Post(n.url, "application/json", bytes.NewReader(data))
20
    if err != nil {
21
        return err
22
    }
23
    defer resp.Body.Close()
24

25
    if resp.StatusCode != http.StatusOK {
26
        return fmt.Errorf("webhook failed: %s", resp.Status)
27
    }
28

29
    return nil
30
}

Best Practices#

1. Error Handling#

1
// Comprehensive error handling
2
func (s *MDMService) processCommand(cmd Command) error {
3
    // Validate command
4
    if err := cmd.Validate(); err != nil {
5
        return fmt.Errorf("invalid command: %w", err)
6
    }
7

8
    // Process with timeout
9
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
10
    defer cancel()
11

12
    if err := s.executeCommand(ctx, cmd); err != nil {
13
        // Log error but don't fail the entire check-in
14
        s.logger.Error("command execution failed", err,
15
            Field("command_uuid", cmd.UUID),
16
            Field("command_type", cmd.Type),
17
        )
18

19
        // Update command status
20
        cmd.Status = CommandStatusFailed
21
        cmd.Error = err.Error()
22

23
        return s.store.UpdateCommand(cmd)
24
    }
25

26
    return nil
27
}

2. Configuration Management#

1
// Environment-based configuration
2
type Config struct {
3
    Server   ServerConfig
4
    Database DatabaseConfig
5
    APNS     APNSConfig
6
}
7

8
func LoadConfig() (*Config, error) {
9
    var cfg Config
10

11
    // Load from environment variables
12
    if err := envconfig.Process("mdm", &cfg); err != nil {
13
        return nil, err
14
    }
15

16
    // Validate configuration
17
    if err := cfg.Validate(); err != nil {
18
        return nil, err
19
    }
20

21
    return &cfg, nil
22
}

3. Testing Strategy#

1
// Unit test example
2
func TestCommandQueue_Enqueue(t *testing.T) {
3
    store := &mockStore{}
4
    push := &mockAPNS{}
5
    queue := &CommandQueue{
6
        store: store,
7
        push:  push,
8
    }
9

10
    cmd := Command{
11
        Type: "InstallProfile",
12
        UUID: "test-uuid",
13
    }
14

15
    err := queue.Enqueue("device-uuid", cmd)
16
    assert.NoError(t, err)
17
    assert.True(t, store.SaveCalled)
18
    assert.True(t, push.PushCalled)
19
}

Conclusion#

MicroMDM’s architecture demonstrates a clean, modular approach to building an MDM server. Its key strengths include:

Simplicity: Focused on core MDM functionality
Extensibility: Easy to build upon or integrate
Security: Proper certificate validation and secure communication
Flexibility: API-first design enables various integration patterns

While it has limitations (single-process architecture, basic storage), these are deliberate design choices that keep the codebase maintainable and the deployment simple. For organizations needing more advanced features or scale, MicroMDM provides an excellent foundation to build upon.

The architecture serves as both a production-ready MDM solution for small to medium deployments and a reference implementation for understanding the Apple MDM protocol.