Download the Oracle Secure Workspace app from eDelivery and unzip the package to a local directory. Patches are published on ARU. This app is not available from the Apple or Google app stores.
This chapter contains the following sections:
To customize and brand the Oracle Workspace app for your company, use the Enterprise Distribution static library framework Xcode project, which is part of Oracle Mobile Security Suite. The project file name is SecureWorkspace.FIPS.zip or SecureWorkspace.NONFIPS.zip.
You can perform the following customizations on the Oracle Workspace app:
Bundle identifier
App name
App icon
Company logo
EULA text file
Custom config URLs for workspace app
Remove support for various document types
Enable Apple Data Protection
This section contains the following topics:
The bundle identifier (bundle ID) needs to match your provisioning profile. To change the bundle identifier follow these steps:
Note:
To learn about bundle IDs, see "Configuring Your Xcode Project for Distribution," in the App Distribution Guide, which is available from the iOS Developer Library:https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/ConfiguringYourApp/ConfiguringYourApp.html
Open BitzerSecureContainer.xcodeproj in Xcode.
Choose BitzerSecureContainer > Targets > General > Bundle Identifier.
In versions of Xcode older than Xcode version 6.2, choose Build Settings > General.
Under the Identity section, change the domain part of Bundle Identifier to the domain you want to use.
The default bundle identifier value is: com.oracle.OracleSecureWorkspace.
Change this to: com.example.OracleSecureWorkspace, where com.example is your domain.
The default name of the app is Workspace. This is what you will see on iOS springboard. This section describes how to change the default name.
Note: The following steps require the Plistbuddy application to be installed on your Mac.
To change the app name on devices that use the English (en) language setting, do the following:
Open the folder where you unzipped the BitzerSecureContainer and BitzerSecureContainer.xcodeproj folders.
Type the following command:
/usr/libexec/PlistBuddy -c "Set :CFBundleDisplayName YourNewAppName" BitzerSecureContainer/BitzerSecureContainer.embeddedframework/BitzerSecureContainer.framework/Resources/en.lproj/InfoPlist.strings
To change the app name for other languages, do the following:
Replace the en.lproj subfolder with the appropriate language subfolder. For example, for French use fr.lproj, for German use de.lproj, for Spanish use es.lproj, and so on.
Type the following command to see all of the language files:
ls BitzerSecureContainer/BitzerSecureContainer.embeddedframework/BitzerSecureContainer.framework/Resources/*.lproj/InfoPlist.strings
To change the name in all of the language files, type this command:
for d in `ls BitzerSecureContainer/BitzerSecureContainer.embeddedframework/BitzerSecureContainer.framework/Resources/*.lproj/InfoPlist.strings`; do /usr/libexec/PlistBuddy -c "Set :CFBundleDisplayName YourNewAppName" $d ; done
To change the app icon, the company logo, and the default splash screen, replace the icons under the folder:
BitzerSecureContainer/BitzerSecureContainer.embeddedframework/Resources
The icons must have following dimensions:
| Image Name | Dimension | Description |
|---|---|---|
|
Icon.png |
57 x 57 |
App Icon |
|
Icon@2x.png |
114 x 114 |
App Icon |
|
Icon-72.png |
72 x 72 |
App Icon |
|
Icon-144.png |
144 x 144 |
App Icon |
|
Icon-Small.png |
29 x 29 |
App Icon |
|
Icon-Small@2x.png |
58 x 58 |
App Icon |
|
Icon-Small-50.png |
50 x 50 |
App Icon |
|
Default.png |
320 x 480 |
iPhone splash screen |
|
Default@2x.png |
640 x 960 |
iPhone splash screen for retina |
|
Default-568h@2x.png |
640 x 1136 |
iPhone 5 splash screen for retina |
|
Default-Portrait~ipad.png |
768 x 1004 |
iPad portrait splash screen |
|
Default-Portriat@x~ipad.png |
1536 x 2008 |
iPad portrait splash screen for retina |
|
Default-Landscape~ipad.png |
1024 x 748 |
iPad landscape splash screen |
|
Default-Landscape@2x~ipad.png |
2048 x 1496 |
iPad landscape splash screen for retina |
|
company-logo.png |
200 x 55 |
Company logo image for iPhone |
|
company-logo@2x.png |
400 x 110 |
Company logo image for iPhone with retina |
|
company-logo~ipad.png |
600 x 165 |
Company logo image for iPad |
|
company-logo@2x~ipad.png |
1200 x 330 |
Company logo image for iPad with retina |
This section describes how to create and display the end-user license agreement (EULA) on a device.
Note:
Because the EULA applies to the device and not the end-user, it is only displayed once per device the first time a user logs in to the Secure Workspace. This holds true even if Multi-User mode (Shared Workspace mode) is enabled on the device.To create a file with the end-user license agreement content, name it EULA.txt and add it to this location:
BitzerSecureContainer/BitzerSecureContainer.embeddedframework/BitzerSecureContainer.framework/Resources/en.lproj/EULA.txt
In addition, the SHOW_EULA_SCREEN value should be set to true in the CompanySettings.plist file:
BitzerSecureContainer/BitzerSecureContainer.embeddedframework/BitzerSecureContainer.framework/Resources/Targets/Bitzer/CompanySettings.plist file
<key>SHOW_EULA_SCREEN</key>
<true/>
Note:
By default, the Secure Workspace app is not configured to connect to any specific MSAS server. The Secure Workspace app can be customized to automatically configure itself to a single MSAS server or present a list of available MSAS servers for the user to select from. Please contact your Oracle Mobile Security Suite server team for Config URL details.The URLs and help text on the Workspace config screen are customizable. This feature makes it possible to link to custom help files that you develop and host. Follow these steps to customize the URLs and help text on the config screen:
Open BitzerSecureWorkspace.xcodeproj in Xcode.
Open the file: BitzerSecureContainer/BitzerSecureContainer.embeddedframework/Resources/CustomizableSettings.plist
The Config URL settings are under the Root node in an Array type item called CONFIG_URL_SETTINGS. Each item in this array represents a Config URL that will be available for selection on the Config screen. If no items are present for CONFIG_URL_SETTINGS array, a default demo URL and help text is displayed. If one or more items are present under the CONFIG_URL_SETTINGS array, the user is presented with custom URL selection options.
Modify Item 0 under CONFIG_URL_SETTINGS and enter your customized Config URL. The information to enter is described in the following table.
Table 10-2 CONFIG_URL_SETTINGS
| Property (key) | Value | Example |
|---|---|---|
|
|
Optional setting that is used if there is only one configuration URL.
|
Example 1: <key>autoconfigure</key> <true/> Example 2: <key>autoconfigure</key> <false/> |
|
|
String value that will be displayed instead of the URL. This should be user friendly text that describes your Mobile Security Access Server site. For example, if you have more than one Mobile Security Access Server site you can label them as Houston Site, or BYOD Site. |
<key>label</key> <string>Your MSAS Server</string> |
|
|
The Mobile Security Access Server configuration URL. |
<key>value</key> <string>http://example.com/bmax/bmconfig_kinit_kinit.json</string> |
If more than one MSAS server is available, you can configure the Secure Workspace so that end users can pick which MSAS server to connect to.
To add more than one Config URL, close Item 0, copy and paste it to create a duplicate item, and edit it. Multiple Config URLs are presented as an action sheet with site labels for each button.
A CONFIG_URL_SETTINGS example is given here.
<key>CONFIG_URL_SETTINGS</key>
<array>
<dict>
<key>autoconfigure</key>
<false/>
<key>label</key>
<string>Your MSAS Server name alias</string>
<key>value</key>
<string>http://example.com/bmax/bmconfig_kinit_kinit.json</string>
</dict>
</array>
Use this feature to add one or more password management links to the Secure Workspace login dialog, for example Forgot Password and Forgot User ID. Oracle Mobile Security Suite does not provide advanced password management functionality. Rather, this feature provides a placeholder to launch password management links from the Secure Workspace app. Using these links, the user can open a web page where they can create, reset, or recover their password. Each link is opened outside of the Secure Workspace and does not use any of the Secure Workspace security or networking features. Be sure to use unauthenticated links that do not require a login session. Users should be able to use the URLs from Safari (the default browser) without having to authenticate.
Customize the Secure Workspace app by modifying the CustomizableSettings.plist file located here:
BitzerSecureContainer/BitzerSecureContainer.embeddedframework/Resources/CustomizableSettings.plist
Add the PASSWORD_MANAGEMENT key, which specifies the link to the password management site that should be included in the login dialog.
The following notes apply to this property:
You can add unlimited entries, however, three entries fills the display in the Secure Workspace login screen. More than three entries is not recommended.
Descriptions in multiple languages can be provided using standard language codes.
A PASSWORD_MANAGEMENT example with two entries is shown here.
<key>PASSWORD_MANAGEMENT</key>
<array>
<dict>
<key>URL</key>
<string>http://example.com/NewUser.html </string>
<key>de</key>
<string>Passwort vergessen URL</string>
<key>en</key>
<string>Forgot Password URL</string>
<key>fr</key>
<string>Mot de passe oublié URL</string>
</dict>
<dict>
<key>URL</key>
<string>http://example.com/PasswordReset.html</string>
<key>de</key>
<string>Benutzer-ID vergessen URL</string>
<key>en</key>
<string>Forgot User ID URL</string>
<key>fr</key>
<string>ID utilisateur Mot URL</string>
</dict>
</array>
Tip:
Apple Support defines Apple Data Protection as follows:Apple Data protection is available for devices that offer hardware encryption, including iPhone 3GS and later, all iPad models, and iPod touch (3rd generation and later). Data protection enhances the built-in hardware encryption by protecting the hardware encryption keys with your passcode. This provides an additional layer of protection for your e-mail messages attachments, and third-party applications.
For more information, refer to this Apple Support page:
To enable Apple Data Protection, follow these steps:
Log into the Apple iOS Dev Center under https://developer.apple.com/ and go to Certificate, Identifiers and Profiles.
Go to Identities and select the App ID you want to use with Workspace app.
Edit the App ID and, select Data Protection, then select Protected Unless open under Sharing and Permissions.
Regenerate your provisioning profile and use that profile for signing the workspace app.
The Workspace app enables you to open the following documents types:
Word: docx and doc
Powerpoint: pptx and ppt
Excel: xlsx and xls
Text: txt, rtf
Adobe pdf
Images: jpg, jpeg, png, tif, tiff, bmp, gif
Videos: mov
To remove support for any or all of these file types (that is, to prevent the Workspace app from opening them) you must remove the document types from BitzerSecureWorkspace.xcodeproj and rebuild the Workspace app. Follow these steps:
Open BitzerSecureContainer.xcodeproj in Xcode.
Select the Info tab and scroll down to Document Types section.
Remove the document types: Bitzer MS Reader, Bitzer Document Editor, Bitzer PDF Reader and Bitzer Image Viewer. Do not remove any other documents types.
To rebuild the Workspace app after making changes, follow these steps:
Make sure the bundle identifier has been updated to match your provisioning profile
Ensure the correct provisioning profile has been selected under Build Settings > Code Signing.
Ensure the correct code signing identity has been selected under Build Settings > Code Signing.
Select iOS Device from Product > Destination. The Workspace app can only be built for iOS Device.
Select Product from the menu and then select Archive.
In the Organizer - Archives window click Export.
In the Select the method for export window, select Save for Enterprise or Ad Hoc Deployment and click Next.
Select Provisioning Profile and click Choose.
Select Export from the Summary window.
Save the app without selecting Save for Enterprise Distribution. This generates a signed IPA for the Workspace app.
Once the Workspace app ipa file is generated, you can upload it to your Catalog on the Mobile Security Manager console or to your enterprise app store.
The Secure Workspace unsigned APK that is part of Oracle Mobile Security Suite can be used for customization and branding. You can perform the following customizations:
App package name
App name
App icon
Splash screen
EULA text file
Custom config URLs for workspace app
Remove support for various document types
This section contains the following topics:
Before you can customize or make any changes for branding, you must extract the APK. Ensure that the Oracle Mobile Security App Containerization Tool has been installed, then run the following command to extract the APK.
build-apk.sh extract SecureWorkspace-unsigned-xxxx.apk
The package name serves as a unique identifier for the application. You may want to customize this value to gain additional control of the app upgrade process or for security reasons. Because the package name defines your application's identity, if you change it after it has been deployed, the new app will be considered to be a different application and users of the previous version will not be able to update to the new version. For more information see:
http://developer.android.com/guide/topics/manifest/manifest-element.html
To change the package name for a Secure Workspace app, follow these steps:
Go to the folder where the APK was extracted.
Edit file AndroidManifest.xml.
On the second line of the file, modify the attribute package to the package name you want. For example:
<manifest android:versionCode="1" android:versionName="@string/version_name" package="com.acme.secureworkspace" xmlns:android="http://schemas.android.com/apk/res/android">
Save the file.
To change name of a Secure Workspace app follow these steps:
Go to the folder where the APK was extracted.
Edit the file res/values/strings.xml.
Modify the value for the string name app_name. For example:
<string name="app_name">My Workspace</string>
Save the file.
To change the icon of a Secure Workspace app, follow these steps:
Go to the folder where the APK was extracted.
Under the res folder, there are several folders with names like drawable-xxxx. Each of these folder contains a file, icon.png, that is sized at 128 x 128 px. Replace each icon.png file with your own icon. Make sure the resolutions match.
The icons must go in the folders listed in Table 10-3:
icon.png (App icon) |
splashscreen.png |
Folder (under res/) |
|---|---|---|
|
128x128 |
N/A |
|
|
128x128 |
480x800 |
|
|
128x128 |
800x480 |
|
|
128x128 |
800x480 |
|
|
128x128 |
800x480 |
|
|
128x128 |
1024x768 |
|
|
128x128 |
480x800 |
|
|
128x128 |
480x800 |
|
|
128x128 |
768x1024 |
|
|
128x128 |
N/A |
|
|
128x128 |
N/A |
|
For more information about resolution and size of images to be placed in the respective drawable folders, see "Supporting Multiple Screens" at http://developer.android.com
To Change the splash screen image, follow these steps:
Go to folder where the APK was extracted.
Under the res folder, there are several folders with names like drawable-xxxx. Each of these folder contains a file, splashscreen.png, with a specific resolution. Replace each splashscreen.png file with your own icon. Make sure the resolutions match.
To change the MDM Agent settings, which include the display-name label value and description value, follow these steps:
Go to the folder where the APK was extracted.
Open the file res/values/strings.xml for editing.
Locate msm_device_admin_label and msm_device_admin_description and modify the values as needed. For example:
<string name="msm_device_admin_label">My Device Administrator</string> <string name="msm_device_admin_description">Lets you securely manage your device</string>
If translated versions of msm_device_admin_label and msm_device_admin_description exist, update them in the corresponding strings.xml file under res/values-<language_code>-<region_code>/strings.xml. If translated versions are not available, then the translated versions of the default values should be removed from those files.
Save the file.
This section describes how to create and display the end-user license agreement (EULA) on a device.
Note:
Because the EULA applies to the device and not the end-user, it is only displayed once per device the first time a user logs in to the Secure Workspace. This holds true even if Multi-User mode (Shared Workspace mode) is enabled on the device.To create a file with the end-user license agreement content, follow these steps:
Go to the folder where the APK was extracted.
Create the file assets/EULA-en with the EULA text contents.
Create the file assets/EULA-<locale> with EULA text using language specific to that locale. For example, for French the file would be assets/EULA-fr.
Save the EULA files.
If the device locale does not match the locale specified in a EULA file, the device will default to the EULA-en version.
This feature makes it possible to link to custom help files that you develop and host. Follow these steps to customize the default config URLs and help text:
Go to the folder where the APK was extracted.
Edit the file assets/prop.txt. See Section 10.2.10 for a sample prop.txt file.
Add config URLs under "--- Choose config urls from List ---". URLs must be comma separated and each URL must be enclosed within double quotes. For example:
"properties":
{
"autoConfigure": "false",
"configURLs":
[
"--- Choose config urls from List ---",
"https://omss1.acme.com/bmax/bmax_config.json"
,"https://omss2.acme.com/bmax/bmax_config.json"
]
}
When a single config URL is specified, then autoConfigure can be used. If autoConfigure is set to true, you are not prompted to select a config URL. Instead, the specified URL is selected for auto configuration.
The following table describes the config_url configuration properties and values:
Table 10-4 Settings and values for prop.txt
| Property | Value | Example |
|---|---|---|
|
|
|
Example 1: "autoConfigure": "false" Example 2: "autoConfigure": "true" |
|
|
Additional descriptions in other languages can be included using standard language codes. |
"en":"Your Config URL ",
"url":"https://bmax6.example.com/bmax/bmconfig_kinit_kinit.json"
|
Save the file prop.txt.
Use this feature to add one or more password management links to the Secure Workspace login dialog, for example Forgot Password and Forgot User ID. Oracle Mobile Security Suite does not provide advanced password management functionality. Rather, this feature provides a placeholder to launch password management links from the Secure Workspace app. Using these links, the user can open a web page where they can create, reset, or recover their password. Each link is opened outside of the Secure Workspace and does not use any of the Secure Workspace security or networking features. Be sure to use unauthenticated links that do not require a login session. Users should be able to use the URLs from the default browser without having to authenticate.
Customize the Secure Workspace app by modifying the prop.txt file located in the AndroidContainer/assets folder. See Section 10.2.10 for a sample prop.txt file.
The prop.txt file supports localization. For password_management, supply localized, non-English strings using standard two character language codes. Strings are displayed based on the device language setting the language identifier. If the device language is not present for the desired option, the English language string is displayed.
The following table describes the password_management configuration properties and values:
Table 10-5 Settings and values for prop.txt
| Property | Value | Example |
|---|---|---|
|
|
Additional descriptions in other languages can be included using standard language codes. Note - You can add unlimited entries, however, three entries fills the display in the Secure Workspace login screen. More than three entries is not recommended. |
"en":"Your Password Reset site ",
"url":"https://example.com/password_reset.html "
|
A sample prop.txt file is shown here:
{
"properties":
{
"autoConfigure": "false",
"config_urls":
[
{
"en":"Your KINIT Server Config",
"fr":"Votre KINIT Server Config",
"de":"Ihr KINIT Server Config",
"url":”https://example.com/bmax/bmconfig_kinit_kinit.json”
},
{
"en":"Your PKINIT Server Config",
"fr":"Votre PKINIT Server Config",
"de":"Ihr PKINIT Server Config",
"url":”https://example.com/bmax/bmconfig_pkinit_tlp.json”
}
],
"password_managment":
[
{
"en":"Your Registration URL",
"fr":"Votre Registration URL",
"de":"Ihr Registration URL",
"url":"http://example.com/NewUser.html"
},
{
"en":"Your Password Reset URL",
"fr":"Votre Password Reset URL",
"de":"Ihr Password Reset URL",
"url":"http://example.com/PasswordReset.html"
}
],
"exitOnLogin": "false",
}
}
When Kiosk Mode is enabled, users only see the Workspace and the apps within the Workspace. Interaction with the operating system outside the Workspace is minimized. The user cannot close the Secure Workspace app, making this mode suitable for public environments where supervision is minimal, such as lobbies, exhibit spaces, and show rooms.
To enable Kiosk Mode, customize the Secure Workspace app by modifying the prop.txt file located in the AndroidContainer/assets folder. See Section 10.2.10 for a sample prop.txt file. Modify the file as follows:
If the "appMode":"workspace", line is present, change it to: "appMode":"launcher",
Otherwise, after
"exitOnLogin": "false",
add the following line:
"appMode":"launcher",
This change enables a proprietary Oracle launcher, not the Google Now launcher.
Save your changes.
Create a Kiosk Mode mobile security policy.
Edit the mobile security policy's Workspace policy and set the Shared Workspace Mode setting to Multi-User. This is a required setting that wipes away Workspace data every time a user logs out of the Workspace. Assign the policy to a role in LDAP that has users who can only access corporate data using the Kiosk mode.
To prevent the Workspace app from opening certain file types follow these steps:
Go to the folder where the APK was extracted.
Edit file AndroidManifest.xml.
Search for the data element in intent-filter that matches the mimeType or path pattern for the file type you want to prevent from opening in Workspace app.
Delete the data element.
Save AndroidManifest.xml.
To package the customized APK content into an APK, follow these steps:
Verify that the Oracle Mobile Security App Containerization Tool has been installed.
Go to the folder where the APK was extracted.
Run the following command:
build-apk.sh package <Secure_Workspace_apk_folder> <new_output_apk> <original_apk>
Secure_Workspace_apk_folder is where the APK was extracted using the extract command.
To sign an APK, use the c14n -c signonly command. For example:
c14n -c signonly -i input.apk -o output.apk -keystore release-key.keystore -storepass password -storealias release -v
For more information on signing Android apps, see "Signing Your Applications" at: http://developer.android.com
Workspace app and containerized apps must be signed using the same certificate. Containerized apps will not work with Workspace if they are signed with a different certificate.
For more information on signing Android apps, see "Signing Your Applications" at http://developer.android.com