url scheme replacement for ios - vdc-download.vmware.com · the configuration is in a property list...

TechnicalFeatureGuide

URLSchemeReplacementforiOS Page1of15

URLSchemeReplacementforiOSVMwareWorkspaceONE®dataleakagepreventionsupportsrun-timereplacementoftheschemeinaURLthatanapplicationrequeststoopen.Thiscanbeused,forexample,to

Causeanenterpriseemailclienttoopenwhentheendusertapsonamailtolink,insteadofthesystemdefaultemailapplication.Causeaparticularwebbrowsertoopenwhentheendusertapsonanhttpslink,insteadofthesystemdefaultwebbrowser.

URLschemereplacementisconfiguredintheWorkspaceONEUnifiedEndpointManager(UEM)console.ReplacementisprocessedatruntimebytheWorkspaceONEmobileSoftwareDevelopmentKit(SDK),ifconfiguredinthemobileapplication.URLschemereplacementisavailableintheSDKforiOS.

TableofContentsDescription........................................................................................................2

Integration.........................................................................................................4

Compatibility..................................................................................................4

Policy.............................................................................................................5

SettingsFile...................................................................................................6

ConsoleConfiguration.....................................................................................7

ApplicationConfiguration................................................................................8

Instructions.................................................................................................8

TestCode......................................................................................................11

Appendix:DecisionTreeActivityDiagram..........................................................12

Appendix:ConsoleUserInterfaceScreenCaptures.............................................13

Appendix:ApplicationProjectScreenCapture....................................................14

DocumentInformation......................................................................................15



DescriptionWhenanapprequeststoopenaURL,theschemeoftheURLisusedbythemobileoperatingsystemtodeterminewhichotherapplicationwillreceivetherequest.Replacingtheschemewillcauseadifferentreceivertobeselected.

WorkspaceONEdataleakagepreventionsupportsautomaticrun-timereplacementoftheschemeinaURL(UniformResourceLocator)valuethatisbeingopenedbyamobileapplicationthathasintegratedtheSDK.

WorkspaceONEsupportsreplacementoftheseURLschemes:

mailtohttphttps

ThefeaturecanbeconfiguredtoreplacetheschemeinaURLrequestwitheither:

Abuilt-inschemethatwillselectaVMwareWorkspaceONEappasthereceiver,Boxerformailto,Webforhttpandhttps.

AcustomschemeconfiguredintheUEMthatwillselecttheenterprise’schosenappasthereceiver.

WorkspaceONEDLPURLreplacementworksasfollows.

Ifacustomschemeisrequired,thenaspecificURLreplacementpolicyisconfiguredintheUEM.Thepolicyconfigurationwillspecifywhichschemesaretobereplacedandtheirreplacementvalues.SeePolicyandSettingsFileforinstructions.

Thisconfigurationisn’trequiredforbuilt-inschemereplacement.

DataLeakagePrevention(DLP)isactivatedandconfiguredintheUEM.DLPisasecuritypolicy.SeeConsoleConfiguration.

TheDLPandURLreplacementpolicyconfigurationsareretrievedbytheSDKinstanceinamobileapplication,atenrollmenttimeorsubsequently.

SupportforURLreplacementisconfiguredinthemobileappproject,atbuildtime.Configurationwillspecifywhichschemesaretobereplaced.

Theconfigurationisinapropertylistfile.SeeApplicationConfigurationfordetails.



WhentheappexecutesanimplicitorexplicitrequesttoopenaURL,theSDKreplacestheschemeifthefollowingconditionsaremet.

TheURLreplacementconfigurationintheapplicationbuildspecifiesthattheschemebeingopenedistobereplaced.

DLPpolicyisactiveandspecifiesURLreplacement.

Thereplacementschemewillbe

AcustomschemeifthereisaURLreplacementconfigurationfromtheUEM,anditspecifiesareplacementfortheschemeintheURLbeingopened.

Abuilt-inreplacementschemeotherwise.

TherequesttoopentheURLcontinuestotheoperatingsystemandhencetothereceiverapplication.

SeetheDecisionTreeActivityDiagramintheappendixtothisdocumentforadiagrammaticrepresentationoftheabove.

-

-

-

-



IntegrationTointegratethefeatureintoyourapplication,followtheinstructionsbelow.

CompatibilityBeforeyoubeginintegration,ensureyouhaveaccesstocompatibleversionsofsoftware.ThefollowingtableshowstheversionnumbersoftheWorkspaceONEcomponentsinwhichthisfeaturefirstbecameavailable.

Software Available

WorkspaceONESDKforiOS 20.6

WorkspaceONEmanagementconsole 9.7*

Version9.7*istheearliestsupportedUEMattimeofwriting.AllcurrentversionsofUEMhavetheDLPandcustomsettingsoptions.



PolicyDecideonaschemereplacementpolicy.Thepolicyincludestheseelements:

Whichofthesupportedschemeswillbereplaced.

Foreachreplacedscheme,whichapplicationistherequiredreceiver.

Basedonthat:

Whatwillbethereplacementscheme.

