Provision a Mac for a new employee

Description
Prepare the provisioning
Provision the new machine

Description

Provision a machine with the company defined standards for settings and software with different flavours for each department or employee role.

Configure a provisioning package on the system administrator and distribute it to the machines that you have to provision.

Prepare a provisioning package configured with:

A base profile with standard settings that will apply to all the machine.
and role profiles with settings dedicated to the department or employee role.
configuration files for each machine
Filevault2 encryption certificates
Antivirus installer (only Sophos Endpoint is supported at the moment)

Profiles example:

base profile:

Common admin username and profile picture.
Corporate FileVault2 recovery key certificate or keychain file.
Company unified desktop picture.
Default applications set: Slack, Skype, LastPass, Jira Client, Google Drive File Stream, Chrome, Firefox, Zoom...

admin role:

Additional applications set: Microsoft Office, Citrix...

developer role:

Additional applications set: Atom, Visual Studio, iTerm2, Docker Desktop, MacVim, Tunnelblick, VirtualBox ...
Homebrew packages: awscli, lastpass-cli, curl ...
System settings: show all extensions, show hidden files, show ~/Library folder ...

creative role:

Additional applications set: Adobe Creative Suite ...

Prepare the provisioning

Install Splinter in the System Administrator computer

follow the installation instructions.

Configure your custom profiles

In ./splinter/profiles/ you will find two initial example profiles:

base-example
example

Create your base common profile

This profile is meant to contain common settings for all your computers and employees.

Create as many role profiles as you need.

You can create a role profile for each department of your company or for any specific employee role

 for example:
 
 * administration
 * human-resources
 * marketing-team
 * board-memeber
 * developer
 * devops
 * fe-developer
 * qa-team

You can modify or copy the base-example and example profiles provided with the initial splinter project folder to create your own profiles.

Enable and configure the desired provisioning modules

In your base profile include the full set of configuration files with the full set of configuration attributes set the the most common desired values.
In your role profiles include only the configuration files and attributes meant to override the base profile values according to specific needs of an employee role or machine use.

Any role profile setting will be merged with the settings defined in the base profiles(s). The values defined in a role profile will have priority over the ones defined in the base profile

Toggle the modules you want to use for the provisioning in <custom_profile>/modules.yml

Each module has its own configuration file with its own attributes and toggles that you can customise.

     examples of profiles
    
    profiles/
    │
    ├── base (common profile)
    │   │
    │   ├── current_user.yml
    │   ├── dotfiles.yml
    │   ├── extra_packages.yml
    │   ├── filevault_option.yml
    │   ├── homebrew.yml
    │   ├── mac_app_store.yml
    │   ├── macos_apps_list.yml
    │   ├── modules.yml
    │   ├── new_user.yml
    │   ├── post_provision.yml
    │   ├── sophos-endpoint.yml
    │   ├── ssh_config.yml
    │   └── system_config.yml
    │
    ├── marketing (role profile)
    │   │
    │   ├── macos_apps_list.yml
    │   ├── modules.yml
    │   └── system_config.yml
    │
    └── developer (role profile)
        │
        ├── homebrew.yml
        ├── modules.yml
        ├── new_user.yml
        ├── ssh_config.yml
        └── system_config.yml

It is possible to pre-install a large variety of Mac applications of common user specifying them as Homebrew Casks list:

     file <custom-profile>/homebrew.yml
    
    homebrew_cask_apps:
        - atom
        - docker
        - firefox
        - github
        - google-backup-and-sync
        - google-chrome
        - google-drive-file-stream
        - iterm2
        - ...

For profiles set up for developers in general, it can be convenient to specify a list of default of homebrew packages to pre-install common Unix tools used within the company.

     file <custom-profile>/homebrew.yml
    
    homebrew_installed_packages:
        - autoconf
        - bash-completion
        - gnu-tar
        - awscli
        - cmake
        - composer
        - ...

Upload your custom profiles to your Github account

This is optional.

Once you have created your profiles you can push your profiles to a Github repository so that they can be maintained and reused in time and across offices.

This is particularly useful if you are delegating the provisioning of a new machine to people in different offices and still keep a cross-company standard

Uploading profiles to a Github repository is not mandatory but is recommended

