Oracle® Fusion Middleware

Customization and Branding Guide for Oracle Mobile Security Suite

Release 3.0

E51967-01

February 2014

Oracle Mobile Security Suite enhances employee productivity by allowing secure access to corporate applications and data from mobile devices while preserving a rich user experience. The Mobile Security Container creates an enterprise workspace on any mobile device, corporate owned or personal, and for all mobile platforms. Employees get seamless access to intranet resources, corporate data and mobile apps with enterprise-grade security and deep integration with Oracle Access Manager and Microsoft Active Directory authentication for true Single Sign-On.

You use the Enterprise Distribution static library framework Xcode project, which is part of Oracle Mobile Security Suite, to customize and brand the Oracle Workspace app for your company.

This document contains the following sections:

- Section 1, "Oracle Secure Workspace Customization for iOS"

- Section 2, "Oracle Secure Workspace Customization for Android"

- Section 3, "Documentation Accessibility"

1 Oracle Secure Workspace Customization for iOS

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:

- Section 1.1, "Change Bundle Identifier"

- Section 1.2, "Change App Name"

- Section 1.3, "Change App Icon, Company Logo and Default Splash Screen"

- Section 1.4, "Change EULA File"

- Section 1.5, "Customize Config URLs"

- Section 1.6, "Enable Apple Data Protection"

- Section 1.7, "Remove Document Types"

1.1 Change Bundle Identifier

You need to use a bundle identifier that matches your provisioning profile. To change the bundle identifier follow these steps:

1. Open BitzerSecureContainer.xcodeproj in XCode.

2. Select Build Settings -> General.

3. 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.

1.2 Change App Name

The default name of the app is Workspace. This is what you will see on iOS springboard. To change the default name, follow these steps:

1. Open BitzerSecureContainer.xcodeproj in XCode.

2. Select Build Settings -> Info.

3. Under Custom iOS Target Properties look for the Bundle display name and change it to the new app name.

1.3 Change App Icon, Company Logo and Default Splash Screen

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:

Table 1 Icon 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

1.4 Change EULA File

To replace the default EULA text, change the text in the file: BitzerSecureWorkspace/BitzerSecureWorkspace.embeddedframework/Resources/en.lproj/EULA.txt

1.5 Customize Config URLs

The default URLs and help text on the Workspace config screen are customizable. Follow these steps to customize them:

1. Open BitzerSecureWorkspace.xcodeproj in Xcode

2. Open the file: BitzerSecureContainer/BitzerSecureContainer.embeddedframework/Resources/CustomizableSettings.plist

3. 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.

4. Modify Item 0 under CONFIG_URL_SETTINGS and enter your customized Config URL. The information to enter is as follows:

- Label: this is text that will be displayed instead of URL. This should be a user friendly text that describes your Mobile Secure Access Server site. e.g: If you have more than one Mobile Secure Access Server sites you can label them as, Houston Site, or BYOD Site. Type must be String.

- Value: This should be the Mobile Security Access Server config URL. Type must be String.

- Autoconfigure: This is optional setting and is only used if there is only one config URL. If set to YES, the user is not prompted for config URL. On launching the Workspace app for the first time, app will be configured using this URL. If set to NO, the user is presented with Config URL screen and a link will appear under Config URL field.

5. 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.
When more than one Config URLs is present, help text is displayed under the Config URL text field. Help text can be customized by editing the SelectSiteTextConfigViewKey key in CustomizableText.strings. The title for the action sheet can be customized by editing the SelectSiteTextActionSheetKey key in CustomizableText.strings. CustomizableText.strings is located under BitzerSecureContainer/BitzerSecureContainer.embeddedframework/Resources

1.6 Enable Apple Data Protection

To enable Apple Data Protection, follow these steps:

1. Log into the Apple iOS Dev Center under https://developer.apple.com/ and go to Certificate, Identities and Profiles.

2. Go to Identities and select the App ID you want to use with Workspace app.

3. Edit the App ID and, select Data Protection, then select Protected Unless open under Sharing and Permissions.

4. Regenerate your provisioning profile and use that profile for signing the workspace app.

1.7 Remove Document Types

The Workspace app enables you to open the following documents types:

- Word: docx and doc

- Powerpoint: pptx and ppt

- Excel: xlsx and xls

- Text files

- rtf

