FileWave Apple Profile Editor Explained

Description

ItConfiguration canof beApple desirabledevices largely relies upon Profiles.  Profiles contain Payloads: settings defined to managecontrol Apps,aspects e.gof Homethe ScreenOperating Layout,System Restrictand Appuser Usage,experience.

FileWave howhas cana Webbuilt-in Clipseditor beallowing managedthe building of Profiles.  This editor is designed to ensure Profiles only contain Payload keys that meets Apple's definitions, which in thisturn sameprovides way.peace of mind that Profiles will instal on devices when associated. 

IngredientsApple Definitions

Apple's developer pages list definitions of all payloads and as such, which keys are available within each payload; including, amongst other things, whether keys are required or optional.

Below is the link to Apple's definition for the Lock Screen Message Payload and example content:

Dict {
    PayloadDisplayName = Lock Screen Message
    PayloadScope = System
    PayloadType = Configuration
    PayloadRemovalDisallowed = false
    PayloadContent = Array {
        Dict {
            PayloadVersion = 1
            PayloadDisplayName = Lock Screen Message
            PayloadType = com.apple.shareddeviceconfiguration
            IfLostReturnToMessage = FileWave IT
            LockScreenFootnote = %custom_field.asset_tag%
            AssetTagInformation = %custom_field.asset_tag%
            PayloadEnabled = true
            PayloadIdentifier = ML1063.local.93367c30-cfe5-4c58-a2a0-83190666231b.com.apple.shareddeviceconfiguration.1b7de9ad-fc3d-4f97-9338-a26d7811f974
            PayloadUUID = 1b7de9ad-fc3d-4f97-9338-a26d7811f974
        }
    }
    ConsentText = Dict {
        default = 
    }
    PayloadIdentifier = ML1063.local.93367c30-cfe5-4c58-a2a0-83190666231b.Configuration.93367c30-cfe5-4c58-a2a0-83190666231b
    PayloadVersion = 1
    PayloadUUID = 93367c30-cfe5-4c58-a2a0-83190666231b
}

Apple's guide shows there are 3 possible keys and their value types:

• iOS 11.3+

  AssetTagInformation -- String

• Supervised devices

  IfLostReturnToMessage -- String

• Web Clip(s)

  LockScreenFootnote -- String

DirectionsFileWave Mechanics

Creating

When creating a WebProfile Clip

WebmacOS Clipwill payloadreact canto beall foundmissing inPayload Keys by applying default values

Below is an example for managing Finder:

Building Profiles in FileWave should ensure you always have correctly configured Payloads.

Custom Settings

Prior to Profile Payloads, Apple had a mechanism known as Managed Preferences (MCX).  These were either controlled using Apple Server or as with Profiles, could be installed locally on devices.

In many ways, they are essentially the same thing; an xml structured file containing configuration.  Despite Profiles taking over from MCX many years ago, MCX management still exists today in the latest macOS.  The FileWave Profile Editor is able to leverage these and they are managed with the Custom Settings Payload.

This means that not only can the OS be managed, but also provides a mechanism for controlling 3rd party Applications whose configuration is defined by this same implementation.

Custom Settings have a slightly different format than Profiles.  It is not possibly to directly import a Profile into a Custom Settings Payload

Importing Profiles

It is possible to find keys that are not defined by Apple, yet may still seem to function.  As such, it would seem on face value, reasonable to add such keys to the Payload.  Yet, FileWave only includes those that are defined by Apple, so how could this be possible?

One method would be the use of Custom Settings, however it is possible to use FileWave to Import any Profile, either from another FileWave Server, built using an Editor or from another tool.  There are though some important considerations when importing from other tools.

FileWave Definitions

As noted above, FileWave definitions are built from Apple's definitions.  Additionally, FileWave will always configure ALL key/value pairs to default if not already defined.  However, the flip side of this is that FileWave will also REMOVE any keys that are not part of the definition.

Importing Undefined Keys

If the Profile being imported contains keys that are not part of the definition, the Profile should never be altered or saved within FileWave.  The Profile, if opened, will not display unknown keys and if the payload only contains unknown definitions, it will appear as if it doesn't even exist within the Profile.