If you name the profiles repository splinter-profiles it won't be necessary to specify the custom_profiles_repo value in the splinter's config file

Create your custom configuration files

This is optional.

You can create any number fo splinter configuration file in (.cfg INI format) one for each machine that you want to configure and they can be named as you like:

The config file contains the only settings related to the new user (if any) and the machine's name.
All the attributes set in the config file can be also specified via splinter command-line parameters
If you have a config file named splinter.cfg will be loaded automatically.
If you have a configuration file but you do not want to load it automatically DO NOT NAME IT splinter.cfg
You can choose not to use any configuration file and only run with command-line parameters.
Config file and command-line parameters are NOT MUTUALLY EXCLUSIVE:

you can use a configuration file and specify some parameters via command line to complement or override the former

Command-line parameters have priority over the attributes specified in the config file.

   file: slinter.cfg
  verbose="yes"
  
  custom_profiles_repo_account="mycompany"
  
  custom_profiles_repo="splinter-profiles"
  
  base_profile="common-profile"
  
  role_profile="developer-profile"
  
  new_user_username="newemployee"
  
  new_user_fullname="New Employee"
  
  new_user_password_cleartext="password"

  computer_name="New-Mac-For-New-Employee"

See the content of example-splinter.cfg for a detailed description of the parameters.

Equivalent command-line parameters

    ./splinter -v provision -u 'newemployee' -f 'New Employee' -p 'password' -b 'common-profile' -r 'developer-profile' -a 'mycompany' -g 'splinter-profiles' -h 'New-Mac-For-New-Employee'

Note: For the computer name to applied, make sure to set:

    # file: <base_profile>/modules.yml

    configure_system: yes

Enable Filevalut2 encryption

Enable this Filevalut2 in your base profile:

     file: <base_profile>/modules.yml
    
    `configure_filevault: yes`

If you want to use Filevault2 you have 2 options:

Personal Recover key
Institutional Recovery Key (recommended)

Personal Recovery Key

The recovery key will be automatically generated after Filevalut2 is enabled and stored by default in the new user's Desktop in form of a cleartext file that the user will have to safely store somewhere out of the machine itself and communicate it to the system administrators.

Even when using an institutional recovery key a personal recovery key will be created by default so that the user that forgot its password can decrypt its computer drive without the need to have the company certificate master key password.

If you do NOT want a personal recovery key to be generated, set:

     file: <base_profile>/filevault.yml
    
    `filevault_norecoverykey: yes`

Institutional Recovery Key

Enable this setting in your base profile:

     file: <base_profile>/filevault.yml
    
    `filevault_certificate: yes`

Using an institutional recovery key is the recommended option for a company because:

Using a shared encryption certificate allows the system administrators to recover the content of the machine even if the employee has forgotten his password
The encryption certificate can be programmatically replaced periodically or in case of a security breach.

You can set up an institutional recovery key in two ways:

Deploy a Keychain recovery key: see Apple documentation
Deploy a DER certificate that will be added to Keychain a recovery key generated on-the-fly

You can generate one of the above in a few different ways, and if you already have one of those you can use them with Splinter.

DO NOT TO INCLUDE the master key with the keychain file when provisioning a new machine.

If you are using your pre-existing DER certificate make sure to update link it correctly:

     file: <base_profile>/filevault.yml
    
    `filevault_certificate_file: 'files/certificates/FileVaultMaster.der.cer'`

Generate a new encryption certificate

Splinter has a built-in option to make the generation of both a Keychain file and a DER certificate to make the process very easy if you are not an expert in certificates.

    ./splinter create filevault-recovery-key

The above command will ask you to set a master password and will create these 3 files in (splinter project)/files/certificates :

FileVaultMaster-keychain-password: the master key password you have been asked during the cert creation)
FileVaultMaster.der.cer: the DER certificate that will be used for the Filevault2 encryption
FileVaultMaster.keychain: contains both the DER certificate and the master key password

Leave the generated DER certificate in this directory and will be used for the encryption of the provisioned machine (the base-example profile is already set to use this file).

Store the keychain file and the master key safely and remove it from the project folder, so that you can use it to decrypt a computer where you do not have any user password to decrypt the filesystem.

To decrypt such computer you will have to follow a specific Apple procedure