- Adobe pdf

- jpg, jpeg, png, tif, tiff, bmp, gif

- 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:

1.7.1 Removing the Document Types from BitzerSecureWorkspace.xcodeproj

1. Open BitzerSecureWorkspace.xcodeproj in Xcode.

2. Select the Info Settings tab and scroll down to Document Types section.

3. Remove the document types: Bitzer MS Reader, Bitzer Document Editor, Bitzer PDF Reader and Bitzer Image Viewer. Do not remove any other documents types.

1.7.2 Rebuilding the Workspace

To rebuild the Workspace app after making changes, follow these steps:

1. Make sure the bundle identifier has been updated to match your provisioning profile

2. Ensure the correct provisioning profile has been selected under Build Settings -> Code Signing.

3. Ensure the correct code signing identity has been selected under Build Settings -> Code Singing.

4. Select iOS Device from Destination. The Workspace app can only be built for iOS Device.

5. Select Product from the menu and then select Archive.

6. In the Organizer - Archives window click Distribute.

7. In the Select the method for distribution window, select Save for Enterprise or Ad Hoc Deployment and click Next.

8. Select Provisioning Profile and click Export.

9. 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 Administrative Console or to your enterprise app store.

1.7.3 Certificate and Provisioning Profile Requirements

Workspace app and containerized apps must be signed using provisioning profiles that have same App ID Prefix. Containerized apps will not work with Workspace if they have a different App ID Prefix.

2 Oracle Secure Workspace Customization for Android

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:

- Section 2.1, "Extracting APK for Customization"

- Section 2.2, "Change App Package Name"

- Section 2.3, "Change App Name"

- Section 2.4, "Change App Icon"

- Section 2.5, "Change Splash Screen Image"

- Section 2.6, "Change EULA"

- Section 2.7, "Customize Config URLs"

- Section 2.8, "Remove Document Types"

- Section 2.9, "Packaging Customized APK"

- Section 2.10, "Signing APK"

- Section 2.11, "Signing Certificate Requirements"

2.1 Extracting APK for Customization

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

2.2 Change App Package Name

To change the package name for a Secure Workspace app, follow these steps:

1. Go to the folder where the APK was extracted.

2. Edit file AndroidManifest.xml.

3. 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">

4. Save the file.

2.3 Change App Name

To change name of a Secure Workspace app follow these steps:

1. Go to the folder where the APK was extracted.

2. Edit the file res/values/strings.xml.

3. Modify the value for the string name app_name. For example:

<string name="app_name">My Workspace</string>

4. Save the file.

2.4 Change App Icon

To change the icon of a Secure Workspace app, follow these steps:

1. Go to the folder where the APK was extracted.

2. Under the res folder, there are several folders with names like drawable-xxxx. Each of these folder contains a file, icon.png, with a specific resolution. Replace each icon.png file with your own icon. Make sure the resolutions match.

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

2.5 Change Splash Screen Image

To Change the splash screen image, follow these steps:

1. Go to folder where the APK was extracted.

2. 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.

2.6 Change EULA

To replace the default EULA text, follow these steps:

1. Go to the folder where the APK was extracted.

2. Replace the contents of the file assets/EULA with your custom EULA file.

3. Save the EULA file.

2.7 Customize Config URLs

To add custom config URLs on your config screen in Workspace app, follow these steps:

1. Go to the folder where the APK was extracted.

2. Edit the file assets/prop.txt.

3. 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"
]
}

4. 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.

5. Save the file prop.txt.

2.8 Remove Document Types

To prevent the Workspace app from opening certain file types follow these steps:

1. Go to the folder where the APK was extracted.

2. Edit file AndroidManifest.xml.

3. 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.

4. Delete the data element.

5. Save AndroidManifest.xml.

2.9 Packaging Customized APK

To package the customized APK content into an APK, ensure that the Oracle Mobile Security App Containerization Tool has been installed, then run following command:

build-apk.sh package Secure_Workspace_apk_folder output_apk

Secure_Workspace_apk_folder is where the APK was extracted using the extract command.

2.10 Signing APK

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

2.11 Signing Certificate Requirements

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

3 Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Oracle Fusion Middleware Customization and Branding Guide for Oracle Mobile Security Suite, Release 3.0

E51967-01

Copyright © 2014, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate failsafe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2014, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.