gsuitemdm

README

gsuitemdm

gsuitemdm is a Go package that eases the management of iOS or Android mobile devices in G Suite domains that use G Suite MDM to secure their mobile devices.

gsuitemdm provides:

• Multiple, easy to use, secure mobile device management APIs deployed as cloud functions to help you quickly manage many mobile devices
• A command line tool (mdmtool) allowing for easy command line mobile device management
• Mobile device & user data stored in Google Datastore
• Configuration, keys & credentials stored securely as secrets in Google Secret Manager

Basically, gsuitemdm gives you:

• A much more convenient API interface to the G Suite Admin SDK
• Ability to script MDM operations or use a CLI tool instead of the Admin Console
• Handy 'quality of life' bits & pieces such as a phone directory API and Slack /phone command

Additional Features

• Securely uses GCP service accounts, GCP IAM roles and G Suite domain-wide delegation authority
• Supports multiple G Suite domains with easy (and shared!) configuration across all components
  • G Suite domains do not need to be under the same G Suite account
• Quickly and easily perform actions (Approve/Block/Delete/Wipe/Search for) on MDM-protected devices across multiple G Suite domains
• Generate an auto-updating Google Sheet so your ops team can track all mobile devices across multiple G Suite domains
• Structured application logs in Stackdriver

Use-Cases

• G Suite administrators managing multiple mobile devices in multiple G Suite domains spread across multiple G Suite organizational accounts
• Programmatically perform administrative actions on G Suite MDM-protected mobile devices
  • Generate an on-call list using the directory API
• Quickly and easily approve/block/wipe mobile devices in the command line without logging into the G Suite Admin Console

Status

• In production
• Ready for public use
• Docs: 95%

Configuration

All configuration data, API keys and service account domain credentials are stored as secrets in Google Secret Manager. Learn more about gsuitemdm configuration or gsuitemdm secrets.

Read all about configuration in the gsuitemdm setup docs.

Pre-Requisites

• 1+ G Suite domain(s) using G Suite MDM to manage iOS/Android mobile devices
• GCP project with billing setup

Brief Setup Notes

Full setup documenation is available here.

TODO

Documentation

Index

• func GetIP(r *http.Request) string
• func GetSecret(ctx context.Context, sid string) (string, error)
• func TimeTrack(start time.Time)
• type ActionRequest
• type AllDirectoryData
  • func (s AllDirectoryData) Len() int
  • func (s AllDirectoryData) Less(i, j int) bool
  • func (s AllDirectoryData) Swap(i, j int)
• type DatastoreMobileDevice
• type DatastoreMobileDevices
  • func (s DatastoreMobileDevices) Len() int
  • func (s DatastoreMobileDevices) Less(i, j int) bool
  • func (s DatastoreMobileDevices) Swap(i, j int)
• type DirectoryData
• type DomainConf
• type Domains
• type GSuiteMDMConfig
• type GSuiteMDMService
  • func New(ctx context.Context, config string) (*GSuiteMDMService, error)
  • func (mdms *GSuiteMDMService) AuthenticateWithDomain(customerid, domain, scope string) (*admin.Service, error)
  • func (mdms *GSuiteMDMService) BuildFullDomainList() []string
  • func (mdms *GSuiteMDMService) ConvertDatastoreDevicetoSDK(device *DatastoreMobileDevice) *admin.MobileDevice
  • func (mdms *GSuiteMDMService) ConvertSDKDeviceToDatastore(device *admin.MobileDevice) (*DatastoreMobileDevice, error)
  • func (mdms *GSuiteMDMService) GetAdminSDKDevices(domain string) error
  • func (mdms *GSuiteMDMService) GetDatastoreData() error
  • func (mdms *GSuiteMDMService) GetDomainCustomerID(domain string) (string, error)
  • func (mdms *GSuiteMDMService) GetSheetData() error
  • func (mdms *GSuiteMDMService) HttpClient(creds string) (*http.Client, error)
  • func (mdms *GSuiteMDMService) IsDomainConfigured(domain string) bool
  • func (mdms *GSuiteMDMService) MergeDatastoreAndSheetData() []DatastoreMobileDevice
  • func (mdms *GSuiteMDMService) SearchDatastoreForDevice(device *admin.MobileDevice) (*DatastoreMobileDevice, error)
  • func (mdms *GSuiteMDMService) SearchSheetForDevice(device *admin.MobileDevice) (DatastoreMobileDevice, error)
  • func (mdms *GSuiteMDMService) UpdateDatastoreDevice(device *admin.MobileDevice) error
  • func (mdms *GSuiteMDMService) UpdateSheet(mergeddata []DatastoreMobileDevice) error
