Mobile Device Management (MDM)
- Introduction
- Configurable Settings
- AppConfig XML Schema
- Example: Deployment With MobileIron
- Example: Deployment With Jamf Pro
- References
Introduction
With the introduction of MDM (Mobile Device Management) by Apple for its devices, a MDM server can securely push a configuration to the iOS device, respectively recieve feedback from the device. ownCloud supports MDM for it’s iOS-App.
The configuration is basically a key-value dictionary provided as a .plist
file. The app can access this configuration from the server in read-only mode using the NSUserDefaults
class by reading a configuration dictionary under the key com.apple.configuration.managed
. The app can also observe a system notification via class NSUserDefaultsDidChangeNotification
to get notified about configuration changes. For feedback, the app writes a dictionary with feedback information into user defaults under the com.apple.feedback.managed
key.
Configurable Settings
The ownCloud iOS App implements a mechanism internally called Class Settings which can be derived from different sources:
-
Environment variables which e.g. can be set in Xcode for testing. In this case setting keys have to be prepended with oc: prefix.
-
User preferences accessed by the very same API but stored under org.owncloud.user-settings key.
-
Settings dictionary pushed by an MDM Server and accessible using
NSUserDefaults
API under the key com.apple.configuration.managed. -
Default settings defined directly in the app sourcecode.
-
Branding.plist which is the part of the Xcode project under ownCloud/Resources/Theming. It allows to override class settings by specifying them in the
Configuration
section
There is also an order in which these settings take precedence, where environment variables have highest priority. When settings are accessed, they are merged and higher priority value for the same key overwrites lower priority ones.
Some settings are accessed only once at runtime and the read value is cached, so that new setting to take effect may a require an app to be terminated and restarted.
App Basic Configurations
There are few settings allowing to mark an app installation as BETA and e.g. to supress UIKit animation and review prompt.
Key | Type | Default | Description | Status |
---|---|---|---|---|
app.app-store-link |
string |
URL for the app in the App Store. |
advanced |
|
app.enable-review-prompt |
bool |
|
Enable/disable review prompt. |
advanced |
app.recommend-to-friend-enabled |
bool |
|
Enables/disables the recommend to a friend entry in the settings. |
advanced |
app.enable-ui-animations |
bool |
|
Enable/disable UI animations. |
debugOnly |
app.is-beta-build |
bool |
|
Controls if the app is built for beta or release purposes. |
debugOnly |
app.show-beta-warning |
bool |
|
Controls whether a warning should be shown on the first run of a beta version. |
debugOnly |
Extensions / Actions
The ownCloud iOS app uses internally a plug-in like mechanism called extensions. Extensions are used to implement menu actions mostly found under "+" menu allowing to add new items (Upload media, take photo etc.) or in more menu (Copy, Move, Open in etc.). Using below settings actions / extensions can be disabled. Extensions are enabled by default, however this might depend on licensing requirements of a particular extension.
Key | Type | Default | Description | Status | ||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
action.allowed |
stringArray |
|
List of all allowed actions. If provided, actions not listed here are not allowed.
|
advanced |
||||||||||||||||||||||||||||||||||||||||||||||||||
action.disallowed |
stringArray |
|
List of all disallowed actions. If provided, actions not listed here are allowed.
|
advanced |
(*) These extensions might require additional license (in-app purchase, enterprise version).
Display Settings
To customize file list UI behevior, following settings are available:
Key | Type | Default | Description | Status |
---|---|---|---|---|
display.prevent-dragging-files |
bool |
|
Controls whether drag and drop should be prevented for items inside the app. |
advanced |
display.show-hidden-files |
bool |
|
Controls whether hidden files (i.e. files starting with |
advanced |
display.sort-folders-first |
bool |
|
Controls whether folders are shown at the top. |
advanced |
Passcode Enforcement
If your organization policies require users to use a passcode as an additional security barrier for managed apps, the below setting will allow to enforce this requirement.
Key | Type | Default | Description | Status |
---|---|---|---|---|
passcode.enforced |
bool |
|
Controls wether the user MUST establish a passcode upon app installation. |
advanced |
passcode.lockDelay |
int |
Number of seconds before the lock snaps and the passcode is requested again. |
advanced |
|
passcode.maximumPasscodeDigits |
int |
|
Controls how many passcode digits are maximal possible for passcode lock. |
advanced |
passcode.requiredPasscodeDigits |
int |
|
Controls how many passcode digits are at least required for passcode lock. |
advanced |
passcode.use-biometrical-unlock |
bool |
|
Controls wether the biometrical unlock will be enabled automatically. |
advanced |
Bookmark
Below settings allow to configure the app to use a certain server URL and even bind it to this URL only by setting the default non-editable.
Key | Type | Default | Description | Status | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
bookmark.default-url |
string |
The default URL for the creation of new bookmarks. |
supported |
|||||||||
bookmark.prepopulation |
string |
Controls prepopulation of the local database with the full item set during account setup.
|
supported |
|||||||||
bookmark.url-editable |
bool |
|
Controls whether the server URL in the text field during the creation of new bookmarks can be changed. |
supported |
Item Policies
Key | Type | Default | Description | Status |
---|---|---|---|---|
item-policy.local-copy-expiration |
int |
|
The number of seconds that a file hasn’t been downloaded, modified or opened after which the local copy is removed. |
advanced |
item-policy.local-copy-expiration-enabled |
bool |
|
Controls whether local copies should automatically be removed after they haven’t been downloaded, modified or opened for a period of time. |
advanced |
item-policy.vacuum-sync-anchor-ttl |
bool |
|
Number of seconds since the removal of an item after which the metadata entry may be finally removed. |
debugOnly |
Connection
Settings concerning HTTP user agent, cookies, background support etc.
Key | Type | Default | Description | Status | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
connection.allow-cellular |
bool |
|
Allow the use of cellular connections. |
recommended |
||||||||||||
core.cookie-support-enabled |
bool |
|
Enable or disable per-process, in-memory cookie storage. |
supported |
||||||||||||
http.user-agent |
string |
|
A custom The following placeholders can be used to make it dynamic:
- |
supported |
||||||||||||
connection.always-request-private-link |
bool |
|
Controls whether private links are requested with regular PROPFINDs. |
advanced |
||||||||||||
connection.plain-http-policy |
string |
|
Policy regarding the use of plain (unencryped) HTTP URLs for creating bookmarks. A value of |
advanced |
||||||||||||
connection.validator-flags |
stringArray |
Allows fine-tuning the behavior of the connection validator by enabling/disabling aspects of it.
|
advanced |
|||||||||||||
core.action-concurrency-budgets |
dictionary |
|
Concurrency budgets available for sync actions by action category. |
advanced |
||||||||||||
core.scan-for-changes-interval |
int |
Minimum number of milliseconds until the next scan for changes, measured from the completion of the previous scan. If no value is provided, uses the poll interval provided in the server’s capabilities (in milliseconds) if it is greater or equal 5 seconds. Defaults to 10 seconds otherwise. |
advanced |
|||||||||||||
connection.allow-background-url-sessions |
bool |
|
Allow the use of background URL sessions. Note: depending on iOS version, the app may still choose not to use them. This settings is overriden by |
debugOnly |
||||||||||||
connection.force-background-url-sessions |
bool |
|
Forces the use of background URL sessions. Overrides |
debugOnly |
||||||||||||
connection.minimum-server-version |
string |
|
The minimum server version required. |
debugOnly |
||||||||||||
core.override-availability-signal |
bool |
Override the availability signal, so the host is considered to always be in maintenance mode ( |
debugOnly |
|||||||||||||
core.override-reachability-signal |
bool |
Override the reachability signal, so the host is always considered reachable ( |
debugOnly |
|||||||||||||
core.thumbnail-available-for-mime-type-prefixes |
stringArray |
|
Provide hints that thumbnails are available for items whose MIME-Type starts with any of the strings provided in this array. Providing an empty array turns off thumbnail loading. Providing |
debugOnly |
||||||||||||
host-simulator.active-simulations |
stringArray |
|
Active Host simulation extensions.
|
debugOnly |
Server Endpoints
Individually configurable endpoints of the ownCloud server instance.
Key | Type | Default | Description | Status |
---|---|---|---|---|
connection.endpoint-capabilities |
string |
|
Endpoint to use for retrieving server capabilities. |
advanced |
connection.endpoint-recipients |
string |
|
Path of the sharing recipient API endpoint. |
advanced |
connection.endpoint-remote-shares |
string |
|
Path of the remote shares API endpoint. |
advanced |
connection.endpoint-shares |
string |
|
Path of the shares API endpoint. |
advanced |
connection.endpoint-status |
string |
|
Endpoint to retrieve basic status information and detect an ownCloud installation. |
advanced |
connection.endpoint-thumbnail |
string |
|
Path of the thumbnail endpoint. |
advanced |
connection.endpoint-user |
string |
|
Endpoint to use for retrieving information on logged in user. |
advanced |
connection.endpoint-webdav |
string |
|
Endpoint to use for WebDAV. |
advanced |
connection.endpoint-webdav-meta |
string |
|
Endpoint to use for WebDAV metadata. |
advanced |
connection.well-known |
string |
|
Path of the .well-known endpoint. |
advanced |
Connection Authentication / Security
Settings concerning certificate validation policies.
Key | Type | Default | Description | Status | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
connection.allowed-authentication-methods |
stringArray |
Array of allowed authentication methods. Nil/Missing for no restrictions.
|
recommended |
|||||||||
connection.preferred-authentication-methods |
stringArray |
|
Array of authentication methods in order of preference (most preferred first).
|
recommended |
||||||||
connection.certificate-extended-validation-rule |
string |
|
Rule that defines the criteria a certificate needs to meet for OCConnection to recognize it as valid for a bookmark. Examples of expressions:
- |
advanced |
||||||||
connection.renewed-certificate-acceptance-rule |
string |
|
Rule that defines the criteria that need to be met for OCConnection to accept a renewed certificate and update the bookmark’s certificate automatically instead of prompting the user. Used when the extended validation rule fails. Set this to |
advanced |
||||||||
user-settings.allow |
stringArray |
List of settings (as flat identifiers) users are allowed to change. If this list is specified, only these settings can be changed by the user. |
advanced |
|||||||||
user-settings.disallow |
stringArray |
List of settings (as flat identifiers) users are not allowed to change. If this list is specified, all settings not on the list can be changed by the user. |
advanced |
|||||||||
connection.transparent-temporary-redirect |
bool |
|
Controls whether 307 redirects are handled transparently at the HTTP pipeline level (by resending the headers and body). |
debugOnly |
OAuth2 Based Authentication
Settings allowing to configure OAuth2 based authentication.
Key | Type | Default | Description | Status |
---|---|---|---|---|
authentication-oauth2.oa2-authorization-endpoint |
string |
|
OAuth2 authorization endpoint. |
advanced |
authentication-oauth2.oa2-client-id |
string |
|
OAuth2 Client ID. |
advanced |
authentication-oauth2.oa2-client-secret |
string |
|
OAuth2 Client Secret. |
advanced |
authentication-oauth2.oa2-redirect-uri |
string |
|
OAuth2 Redirect URI. |
advanced |
authentication-oauth2.oa2-token-endpoint |
string |
|
OAuth2 token endpoint. |
advanced |
authentication-oauth2.oa2-expiration-override-seconds |
int |
OAuth2 Expiration Override - lets OAuth2 tokens expire after the provided number of seconds (useful to prompt quick |
debugOnly |
OpenID Connect (OIDC) parameters
OpenID Connect (OIDC) parameters allow you fine-tune the behaviour, in case the Identity Provider (IdP) needs something special.
Key | Type | Default | Description | Status |
---|---|---|---|---|
authentication-oauth2.oidc-redirect-uri |
string |
|
OpenID Connect Redirect URI |
supported |
authentication-oauth2.oidc-register-client |
bool |
|
Use OpenID Connect Dynamic Client Registration if the |
supported |
authentication-oauth2.oidc-register-client-name-template |
string |
|
Client Name Template to use during OpenID Connect Dynamic Client Registration. In addition to the placeholders available for |
supported |
authentication-oauth2.oidc-scope |
string |
|
OpenID Connect Scope |
supported |
Logging
Logging settings control the ammount and type of app internal log messages stored as text files and accessible via settings menu.
Key | Type | Default | Description | Status | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
log.level |
int |
|
Log level
|
supported |
||||||||||||||
log.privacy-mask |
bool |
|
Controls whether certain objects in log statements should be masked for privacy. |
supported |
||||||||||||||
log.blank-filtered-messages |
bool |
|
Controls whether filtered out messages should still be logged, but with the message replaced with |
advanced |
||||||||||||||
log.colored |
bool |
|
Controls whether log levels should be replaced with colored emojis. |
advanced |
||||||||||||||
log.enabled-components |
stringArray |
|
List of enabled logging system components.
|
advanced |
||||||||||||||
log.format |
string |
|
Determines the format that log messages are saved in
|
advanced |
||||||||||||||
log.maximum-message-size |
int |
|
Maximum length of a log message before the message is truncated. A value of 0 means no limit. |
advanced |
||||||||||||||
log.omit-matching |
stringArray |
If set, omits logs messages containing any of the exact terms in this array. |
advanced |
|||||||||||||||
log.omit-tags |
stringArray |
If set, omits all log messages tagged with tags in this array. |
advanced |
|||||||||||||||
log.only-matching |
stringArray |
If set, only logs messages containing at least one of the exact terms in this array. |
advanced |
|||||||||||||||
log.only-tags |
stringArray |
If set, omits all log messages not tagged with tags in this array. |
advanced |
|||||||||||||||
log.single-lined |
bool |
|
Controls whether messages spanning more than one line should be broken into their individual lines and each be logged with the complete lead-in/lead-out sequence. |
advanced |
||||||||||||||
log.synchronous |
bool |
|
Controls whether log messages should be written synchronously (which can impact performance) or asynchronously (which can loose messages in case of a crash). |
advanced |
||||||||||||||
measurements.enabled |
bool |
|
Turn measurements on or off |
debugOnly |
Account Handling
Key | Type | Default | Description | Status |
---|---|---|---|---|
account.auto-connect |
bool |
|
Skip "Account" screen / automatically open "Files" screen after login |
supported |
Authentication Settings
Authentication settings control the behaviour of the web-based login.
Key | Type | Default | Description | Status | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
authentication.browser-session-class |
string |
|
Alternative browser session class to use instead of
|
supported |
||||||||||||
authentication.browser-session-prefers-ephermal |
bool |
|
Indicates whether the app should ask iOS for a private authentication (web) session for OAuth2 or OpenID Connect. Private authentication sessions do not share cookies and other browsing data with the user’s normal browser. Apple only promises that [this setting](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession/3237231-prefersephemeralwebbrowsersessio) will be honored if the user has set Safari as default browser. |
supported |
Browsersession (deprecated)
Browsersession settings were extended, and are now included in authentication.browser-session-class
(Authentication Settings)
Key | Type | Default | Description | Status |
---|---|---|---|---|
browser-session.custom-scheme-plain |
string |
Scheme to use instead of plain |
advanced |
|
browser-session.custom-scheme-secure |
string |
Scheme to use instead of |
advanced |
Branding Parameters
Key | Type | Default | Description | Status | ||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
branding.app-name |
string |
App name to use throughout the app. |
supported |
|||||||||
branding.disabled-import-methods |
stringArray |
List of disabled import methods that can’t be used.
|
supported |
|||||||||
branding.organization-name |
string |
Organization name to use throughout the app. |
supported |
|||||||||
Allow adding accounts |
bool |
|
Controls whether the user can add accounts. |
advanced |
||||||||
Allow editing accounts |
bool |
|
Controls whether the user can edit accounts. |
advanced |
||||||||
branding.enable-review-prompt |
bool |
|
Controls whether the app should prompt for an App Store review. Only applies if the app is branded. |
advanced |
||||||||
Profile definitions |
dictionaryArray |
Array of dictionaries, each specifying a profile. All |
advanced |
|||||||||
Feedback Email address |
string |
|
Email address to send feedback to. Set to |
advanced |
||||||||
Feedback URL |
string |
URL to open when selecting the "Send feedback" option. Allows the use of all placeholders provided in |
advanced |
|||||||||
branding.theme-definitions |
dictionaryArray |
Array of dictionaries, each specifying a theme. |
advanced |
|||||||||
branding.theme-generic-colors |
dictionary |
Dictionary defining generic colors that can be used in the definitions. |
advanced |
|||||||||
Documentation URL |
urlString |
URL to documentation for the app. Opened when selecting "Documentation" in the settings. |
advanced |
|||||||||
Help URL |
urlString |
URL to get help for the app. Opened when selecting "Help" in the settings. |
advanced |
|||||||||
Privacy URL |
urlString |
URL to get privacy information for the app. Opened when selecting "Privacy" in the settings. |
advanced |
|||||||||
Terms of use URL |
urlString |
|
URL to terms of use for the app. Opened when selecting "Terms Of Use" in the settings. |
advanced |
||||||||
branding.user-defaults-default-values |
dictionary |
Default values for user defaults. Allows overriding default settings. |
advanced |
|||||||||
|
bool |
Indicates if the user can change the server URL for the account. |
advanced |
|||||||||
|
stringArray |
The identifiers of the authentication methods allowed for this profile. Allows to f.ex. force OAuth2, or to use Basic Auth even if OAuth2 is available.
|
advanced |
|||||||||
|
stringArray |
Domain names (can also include subdomain name), which are allowed as server url when adding a new account. |
advanced |
|||||||||
|
string |
The name that should be used for the bookmark that’s generated from this profile and appears in the account list. |
advanced |
|||||||||
|
string |
Text used for the onboarding button title |
advanced |
|||||||||
|
urlString |
Optional URL to onboarding resources. |
advanced |
|||||||||
|
string |
Identifier uniquely identifying the profile. |
advanced |
|||||||||
|
string |
Name of the profile during setup. |
advanced |
|||||||||
|
string |
Message shown in an alert before opening the onboarding URL. |
advanced |
|||||||||
|
string |
Text that is shown when asking the user to enter their password. |
advanced |
|||||||||
|
string |
Text that is shown to the user before opening the authentication web view (f.ex. for OAuth2, OIDC). |
advanced |
|||||||||
|
urlString |
The URL of the server targeted by this profile. |
advanced |
|||||||||
|
string |
Text shown above the URL field when setting up an account. |
advanced |
|||||||||
|
string |
Welcome message shown during account setup. |
advanced |
Build Options
The following build options are only available for configuring custom builds via the Branding.plist
file. They can’t be configured dynamically wih MDM:
Key | Type | Default | Description | Status |
---|---|---|---|---|
build.custom-app-scheme |
string |
|
Name of the URL scheme to use for private links. Must be provided in Branding.plist at build time. For documentation, please see doc/BUILD_CUSTOMIZATION.md. |
supported |
build.custom-auth-scheme |
string |
|
Name of the URL scheme to use for OAuth2/OIDC authentication. Must be provided in Branding.plist at build time. The authentication redirect URI parameters must also be changed accordingly in Branding.plist and on the server side. For documentation, please see doc/BUILD_CUSTOMIZATION.md. |
supported |
build.flags |
string |
A set of space separated flags to customize the build. Must be provided in Branding.plist at build time. For documentation, please see doc/BUILD_CUSTOMIZATION.md. |
supported |
Diagnostics
Key | Type | Default | Description | Status |
---|---|---|---|---|
diagnostics.enabled |
bool |
|
Controls whether additional diagnostic options and information is available throughout the user interface. |
advanced |
Licensing
Key | Type | Default | Description | Status |
---|---|---|---|---|
licensing.disable-appstore-licensing |
bool |
|
Enables/disables App Store licensing support. |
debugOnly |
licensing.disable-enterprise-licensing |
bool |
|
Enables/disables Enterprise licensing support. |
debugOnly |
Localization feature
The localization feature allows to overwrite every string in the app, in every language.
Key | Type | Default | Description | Status |
---|---|---|---|---|
Localization Overrides |
dictionary |
|
Dictionary with localization overrides where the key is the English string whose localization should be overridden, and the value is a dictionary where the keys are the language codes (f.ex. "en", "de") and the values the translations to use. |
advanced |
AppConfig XML Schema
The XML format, developed by AppConfig community, makes it easy for developers to define and deploy an app configuration. It not only supports configuration variables having default values, but also provides a configuration UI description, which can be interpreted by the tool and which generates a plist file. Moreover, specfile XML is consistently supported by major EMM vendors.
AppConfig conformant spec file tailored to administrator needs and containing one or more of the above settings can be easily created using Config Spec Creator tool hosted at AppConfig website.
Example: Deployment With MobileIron
-
Open AppConfig Generator
-
Upload a specfile.xml.
-
Change the configuration options.
-
Download the generated plist file (ManagedAppConfig).
-
Open MobileIron Core.
-
Navigate to
-
Upload the generated plist and specify name, bundle ID, and description
Example: Deployment With Jamf Pro
-
Open AppConfig Generator
-
Upload a specfile.xml.
-
Change the configuration options.
-
Copy Dictionary (button).
-
Open Jamf Pro.
-
Navigate to
-
Paste the generated Dictionary into the "Preferences" field.