Theschememustbeoneregisteredbytherequiredreceiverapplication.Theapplicationdevelopershouldsupplythisvalue,forexampleintheirproductdocumentation.

Whatnameforthereceiverappshouldbedisplayedtotheuser.

Thefullproductnamemightbeunfamiliar,toolong,orotherwiseunsuitablefordisplayinthemobileuserinterface.

Thepolicycouldberecordedinatablelikethefollowing.

OriginalScheme ReplacementScheme ReplacementAppName

mailto Replacementemailclientnamehttp Replacementbrowsernamehttps Replacementbrowsername

Notethefollowing.

Replacementofmailtoisoptional.

Replacementofhttpandhttpsisoptional.

Thereplacementappnameforthehttpandhttpsschemesmustbethesame.

Thereplacementschemesforhttpandhttpsneedn’tbethesamebutifhttpisreplacedthenhttpsmustalsobereplaced,andviceversa.

Forexample,thefollowingtableshowsasamplepolicythatspecifiesMicrosoftOutlookandtheBravebrowser.

OriginalScheme ReplacementScheme ReplacementAppName

mailto ms-outlook Outlook

http brave Brave

https brave Brave

-

-



SettingsFileCreateacustomsettingsfileforinsertionintoyourWorkspaceONEmanagementconsoleconfigurationuserinterface.ThefileisarepresentationofthePolicydecidedintheprecedingstep.

ThecustomsettingsfilewillbeplaintextinJavaScriptObjectNotation(JSON)format.Youcanuseatexteditortocreatethefile.

ThefollowingJSONcodeillustratestherequiredstructure.

{"CustomSDKSettings":{"com_vmware_DLP_Redirection":{"mailtoSchemeConfiguration":{"mailto":"REPLACEMENT-SCHEME-FOR-MAILTO","appName":"MAILTORECEIVERAPPNAME"},"httpSchemeConfiguration":{"http":"REPLACEMENT-SCHEME-FOR-HTTP","https":"REPLACEMENT-SCHEME-FOR-HTTPS","appName":"HTTPANDHTTPSRECEIVERNAME"}}}}

Thiscodecanalsobeusedasatemplate.

Changethecapitalizedpartstorepresentyourpolicy.

Ifyourpolicydoesn’treplacemailto,thendeletethe“mailtoSchemeConfiguration”entry.

Ifyourpolicydoesn’treplacehttpandhttps,thendeletethe“httpSchemeConfiguration”entry.



ConsoleConfigurationThisfeaturecanbeconfiguredintheWorkspaceONEmanagementconsole.Thefollowinginstructionsareintendedforapplicationdevelopersorotheruserswishingtotryoutthefeaturequickly.Fulldocumentationcanbefoundintheonlinehelp.

TheseinstructionsassumethatyouhavealreadycreatedaSettingsFile.

1. Logintothemanagementconsole.

Thedashboardwillbedisplayed.

2. Selectanorganizationgroup.

Bydefault,theGlobalgroupisselected.

3. Navigateto:Groups&Settings,AllSettings,Apps,SettingsandPolicies,SecurityPolicies.

ThisopenstheSecurityPoliciesconfigurationscreen,onwhichanumberofsettingscanbeswitchedonandoff,andconfigured.

4. FortheDataLossPreventionsetting,selectEnabled.

WhenEnabledisselected,furthercontrolswillbedisplayed.

5. Makethefollowingselections:

EnableComposingEmail:No

6. SelectSavetocommityourchangestotheconfiguration.

7. Navigateto:Groups&Settings,AllSettings,Apps,SettingsandPolicies,Settings.

ThisopenstheSettingsconfigurationscreen,onwhichanumberofsettingscanbeswitchedonandoff,andconfigured.

8. ForCustomSettings,selectEnabled.

WhenEnabledisselected,atextbox,alsolabelledCustomSettingswillbedisplayed.

9. IntheCustomSettingstextbox,pasteinthecontentsofyoursettingsfile.

10. SelectSavetocommityourchangestotheconfiguration.

SeealsotheConsoleUserInterfaceScreenCapturesintheappendixtothisdocument.

-



ApplicationConfigurationAddabundleandpropertylisttoyourapplicationproject,asshowninthefollowingscreencapture.

Screencapture1:Configurationintheapplicationproject

(TheapplicationnameinthescreencaptureisCaptivity,whichcanbeignored.)

InstructionsThefollowinginstructionswillsettheaboveconfiguration.

1. OpentheapplicationprojectintheAppleXcodeintegrateddevelopmentenvironment(IDE).

2. AddabundlenamedAWSDKDefaultstotheapplication,unlessitalreadyhasone.

Youcanaddabundlelikethis:

1. Selecttheapplicationintheprojectnavigator.

2. IntheXcodemenu,selectFile,New,File…

Thisopensatemplatechooser.

3. Choosethetemplate:SettingsBundle.

Afile-savedialogopeninwhichyouwillenterthenameofthenewbundle.

4. Enterthename:AWSDKDefaults

ThefullfilenamewillbeAWSDKDefaults.bundle

TheAWSDKDefaultsbundlehasnowbeenaddedandyoucancontinue.Thebundlemighthavesomeboilerplatecontent,likeaRootpropertylistandlocalisationfolder.Theboilerplatecontentcanbeignored.