• type SearchRequest
• type SlackRequest
• type UpdateRequest

Functions

func GetIP

func GetIP(r *http.Request) string

Helper function to get a remote IP from an http.Request

func GetSecret

func GetSecret(ctx context.Context, sid string) (string, error)

Get a secret from Secret Manager

func TimeTrack

func TimeTrack(start time.Time)

Helper func to track how long a func takes to execute (found on StackExchange I think!)

Types

type ActionRequest

type ActionRequest struct {
	Action  string `json:"action"`
	Confirm bool   `json:"confirm"`
	Debug   bool   `json:"debug"`
	Domain  string `json:"domain"`
	IMEI    string `json:"imei"`
	Key     string `json:"key"`
	SN      string `json:"sn"`
}

Action (Approve, Block, Delete, Wipe)

type AllDirectoryData

type AllDirectoryData struct {
	Data []DirectoryData
}

Multiple directory entries

func (AllDirectoryData) Len

func (s AllDirectoryData) Len() int

Sort funcs for directory data

func (AllDirectoryData) Less

func (s AllDirectoryData) Less(i, j int) bool

func (AllDirectoryData) Swap

func (s AllDirectoryData) Swap(i, j int)

type DatastoreMobileDevice

type DatastoreMobileDevice struct {
	Color             string // Color of device
	CompromisedStatus string // Is the device compromised?
	Domain            string // G Suite domain
	DeveloperMode     bool   // Is the device in developer mode?
	Email             string // Email address of device owner
	EncryptionStatus  string // Is the device encrypted?
	IMEI              string // IMEI
	Model             string // Model
	Name              string // Full Name of device owner
	Notes             string // Notes
	OS                string // Operating System
	OSBuild           string // OS Build
	PasswordStatus    string // Password status
	PhoneNumber       string // Telephone number of the device
	RAM               string // RAM in GB
	ResourceId        string // MDM ID for device
	SN                string // Serial number
	Status            string // Device status
	SyncFirst         string // First sync device time
	SyncLast          string // Most recent device sync time
	Type              string // Type of G Suite sync
	UnknownSources    bool   // Are unknown sources of apps allowed on the device?
	USBADB            bool   // Is ADB/USB debugging enabled?
	WifiMac           string // Wifi MAC address
}

A single mobile device type, stored in Datastore. Based on https://developers.google.com/admin-sdk/directory/v1/reference/mobiledevices#resource

type DatastoreMobileDevices

type DatastoreMobileDevices struct {
	Mobiledevices []DatastoreMobileDevice
}

Multiple mobile devices

func (DatastoreMobileDevices) Len

func (s DatastoreMobileDevices) Len() int

Sort funcs for devices

func (DatastoreMobileDevices) Less

func (s DatastoreMobileDevices) Less(i, j int) bool

func (DatastoreMobileDevices) Swap

func (s DatastoreMobileDevices) Swap(i, j int)

type DirectoryData

type DirectoryData struct {
	Name        string `json:"name"`
	Email       string `json:"email"`
	PhoneNumber string `json:"phonenumber"`
}

Individual directory entry

type DomainConf