Add Sophos Anti-Virus Endpoint installer

If you have a company subscription for Sophos Anti-Virus Endpoint

Download the macOS Sophos endpoint installer from your Sophos Cloud account
Save the installer archive as
```
 (splinter project)/files/sophos_endpoint/SophosInstaller.zip
```
make sure that the name and path is exactly the above

Enable Sophos configuration on your 'base' profile:

      file: <base_profile>/modules.yml
     
     configure_sophos_endpoint:      no

When creating the provisioning package the installer will be included in it.

The SophosInstaller.zip should NOT be posted on a public link because it contains your company-specific identified that will connect the provisioned machine to your Sophos account.

Add custom profile and desktop background pictures

Profile Pictures

You can add a custom and distinct company profile pictures (i.e. the company logo) for both the new employee account and the 'admin' account from which you are running the provisioning (referred to as current_user).

Load those files in .jpg or .png formats into:

 `(splinter project)/files/profile_pictures/`

Specify their path/name in the configuration files:

  file: <base_profile>/current_user.yml
 
 current_user_profile_picture: "files/profile_pictures/company_logo.png"
 

  file: <base_profile>/new_user.yml
 
 new_user_profile_picture_path: 'files/profile_pictures/department_logo.png'

Desktop picture

You can also add a custom company desktop background image

Load the background image files in .jpg or .png formats into:
```
 `(splinter project)/files/`
```

Specify its path/name in the configuration files:

  file: <base_profile>/system_preferences.yml
 
 DesktopScreenSaver_Enabled:  yes
 DesktopScreenSaver_BackGroundImage: "files/desktop_pictures/custom_desktop_image.jpg"  Background iamge

Create the provisioning package

Now that you have added all your custom settings and files to the project folder you can create a provisioning package that you can reuse when needed.

Make sure to remove the keychain file and the master key (and any other sensitive information) from the project folder before packaging it.

    ./splinter create package

will create (splinter project)/SplinterProvision.dmg with a rough size of 600MB

Store the provisioning package in a company shared storage where other colleagues could also access it, for example, Google Drive

Provision the new machine

When provisioning a new employee machine it is recommended to run the provision with an 'admin' account distinct from the new employee's account you will create.

New machine preparation steps

Login in the new machine as the company admin account, the first account you create in the machine, not the new employee user account.
Add the Terminal application (located in /Applications/Utilities/) to the "Full Disk Access" policy

a. Open System Preferences -> Security & Privacy -> Privacy -> Full Disk Access

b. Authenticate to unlock the list of allowed applications

c. Add Terminal to the list of allowed apps, save and close.
Connect to a WiFi network.
Transfer a copy of the SplinterProvision.dmg provisioning archive to the new machine:

option 1: transfer the directory using Share->AirDrop (you need to make the new machine discoverable by everyone).
option 2: transfer with a USB stick.

Mount the provisioning archive

New machine provisioning

from the Terminal applicatione access the mounted diskimage

cd /Volumes/SplinterProvision

run splinter:

If you are using splinter.cfg
```
  ./splinter provision
```
If you are using a custom-name configuration file:
```
  ./splinter provision -c custom-name.cfg
```

If you are NOT using a configuration file:

  ./splinter provision -u newemployee -f 'Full Name' -p 'cleartextnewuserpass' -b base-profile -r role-profile -h 'Computer-Name'

Splinter will request you to enter the current user account (to be used as sudo password throughout the whole process).

The rest of the provisioning can be mostly unattended but a few applications might require some system privacy authorisation, for instance vagrant and if you do not allow that in time and the installation fail you can re-run the brew installation command or re-run splinter

During the deployment a few applications might request authorisation to run so do not leave the computer completely unattended.

Post Provisioning manual Steps

You do not need to login into the new employee account because all settings have been set by Splinter, included muting all the Setup Assistant first-login panels.

Authorise "Virtualbox" kext if you installed it via homebrew or macos_apps list

This applies only if you have installed Oracle's Virtualbox

Go to System Preferences -> Security & Privacy -> General
Click the Allow button next to the request of authorisation for "Oracole America, Inc." software
re-run VirtualBox installation, this time it should succeed without errors

brew cask reinstall VirtualBox