Dict {
    PayloadVersion = 1
    PayloadDisplayName = Xcreds Azure
    PayloadScope = System
    PayloadType = Configuration
    PayloadRemovalDisallowed = false
    PayloadContent = Array {
        Dict {
            PayloadVersion = 1
            PayloadDisplayName = XCreds
            PayloadUUID = 216961FC-A8FE-4E1B-8253-747D3A4A184B
            PayloadType = com.twocanoes.xcreds
            discoveryURL = https://login.microsoftonline.com/xxx/.well-known/openid-configuration
            loginWindowBackgroundImageURL = file:///Users/Shared/random.heic
            scopes = profile openid offline_access
            PayloadIdentifier = ml1063.lan.4301329C-0440-4BB7-B8E8-B498DDE2448C.com.twocanoes.xcreds.216961FC-A8FE-4E1B-8253-747D3A4A184B
            clientID = xxx
            PayloadOrganization = 
        }
    }
    ConsentText = Dict {
        default = 
    }
    PayloadIdentifier = ml1063.lan.e558df3f-4f17-4d48-919e-56c2fc8636d3.Configuration.e558df3f-4f17-4d48-919e-56c2fc8636d3
    PayloadOrganization = FileWave
    PayloadUUID = e558df3f-4f17-4d48-919e-56c2fc8636d3
}

Importing Existing Profiles

Each Profile has a Unique Identifier.  If at the time of importing, a Profile with the same Identifier already exists within FileWave, a prompt will be shown, asking if this should be newly created or if it should overwrite the current Profile.

This action will, as with all save actions with Profiles, causes all missing, but defined keys, to be added with default values, whilst all undefined keys will be removed.

macOS GUI

The macOS GUI does not always necessarily display the setting that is defined.  In some instances, it may even look like it allows the user to alter the value, however, to the user it will appear not to work, since in reality it is managed.

Undefined Keys

Looking into plist files or binaries of applications, additional, undefined keys can sometimes be found.  What's more, it may be createdpossible by:

use
1. Namingthese keys, either within an imported Payload or Custom Settings, with the Profiledesired effect.  However, since they are undefined, it cannot be guaranteed that these settings will work on all versions of macOS.
   Example: Apple Undefined Key

   Looking at the macOS Restrictions Payload, one of the services available for control is AirDrop:

   

   allowAirDrop -- boolean If false, the system disables AirDrop. Requires a supervised device. Available in iOS 7 and later, and macOS 10.13 and later. Default: true

   When using AirDrop there are options for discovery:

   • No One
   • LabelContacts Only (Requires iCloud login)
   • Everyone

   Looking at a user's plist file, the Webkey Clipdefining (nametheir displayedsetting onmay be seen:

   % defaults read ~/Library/Preferences/com.apple.sharingd.plist DiscoverableMode
   Off

   Taking that info a Custom Settings Payload:

   

   Applying to the device)

same
2. Adddevice whose AirDrop discovery is set as 'Off':

    

   

   For the URL

user,
3. Addit is configured as 'Off', yet the Payload is defining this to be 'Everyone' and this is reflected in the user experience.

   Remember, this is an icon.undefined Ankey iconand may not function as desired with all macOS versions.

   Missing Keys

   At times, Apple add/remove keys from Payload definitions.  If a key is considered to be missing from FileWave, but is clearly defined in Apple's developer documentation, then consider creating a ticket through FileWave Support.

   Conflicting Keys

   It would be worth noting in this topic, conflicting Payloads.  If two payloads were overlapping in content, but with different settings, what should be the outcome.

   As per Apple's documentation: https://support.apple.com/en-gb/guide/deployment/dep9a318a393/web

   

   Conclusion

   FileWave Profile Editor protects against malformed Payloads, ensuring they meet Apple's requirements.

   If a key is required that is not defined by Apple, consider using a requirement,Custom butSettings willPayload maketo deliver that key/value pair.

   If importing an undefined key within a non-Custom Settings Payload, do not edit the Profile to ensure it easierremains for users of devices to identify the Web Clip.

URL Schemeuntouched.

The URL must contain an appropriate scheme, e.g http:// or https://

Creating a Home Screen Layout

Home Screen Layout payload can also be found in the FileWave Profile Editor.  

When managing items in Home Screen Layout, the Bundle ID is usually referenced, however all Web Clips have the same bundle ID.  Therefore, when including a Web Clip in a Home Screen Layout, the URL from the Web Clip should be copied to this payload to match exactly.  Again, the URL must contain the same appropriate scheme, e.g http:// or https://

To move the Web Clip version of the App Portal please view our KB on this topic: Moving the App Portal Web Clip using the Home Screen Layout Payload

App Restrictions

Where Application Restrictions are applied, Web Clips will need to be allowed if required.  This involves referencing the Bundle ID: com.apple.webapp

Bundle ID
Since the Bundle ID is the same for all Web Clips, restrictions will either allow or deny all Web Clips. Associations should be used for granular control.

User Created Web Clips
When App Restrictions are in place which deny 'Allow Removing Apps', users may create their own Web Clips, but will not be able to remove them.