type DomainConf struct {
	// Administrative User on this G Suite domain you want the API calls to "run as".
	// This will need to be a user/email address that has Administrator/Super Administrator role
	// in the specific G Suite domain.
	AdminUser string `json:"adminuser"`

	// Immutable Customer ID of G Suite domain
	CustomerID string `json:"companyid"`

	// FQDN of G Suite domain
	DomainName string `json:"domainname"`

	// Credentials Secret for this G Suite domain
	SecretID string `json:"secretid"`
}

Specific G Suite domain configuration

type Domains

type Domains []DomainConf

Struct used for configured domains. Just a slice of the domain-specific configuration struct

type GSuiteMDMConfig

type GSuiteMDMConfig struct {
	// Required G Suite Admin SDK scope to perform ACTION operations (delete, wipe, block, etc).
	// See SearchScope for more details
	ActionScope string `json:"actionscope"`

	// Default sort order of devices returned by the Admin API query parameter: orderBy.
	// Refer to https://developers.google.com/admin-sdk/directory/v1/reference/mobiledevices/list
	APIQueryOrderBy string `json:"apiqueryorderby"`

	// Default sort order of devices returned by Cloud Datastore
	DatastoreQueryOrderBy string `json:"datastorequeryorderby"`

	// Global debug mode?
	Debug bool `json:"globaldebug"`

	// Datastore namekey
	DSNamekey string `json:"dsnamekey"`

	// Project ID of the GCP project
	ProjectID string `json:"projectid"`

	// What type of Remote Wipe will we use for the "wipe" command? Possible values are:
	// Refer to https://developers.google.com/admin-sdk/directory/v1/reference/mobiledevices/action
	RemoteWipeType string `json:"remotewipetype"`

	// Required G Suite Admin API scope to perform SEARCH operations. Since we are using the
	// Mobiledevices: list method of the G Suite Admin API, refer to
	// https://developers.google.com/admin-sdk/directory/v1/reference/mobiledevices/list
	//
	// Default value for this should be: "https://www.googleapis.com/auth/admin.directory.device.mobile.readonly"
	// and there should likely be no good reason to change it.
	SearchScope string `json:"searchscope"`

	// Default type of search.
	// This refers to the STATUS of the mobile device as seen in the G Suite Admin console.
	// Possible values are:
	//		All
	//		Approved
	//		Pending Approval
	//		Blocked
	//		Account Wiped
	//		Device Wiped
	//		Account Wiping
	//		Device Wiping
	//
	SearchType string `json:"searchtype"`

	// GCP Secret Manager ID of the credentials with necessary permissions to write to the Google Sheet
	SheetCredsID string `json:"sheetcredsid"`

	// ID of the google spreadsheet to update
	SheetID string `json:"sheetid"`

	// Required Sheets API scope to update the Google Sheet
	SheetScope string `json:"sheetscope"`

	// Who to write the spreadsheet as
	SheetWho string `json:"sheetwho"`

	// Time Zone
	TimeZone string `json:"timezone"`

	// Version of gsuitemdm
	Version string `json:"version"`

	// G Suite domains that mdmtool knows about.
	Domains Domains `json:"domains"`
}

G Suite MDM Service config struct type

type GSuiteMDMService

type GSuiteMDMService struct {
	C             GSuiteMDMConfig         // Main configuration
	Ctx           context.Context         // Context
	DatastoreData []DatastoreMobileDevice // Datastore mobile device data
	SDKData       *admin.MobileDevices    // Admin SDK mobile device data
	SheetData     []DatastoreMobileDevice // Google Sheet mobile device data
}

G Suite MDM Service main struct type

func New

func New(ctx context.Context, config string) (*GSuiteMDMService, error)

Create a new G Suite MDM Service

func (*GSuiteMDMService) AuthenticateWithDomain

func (mdms *GSuiteMDMService) AuthenticateWithDomain(customerid, domain, scope string) (*admin.Service, error)

Authenticate with a domain, get an admin.Service

func (*GSuiteMDMService) BuildFullDomainList

func (mdms *GSuiteMDMService) BuildFullDomainList() []string

Build a list of all configured domains

func (*GSuiteMDMService) ConvertDatastoreDevicetoSDK