3. AddapropertylistfilenamedAWSDKDefaultSettings.plisttotheAWSDKDefaultsbundle,unlessitalreadyhasone.

Youcanaddapropertylistfilelikethis:

1. Selecttheapplicationintheprojectnavigator.

2. IntheXcodemenu,selectFile,New,File…

Thisopensatemplatechooser.

3. Choosethetemplate:PropertyList.

Afile-savedialogopeninwhichyouwillenterthenameofthenewbundle.

4. Enterthename:AWSDKDefaultSettings

ThefullfilenamewillbeAWSDKDefaultSettings.plist

5. DraganddropthenewpropertylistfileintotheAWSDKDefaultsbundle.

Thepropertylistfilehasnowbeenaddedintherequiredlocationandyoucancontinue.



4. AddpropertiestotheAWSDKDefaultSettingsfile.

Adddictionarypropertiesasfollows.

Tosupportmailtoreplacement,addthis:

Key:AWMailtoSchemeConfigurationType:Dictionary

Insidethedictionary,addoneproperty:

Key:enabledValue:YES

Tosupportmailtoreplacement,addthis:

Key:AWURLSchemeConfigurationType:Dictionary

Insidethedictionary,addoneproperty:

Key:enabledValue:YES

Youcanaddeverythingbyopeningthepropertylistfileassourcecodeandthenpastingallorpartofthefollowingsnippet.<?xmlversion="1.0"encoding="UTF-8"?><!DOCTYPEplistPUBLIC"-//Apple//DTDPLIST1.0//EN""http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plistversion="1.0"><dict><key>AWMailtoSchemeConfiguration</key><dict><key>enabled</key><true/></dict><key>AWURLSchemeConfiguration</key><dict><key>enabled</key><true/></dict></dict></plist>

Savethepropertylistfile.

Thiscompletestheapplicationconfiguration.

-

-



TestCodeCodelikethefollowingcanbeusedtotesttheintegration.

//CreateasamplemailtoURL.//AssignmentusesaSwiftmultilinestringliteral,see://https://docs.swift.org/swift-book/LanguageGuide/StringsAndCharacters.htmlletmailtoString="""mailto:\[email protected]\[email protected],[email protected]\&[email protected]\&subject=Some%20Important%20Mail\&body=Hi%2C%0A%0A%0A"""ifletmailtoURL=URL(string:mailtoString){//IssuearequesttoopentheURL,see://https://developer.apple.com/documentation/uikit/uiapplication/1648685-openUIApplication.shared.open(mailtoURL,options:[:],completionHandler:nil)}

ThiscompletesintegrationofURLSchemeReplacementforiOS.



Appendix:DecisionTreeActivityDiagramThefollowingdiagramrepresentsthedecisiontreeforOpenURLwithschemereplacementasaUnifiedModelingLanguage(UML)Activitydiagram.

ActivityDiagram:OpenURLRequest

ApplicationCode

OpenURL

Scheme

Start

ApplicationPropertyList

No

Don'treplacescheme

Schemeconfiguredasreplaced?

No

UEMconfiguration

Yes

Yes

CustomSettings

configured?

Replacewithbuilt-inscheme

DLPsecuritypolicyactive?

Schemeismailtto?

Yes

No

No

Yes

DLPEnableComposing

Emailsetting… No

No

ReplacementforSchemeinsettings?

Replacewithcustomscheme

Yes

Yes

Diagram1:OpenURLwithschemereplacementactivitydiagram



Appendix:ConsoleUserInterfaceScreenCapturesThefollowingscreencapturesshowsthisfeature’sconfigurationinthemanagementconsole.Forstep-by-stepinstructions,seeConsoleConfiguration.

Screencapture2:ConsoleUserInterfaceDataLeakagePrevention

Screencapture3:ConsoleUserInterfaceCustomSettings



Appendix:ApplicationProjectScreenCaptureThefollowingscreencapturesshowsthisfeature’sconfigurationintheAppleXcodeintegrateddevelopmentenvironment.

Screencapture1:Configurationintheapplicationproject

(Ignoretheapplicationnameinthescreencapture,Captivity.)

ThisconfigurationcanbesetbyfollowingtheApplicationConfigurationinstructions.



DocumentInformationRevisionHistory30jun2020 FirstPublication.

LegalVMware,Inc.3401HillviewAvenuePaloAltoCA94304USATel877–486–9273Fax650–427–5001www.vmware.comCopyright©2020VMware,Inc.Allrightsreserved.ThisproductisprotectedbyU.S.andinternationalcopyrightandintellectualpropertylaws.VMwareproductsarecoveredbyoneormorepatentslistedathttps://www.vmware.com/go/patents.VMwareisaregisteredtrademarkortrademarkofVMware,Inc.anditssubsidiariesintheUnitedStatesandotherjurisdictions.Allothermarksandnamesmentionedhereinmaybetrademarksoftheirrespectivecompanies.

https://www.vmware.com/go/patents

url scheme replacement for ios - vdc-download.vmware.com · the configuration is in a property list...

Documents