func (mdms *GSuiteMDMService) ConvertDatastoreDevicetoSDK(device *DatastoreMobileDevice) *admin.MobileDevice

Convert a Datastore mobile device object to an Admin SDK mobile device object

func (*GSuiteMDMService) ConvertSDKDeviceToDatastore

func (mdms *GSuiteMDMService) ConvertSDKDeviceToDatastore(device *admin.MobileDevice) (*DatastoreMobileDevice, error)

Convert an Admin SDK mobile device object to a Datastore mobile device object

func (*GSuiteMDMService) GetAdminSDKDevices

func (mdms *GSuiteMDMService) GetAdminSDKDevices(domain string) error

Get the list of devices for a G Suite domain from the Admin SDK

func (*GSuiteMDMService) GetDatastoreData

func (mdms *GSuiteMDMService) GetDatastoreData() error

Read all mobile device data from Google Cloud Datastore

func (*GSuiteMDMService) GetDomainCustomerID

func (mdms *GSuiteMDMService) GetDomainCustomerID(domain string) (string, error)

Get a CustomerID for a given domain

func (*GSuiteMDMService) GetSheetData

func (mdms *GSuiteMDMService) GetSheetData() error

Read all mobile device data from the Google Sheet

func (*GSuiteMDMService) HttpClient

func (mdms *GSuiteMDMService) HttpClient(creds string) (*http.Client, error)

Create an authenticated http(s) client, used to read/write the Google Sheet

func (*GSuiteMDMService) IsDomainConfigured

func (mdms *GSuiteMDMService) IsDomainConfigured(domain string) bool

Check to see if a domain is configured

func (*GSuiteMDMService) MergeDatastoreAndSheetData

func (mdms *GSuiteMDMService) MergeDatastoreAndSheetData() []DatastoreMobileDevice

Merge Datastore and Sheet data

func (*GSuiteMDMService) SearchDatastoreForDevice

func (mdms *GSuiteMDMService) SearchDatastoreForDevice(device *admin.MobileDevice) (*DatastoreMobileDevice, error)

Search for a matching device in Google Datastore using a specific Admin SDK mobile device object

func (*GSuiteMDMService) SearchSheetForDevice

func (mdms *GSuiteMDMService) SearchSheetForDevice(device *admin.MobileDevice) (DatastoreMobileDevice, error)

Search the Google Sheet for a specific device

func (*GSuiteMDMService) UpdateDatastoreDevice

func (mdms *GSuiteMDMService) UpdateDatastoreDevice(device *admin.MobileDevice) error

Update a device in Google Cloud Datastore

func (*GSuiteMDMService) UpdateSheet

func (mdms *GSuiteMDMService) UpdateSheet(mergeddata []DatastoreMobileDevice) error

Update the Google Sheet

type SearchRequest

type SearchRequest struct {
	Debug        bool   `json:"debug"`
	Domain       string `json:"domain"`
	ReturnFormat string `json:"format"`
	Key          string `json:"key"`
	QType        string `json:"qtype"`
	Q            string `json:"q"`
	SlackToken   string `json:"slacktoken"`
}

Search

type SlackRequest

type SlackRequest struct {
	Token          string `json:"token"`
	TeamID         string `json:"team_id"`
	TeamDomain     string `json:"team_domain"`
	EnterpriseID   string `json:"enterprise_id,omitempty"`
	EnterpriseName string `json:"enterprise_name,omitempty"`
	ChannelID      string `json:"channel_id"`
	ChannelName    string `json:"channel_name"`
	UserID         string `json:"user_id"`
	UserName       string `json:"user_name"`
	Command        string `json:"command"`
	Text           string `json:"text"`
	ResponseURL    string `json:"response_url"`
	TriggerID      string `json:"trigger_id"`
}

Slack Search Request (nicked from https://github.com/nlopes/slack)

type UpdateRequest

type UpdateRequest struct {
	Debug bool   `json:"debug"`
	Key   string `json:"key"`
}

Update