Upload
others
View
10
Download
0
Embed Size (px)
Citation preview
BlackBerryDynamicsApplicationDeveloperGuide
BypassUnlock
4
8
13
17
Contents
IntroductionAvailabilityBackgroundBypassUnlockintheBlackBerryDynamicsauthenticationcycleDiagramNotesonauthenticationstateDivisionoftheuserinterfaceBypassUnlockPolicyBypassUnlockRegistrationSummaryofBypassUnlockconditions
ImplementationEssentialsStartwithacopyofaBypassUnlocksampleapplicationRegisterforaccesstothefeaturewhencompleteDeclareandimplementBypassscreensCreateaBypassUnlockpolicydefinitionDeclarethepolicysettingnameImplementtrackingoftheIdlelock
RegistrationWhentorequestreqistrationProcedureTemplatesExampleRegistrationMessagesWhentomakeasubsequentregistrationrequest
DiscussionUserExperienceandUserInterfaceBypassUnlockDataFurtheroptionsforadministratorsandendusersBypassversionsofscreensBypassUnlockisoptionalTransitionfromBypasstoProtectedAuthenticationDelegationFingerprintAuthentication
2of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
25
35
EnterprisePolicySettingDesignationofscreens
SampleApplicationsSampleBypassUnlockApplicationforAndroidSampleBypassUnlockApplicationforiOS
LegalNoticeLegalInformation
3of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
IntroductionBypassUnlockisafeatureforBlackBerryDynamicsapplications.Itallowsthescopeof theBlackBerryDynamics idle lock tobeconfigured.Partof theapplicationuserinterfacecanthenremainaccessibleaftertheidletimeouthasexpired.
Bydefault,thewholeofaBlackBerryDynamicsapplication’suserinterfaceiswithinthe scope of the idle lock. After the idle time out has expired, the BlackBerryDynamics unlock screen is superimposed on the application user interface. Thisdoesn’tapplytoscreensthatareconfiguredforBypassUnlock.Thosescreensareimmediatelyaccessible,withoutenduserauthentication.NotethatthosescreensarethereforenotprotectedbytheBlackBerryDynamicsidlelock.
SomegeneralusecasesofBypassUnlockare:
Notificationsthatrequireaswiftresponsebytheenduser,suchasaninboundcallinaVoiceOverIP(VoIP)application.Constantdisplayoflesssensitiveapplicationdata.Immediatestorageofnewdata,suchasanoteorphotograph,tothesecurestore.
Useof theBypassUnlock feature isanapplicationprivilege. Itmustbe requestedfrom BlackBerry, who will require that the application implements the featureaccordingtotherulesinthisdocument.
Availability
TheBypassUnlock feature is supportedby the followingsoftwaredevelopment kit(SDK)products:
GoodDynamicsSDKforAndroidversion2.3andlater.GoodDynamicsSDKforiOSversion2.3andlater.BlackBerryDynamicsSDKforAndroidversion3andlater.BlackBerryDynamicsSDKforiOSversion3andlater.
ThenameoftheproductwaschangedtoBlackBerryDynamicsinversion3.ThereisnoGoodDynamicsversion3,norBlackBerryDynamicsearlierthanversion3.
Background
For an introduction to BlackBerry Dynamics, see the Platform Overview forAdministratorsandDevelopers.Itispublishedhere:http://help.blackberry.com/en/good-control-good-proxy/current/
4of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
Notauthenticated.
Authenticated.
Idle.
BypassUnlockintheBlackBerryDynamicsauthenticationcycle
BypassUnlockappliesataparticularpointintheauthenticationcycle.
ABlackBerryDynamicsapplicationgoesthroughthefollowingauthenticationstatesatstart-up.
Theinitialstate.Theapplicationwillbeinthisstateuntiltheenduserhasenteredtheirsecuritypasswordforthefirsttimeafterstart-up.Notethattheendusercouldsupplyadifferentauthenticationsecret,insteadofapassword,ifaTrustedAuthenticatorisinuse.
Thestateimmediatelyaftertheuserhassuppliedtheirpassword,orotherauthenticationsecret.Dataonthedeviceisprotectedwithanencryptionkeythatisderivedfromthesecret.Afterthesecrethasbeensupplied,thekeyisderivedandtheruntimecanaccessitsmanagementdata,andanyapplicationdata.
Thestateenteredwhentheuserhasn’tinteractedwiththeapplicationfortheidletimeout.Thedurationoftheidletimeoutissetinthemanagementconsole,asasecuritypolicysetting.TheruntimelockstheapplicationuserinterfacewhentheIdlestateisentered.
BypassUnlockappliesintheIdlestateonly.
Diagram
Theabovestatesareillustratedinthefollowingdiagram.
5of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
Bypass.
Protected.
Notesonauthenticationstate
Ifthedeviceisswitchedoffandon,andthentheapplicationisstartedagain,itwillbebackintheinitialstate:Notauthenticated.Thesameistruewhentheapplicationisstartedafterhavingbeenunloadedfrommemory.Theapplicationcouldbeunloadedby thedeviceoperatingsystemto release resources,or if itcrashes,or if theuserchoosestoterminateit.
BypassUnlockdoesn’tapplyintheNotauthenticatedstate.Forexample,itdoesn’tapply in thecasethat theapplication isunloadedfrommemoryandthenrestarted.Showing any screen when not authenticated will cause the unlock screen to bedisplayed.
Divisionoftheuserinterface
For the purposes of Bypass Unlock, the user interface of a BlackBerry Dynamicsmobileapplicationisdividedintotwosetsofscreens.
ScreensthatcouldbedisplayedeveniftheapplicationuserinterfaceislockedbyBlackBerryDynamics,intheIdlestate.
Allotherscreens,whichwillneverbedisplayedwhentheapplicationuserinterfaceislocked.
BypassUnlockPolicy
Bypass Unlock can be allowed or disallowed by enterprise policy. This isimplemented using the BlackBerry Dynamics Application Policies feature.(ApplicationPoliciesaresometimesknownasApplication-SpecificPolicies.)
The end user of a BlackBerry Dynamics application is always associated with anenterprise,byactivation.Theenterprisecansetanumberofpoliciesthatcontroluseoftheapplicationbytheenduser,includingallowingordisallowingBypassUnlock.
If the enterprise disallows Bypass Unlock then Bypass screen designations areignoredandevery screen is treatedasaProtectedscreen.Theuser interfacewillthen be locked when in the Idle state, regardless of which application screen isdisplayed.
BypassUnlockRegistration
Access to Bypass Unlock is restricted and must be requested from BlackBerry.ApplicationsthataregrantedaccesstoBypassUnlockareregisteredbyBlackBerry,andeachissuedauniqueregistrationmessage.Themessagemustbeembeddedintheapplicationdeclaration,atbuild-time.
6of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
SummaryofBypassUnlockconditions
TheconditionsfordisplayofascreeniftheapplicationisintheIdlelockedstateare:
TheparticularscreenhasbeenmarkedforBypassUnlockintheapplicationdeclaration.Theenduserhasauthenticatedatleastoncesincetheapplicationstarted.BypassUnlockisallowedbyenterprisepolicy.AvalidBypassUnlockregistrationmessageisembeddedintheapplication.
7of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
ImplementationEssentialsTo implement Bypass Unlock in your application, you would typically do thefollowing:
DeclareandimplementyourBypassscreens.CreateaBypassUnlockpolicydefinitionforyourapplication.ImplementtrackingoftheIdlelockstate.
Eachoftheseitemsisdetailedinasub-section,seebelow.
StartwithacopyofaBypassUnlocksampleapplication
ThesoftwaredevelopmentkitsformobileplatformsthatsupportBypassUnlockeachcomewithasampleapplication.AcopyoftheBypassUnlocksampleapplicationcanbeusedasastartingpointforyourownimplementation.
Access to the Bypass Unlock feature is restricted and requires registration of theapplication identifier,andotherdetails.Thesampleapplications’ identifiersarepre-registered, and a signed registration message is embedded in their applicationdeclarations.
Ifthereisn’tavalidBypassUnlockregistrationmessageembeddedintheapplicationdeclaration,everyscreenwillbe treatedasaProtectedscreen.Theuser interfacewill thenbelockedwhenintheIdlestate,regardlessofwhichapplicationscreenisdisplayed.
Registerforaccesstothefeaturewhencomplete
When your implementation is finished, or nearly finished, request access to theBypassUnlockfeatureforyourapplication.
Theprocedureforregistrationisdocumentedinaseparatesection,below.
Whenregistrationiscomplete,stopusingtheidentifiersoftheBypassUnlocksampleapplications and use the official identifiers of your application instead. TheapplicationwillthenutiliseBypassUnlockandcanbereleasedtoproductionorbeta.
8of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
DeclareandimplementBypassscreens
Declare which screens are Bypass in your application. You might also need toimplement new screens. The possible need for new screens is discussed in theDiscussionsection,below.
Declarationsanduserinterfaceimplementationsareplatformspecific.
InanAndroidapplication,aBypassscreenwillbeanActivity.
Add a meta-data tag to the declaration of each Bypass Screen in theAndroidManifest.xmlfile,asshowninthefollowingsnippet.
<activity
android:name=".InCallActivity"
android:configChanges="orientation|keyboardHidden|screenSize">
<!-- Declare this Activity as a Bypass Screen. -->
<meta-data android:name="com.good.gd.bypassunlock"
android:value="true"/>
</activity>
Any mechanisms for launching an Activity can be used to display a Bypassscreen.Forexample,thefollowingsnippetshowshowtolaunchasachildActivity.
Intent intent = new Intent(ParentActivity.this, BypassActivityName.class);
intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
startActivity(intent);
InaniOSapplication,aBypassscreenwillbeaViewController.
List the View Controller class names for Bypass Screens in a property in theInfo.plistfile,asshowninthefollowingsnippet.
<key>GDBypassUnlockViewControllers</key>
<array>
<string>BPIncallViewController</string>
</array>
AViewControllerthatcanbepushedontotheuserinterfacenavigationstackcanbeaBypassscreen. Inprogramming terms, thismeansa UIViewControllerinstance that could be passed successfully to the UINavigationControllerpushViewControllerfunction.
AnyofthefollowingmechanismscanbeusedtodisplayBypassscreens.
FunctionsintheUIKitprogramminginterface,suchas:UIViewControllerpresentViewController:animated:completion:Seguewithmodalpresentation,configuredinastoryboard.Programmaticsegue,suchas:UIViewControllerperformSegueWithIdentifier:sender:
9of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
CreateaBypassUnlockpolicydefinition
Define a custom application policy that will control use of Bypass Unlock by endusers.
Create anApplication Policies definition file, if your application doesn’t alreadyhaveone.For an introduction to Application Policies see the technical brief, which ispublishedontheapplicationdeveloperportalhere:https://community.good.com/docs/DOC-1543
AddasettingfortheBypassUnlockpolicy.Thefollowingsnippetshowsanexamplesettingdefinition.
<setting name="GD_SDK_Security_AllowBypassUnlock" >
<checkbox>
<key>GD_SDK_Security_AllowBypassUnlock</key>
<label
>Allow parts of the user interface to be displayed when
idle lock is in place.</label>
<value>false</value>
</checkbox>
</setting>
Intheabovesnippet,thenameofthesettingisGD_SDK_Security_AllowBypassUnlock.
IncludethesettinginthestructuralpartoftheApplicationPoliciesfile.Thefollowingsnippetshowsanexampleofthestructuralpartofthedefinition.
<pview>
<pview type="tabbed" key="BlackBerryDynamicsFeatures">
<title>BlackBerry Dynamics Features</title>
<pe ref="GD_SDK_Security_AllowBypassUnlock" />
<desc> - Incoming Call Screen</desc>
<desc> - In-Call Screen </desc>
</pview>
</pview>
NotethatalistofBypassscreensisincluded.Thelistwillappearinthepolicyseteditorinthemanagementconsole.
Checkthepolicysettingatruntime.
InanAndroidapplication,callthe GDAndroid getApplicationPolicyorgetApplicationPolicyStringmethodtogetthesettingsasacollectionorasaJavaScriptObjectNotation(JSON)string,respectively.
InaniOSapplication,callthe GDiOS getApplicationPolicyorgetApplicationPolicyStringfunctiontogetthesettingsasacollectionorJSONstring,respectively.
ThenameoftheiteminthecollectionorJSONstringwillbethesameasinthedeclaration.Intheaboveexample,itisGD_SDK_Security_AllowBypassUnlock.
10of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
Declarethepolicysettingname
Thenameof theBypassUnlockpolicysettingmustbedeclared, in theapplicationdeclarationfile.Applicationdeclarationfilesareplatformspecific.
InanAndroidapplication,addthedeclarationtothe settings.jsonfile.
Addasettinglikethefollowing:
"GDBypassUnlockPolicySetting": "GD_SDK_Security_AllowBypassUnlock"
Thesettingmustbeatthetoplevelofthehierachy.ThisisthesamelevelastheGDApplicationIDandGDApplicationVersionsettings.
InaniOSapplication,addthedeclarationtotheInfo.plistfile.
Addasettinglikethefollowing,intheXMLview:
<key>GDBypassUnlockPolicySetting</key>
<string>GD_SDK_Security_AllowBypassUnlock</string>
Inthepropertylistview,thesamedeclarationwouldappearlikethis:
Key Type Value
GDBypassUnlockPolicySetting String GD_SDK_Security_AllowBypassUnlock
Thesettingmustbeatthetoplevelofthehierachy.ThisisthesamelevelastheGDApplicationIDandGDApplicationVersionsettings.
In the above examples, the declared policy setting name isGD_SDK_Security_AllowBypassUnlock.Thisisalsothenameintheexamplesintheabove section, Create a Bypass Unlock policy definition. It is possible to use acustom name, in case GD_SDK_Security_AllowBypassUnlock is somehowunsuitableforyourapplication.ReplaceGD_SDK_Security_AllowBypassUnlockwithyourcustomnamewherever itoccurs in theapplicationpolicydefinition,and in theapplicationdeclaration.
11of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
ImplementtrackingoftheIdlelock
Trackwhen the idle lock is in place.Doing sowill enable the application to avoidattempting to display a Bypass-only screen if the application is idle locked andBypassUnlockisn’tallowedbypolicy.
In an Android application, when the idle timer expires, theGDAppEventListener instance onGDEvent method will be despatched aGDAppEventwiththefollowingcharacteristics:
ThegetEventType()accessorwillreturnGDAppEventNotAuthorized.ThegetResultCode()accessorwillreturnGDErrorIdleLockout.
InaniOSapplication,whentheidletimerexpires,the GDiOSDelegate instancehandleEvent: function will be despatched a GDAppEvent with the followingpropertyvalues:
typeGDAppEventNotAuthorized.codeGDErrorIdleLockout.
If the application attempts to open a Bypass screen when Bypass Unlock isdisallowed, the Bypass designation will be ignored and the unlock screen will besuperimposed.
12of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
RegistrationAccess to Bypass Unlock is restricted and must be requested from BlackBerry.ApplicationsthataregrantedaccesstoBypassUnlockareregisteredbyBlackBerry,andeachissuedauniqueregistrationmessage.Themessagemustbeembeddedintheapplicationdeclaration,atbuild-time.
Whentorequestreqistration
YoushouldrequestaccesstotheBypassUnlockfeatureforyourapplicationtowardstheendofyourinitialimplementationofthefeature.
Procedure
RegisteryourapplicationforaccesstoBypassUnlockasfollows.
1. SendaBypassUnlockaccessrequest.
Send an email message to the Bypass Unlock Registrar at BlackBerry, at thefollowingaddress:[email protected]
Includethefollowing.
IfthereisanAndroidapplication,thenthe settings.jsonandAndroidManifest.xmlfiles.
IfthereisaniOSapplication,thentheInfo.plistfile.
TheApplicationPoliciesdefinitionXMLfile.
CompletedBypassUnlockrequestform,whichwillsummarisethefollowing:
Typeofapplication.WhatdataappearsoneachBypassscreen.Thescreenswillhavebeenlistedinthefilesmentionedabove.HowtheapplicationuserinterfacebehavesdifferentlyifBypassUnlockisallowedanddisallowedbytheenterprise.BypassUnlockoptionsfortheenterpriseadministratorandenduser,ifany.
Templatesfortheemailmessageandformtextfilearegivenbelow.
2. Answeranyquestionsfromtheregistrar.
The registrarmay send you questions by reply. In general, the answers to thequestionsshouldbeaddedtotheappropriatesectionintherequestformtextfile.
Theregistrarmayalsorequestchangesinyourapplication,forexampleremovingormakingoptionalthedisplayofparticulardataitemsonaBypassscreen.
13of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
3. Buildtheapplicationwithmodifiedapplicationdeclarationsfromtheregistrar.
When all changes have been made, the registrar will issue a Bypass Unlockregistrationmessage.Theformofthemessagewillbesomesigneddatathatyouinsert into your application’s settings.json or Info.plist files. Some exampleregistrationmessagesaregivenbelow.
Templates
Youcanusethefollowingastemplatesforyouraccessrequest.
Templatefortheaccessrequestemailmessage.
To:[email protected]:BypassUnlockaccessrequest
HelloBypassUnlockRegistrar,
Please can you grant access to the Bypass Unlock feature for my BlackBerryDynamicsapplication.Thefollowingfilesareattachedtothismessageaspartoftherequest.
Thesettings.jsonandAndroidManifest.xmlfilesfrommyapplicationforAndroid.TheInfo.plistfilefrommyapplicationforiOS.TheApplicationPoliciesdefinitionXMLfileformyBlackBerryDynamicsapplication.AcompletedBypassUnlockrequestform,inaplaintextfile.
Bestregards,<YourName>.<Yourcontactdetails.>
14of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
Template for the Bypass Unlock request form text file, mentioned in the emailmessagetemplateabove.
BypassUnlockRequestForm
This text file contains the details for the request email message to which it isattached.
Typeofapplication:<Examples:VoiceoverIP,orBusinessDashboard.>
DatadisplayedinBypassUnlock:
Screen:<Activityclassname,forAndroid,orViewControllerclassname,foriOS.Example:InboundCallBypassViewController>Data:<Listthedataitemsdisplayedonthescreen.Ifthereareoptionsfortheenterpriseadministratororenduser,listthemaximalsetofdataitemshereandnotebelowwhattheoptionsare.Example:
Displaysanotificationthatthereisaninboundcall.Thenumberofthecallingparty,optionally.Thenameandcompanyaffiliationofthecallingparty,optionally.
IncludetheScreenandDatainformationforeachBypassScreenseparately.>
Userexperiencedifferences:<StatehowtheuserexperiencediffersifBypassUnlockisallowedanddisallowedbytheenterprise.Example:If BypassUnlock is allowed, when the end user receives a phone call and theapplication is in the Idle locked state, a variant of the inbound call notificationscreenisdisplayed.>
Options:<List the options available to the enterprise administrator and end user, if any.Example:Theenterpriseadministratorand theendusercanchoosewhichdata itemsaredisplayed on the Bypass inbound call notification screen, see above. The enduser can select not to display data items that are permitted by the enterpriseadministrator.>
15of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
ExampleRegistrationMessages
ThefollowingisasampleBypassUnlockregistrationmessageforAndroid.Itwouldbeinsertedintotheapplication settings.jsonfile.Thesignaturehasbeenshortenedforconvenience.
"GDPermissions": [ { "Signature": "0b9aeff6...1ced54863754d9", "SignatureScheme": "RSAv1", "Permission": { "nativeApplicationId": "com.good.example.sdk.bypassunlock", "GDApplicationId": "com.good.example.sdk.bypassunlock", "BypassUnlockPermission": "1" } }]
Thefollowing isasampleBypassUnlockregistrationmessagefor iOS. Itwouldbeinserted into the application Info.plist file. The signature has been shortened forconvenience.
<key>GDPermissions</key><array> <dict> <key>Permission</key> <dict> <key>BypassUnlockPermission</key> <string>1</string> <key>GDApplicationId</key> <string>com.good.example.sdk.bypassunlock</string> <key>nativeApplicationId</key> <string>com.good.example.sdk.bypassunlock</string> </dict> <key>Signature</key> <string>0b9aeff...ced54863754d9</string> <key>SignatureScheme</key> <string>RSAv1</string> </dict></array>
Whentomakeasubsequentregistrationrequest
Theregistrationmessagegenerallyremainsvalidthroughupdatestoyourapplicationand through new versions of the SDK. However, you will need to request accessagainif:
Thenativeapplicationidentifierchanges,i.e.thepackagename,forAndroid,orthebundleidentifier,foriOS.Theentitlementidentifier(generallyknownastheGDApplicationIdentifier,orGDAppID)changes.AnewBypassscreenisadded.AdditionaldataitemsareaddedtoanexistingBypassscreen.ThereisanyothersubstantialchangetotheBypassUnlockaspectoftheapplication.
16of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
DiscussionSome points arising from the implementation tasks, above, are discussed in thefollowing.
UserExperienceandUserInterface
Youcouldbeginyourimplementationbydecidingwhichpartsoftheuserexperience(UX)ofyourapplicationwillbenefitfromBypassUnlock.Forexample,onepartofaVoIPuserexperiencethatwouldbenefitcouldbeansweringacall.
EachpartoftheUXtowhichBypassUnlockwillapplymustbeisolatedinaseparatescreen in the user interface (UI). For the different mobile platforms, a screencorrespondsto:
AnActivity,inanAndroidapplication.AViewController,inaniOSapplication.
Youmight have to create newUI screens, if any part of theUX towhich youwillapplyBypassUnlockisn’talreadyisolatedonaseparatescreen,orsetofscreens.
ThepartoftheUXtowhichBypassUnlockwillapplymightalreadybeonaseparatescreen,inwhichcaseyouwon’thavetocreateanynewscreens.Forexample,inaVoIPapplicationtheremightalreadybeaseparateInboundCallscreen.
BypassUnlockData
There are a number of approaches you can take to the presentation of enterprisedataonaBypassscreen.
NodataonBypassscreens.
ThemostsecureapproachcouldbetodisplaynodataonBypassscreens.ThisissimplebutmightleadtoaworseUXinsomeapplications.Thefollowingexamplesillustratethisapproach.
TheInboundCallscreeninaVoIPapplicationalertstheuserthatthereisaninboundcallbutdoesn’tincludeanyinformationaboutthecaller.Theuserwouldthenhavetomakeanuninformeddecisiontoacceptorrejectthecall.AnapplicationforfieldengineerscouldhaveaBypassscreen,theUtilitiesscreen,fromwhichtheusercanopenthedevicecamera.Iftheusertakesapicture,theimagedataiswrittentothesecurestore,andtheapplicationreturnstotheUtilitiesscreen.ThereisnowayfortheusertoviewcapturedimagesfromaBypassscreen,norinthenativephotogalleryapplication.Anapplicationfornote-takingcouldhaveaBypassscreen,theQuickNotescreen,onwhichtheusercanwritethemselvesatextnote.Whentheusersavesthenote,itiswrittentothesecurestore,andthescreeniscleared.ThereisnowayfortheusertoviewsavednotesfromaBypassscreen.
17of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
NoenterprisedataonBypassscreens.
Alesssecureapproachthendisplayingnodataatallwouldbetodisplaynodatathatcamefromtheenterprise.
Thefollowingexamplesillustratethisapproach.
TheInboundCallscreeninthepreviousexamplecoulddisplaythecaller’sphonenumber.Itwouldn’tcomparethecaller’snumbertothenumbersintheuser’senterpriseaddressbook,sowouldn’tdisplaythenameorcompanyaffiliationofthecaller.TheUtilitiesscreeninthepreviousexamplecoulddisplayacountofthenumberofphotoscaptured,andthetimeofthelastcapture.TheQuickNotescreeninthepreviousexamplecoulddisplayacountofthenumberofnotessaved,andthetimeofthelastsave.
LessvaluableenterprisedataonBypassscreens.
A less secure approach than displaying no enterprise datawould be to displayenterprise data that is somehow less valuable than that in themain part of theapplicationUI.Dependingonwhattypeofenterprisedatatheapplicationhandles,oneormoreofthefollowingmightapply.
Summariseddataislessvaluablethandetaileddata.Olddataislessvaluablethannewdata.
Thefollowingexamplesillustratethisapproach.
Anapplicationforworkflowcoulddisplaythenumberofoutstandingitemsintheuser’sinbox,andthenumberofitemsforwhichtheuserisawaitingactionsbyothers.Anapplicationwithaprojectstatusdashboarddisplaysinformationfromyesterday,orfromthelasttimetheuserauthenticated.
LimitedenterprisedataonBypassscreens.
Anotherapproachthatislesssecurethandisplayingnoenterprisedatawouldbetodisplayaverylimitedsubsetofenterprisedata.
Thefollowingexamplesillustratethisapproach.
TheInboundCallscreenintheearlierexamplescoulddisplaythenameofthecaller,butnotanyothernames.TheUtilitiesscreenintheearlierexamplescoulddisplaythelastphototaken,butnotanyothers.Theworkflowapplicationinthepreviousexamplecoulddisplaythenewestitemintheuser’sinbox,butnotanyotheritems.
18of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
Furtheroptionsforadministratorsandendusers
Incaseitisn’tobviouswhichoftheseappliesbesttoyourapplication,youcouldgiveoptionstotheenterpriseadministrator,ortotheenduser,ortoboth.
For example, the enterprise administrator could have an option to select whatinformation is shownon the InboundCall screen in theaboveexamples.Theendusercouldalsohaveanoption.
Ifyougiveoptionstoboththeadministratorandtheenduser,theendusermustberestrictedtoselectingamoresecuresettingthantheadministrator.Forexample,theadministratormightselecttoshowthephonenumberofaninboundcallerinaVoIPapplication. The end user could still select to show nothing, but couldn’t select toshowthecaller’sname.
OptionsfortheenterpriseadministratorwouldbeimplementedasApplicationPolicysettings. Options for the end user would be implemented in the settings orpreferencesUIinthemobileapplication.
Bypassversionsofscreens
WhicheverapproachyoutakemightrequirethecreationofBypassUnlockversionsofexistingUIscreens.
Forexample,iftheenduserofaVoIPapplicationhappenstobeauthenticatedandactivewhen they receive a call, a full InboudCall screen could be displayed.Thescreencouldshow thenameandcompanyaffiliationof thecaller,andcouldhaveobtainedthatinformationfromenterprisedata.But,iftheapplicationUIhadbeenidlelockedatthetimeofthecall,alimitedversionofthescreencouldbeshowninstead.ThefullscreenwouldbeaProtectedscreen;thelimitedversionwouldbeaBypassscreen.
Theapplicationcantrackthefollowingconditions:
Idlelockisineffect.BypassUnlockisallowedbytheenterprise.
If both conditions are met at the time the call is received, the application woulddisplay the limited Bypass screen. Otherwise, it would display the full Protectedscreen.Notethattherewouldbenopoint indisplayingthelimitedscreenifBypassUnlockisn’tallowed.Theenduserwouldhavetoauthenticatetoviewthescreeninthatcase,sotheymightaswellbeshownthefullscreen.
BypassUnlockisoptional
The enterprise will always have the option to disallow Bypass Unlock for yourapplication. The UI of your application mustn’t depend on Bypass Unlock alwaysbeingallowed.
19of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
TransitionfromBypasstoProtected
IfyourapplicationattemptstodisplayaProtectedscreenwhentheUIislocked,theunlockscreenwillbesuperimposed.Thatstillapplies ifaBypassscreen iscurrentwhen the attempt to display a Protected screen is made. The transition from aBypass screen to aProtected screen is a special case that should be handled byyourapplication.
The transition from Bypass UI to Protected can be handled with the folowingimplementation.
Tracktheidlelock.
Yourapplicationcanbenotifiedofstatechanges, includingtheexpiryof the idletimeout.Theruntimedispatchesaneventeverytimethestatuschanges.Forthedifferentmobileplatforms:
Androidapplicationscanincludea GDAppEventListenerinstance.Whentheidletimeoutexpires,thelistener onGDEventmethodwillbeinvokedandpasseda GDAppEventwiththefollowingcharacteristics:
ThegetEventType()accessorwillreturnGDAppEventNotAuthorized.ThegetResultCode()accessorwillreturnGDErrorIdleLockout.
iOSapplicationscanincludeaGDiOSDelegateinstance.Whentheidletimeoutexpires,thedelegate handleEvent:functionwillbeinvokedandpasseda GDAppEventwiththefollowingpropertyvalues:
typeGDAppEventNotAuthorized.codeGDErrorIdleLockout.
Whenyourapplicationisnotifiedof idle lock,setaninternalflag,andputoneorbothofthefollowingintoeffect.
Highlightoptionsthatwillleadtotransition.
Forexample,showapadlockiconbyanybuttononaBypassscreenthatopensaProtectedscreen.
IftheBypassscreenispartofthemainUI,andcouldbeshownwhenthereisnoidle lock ineffect, then thehighlightshouldonlybeshown if thereactually isanidlelock.
Warntheuserandgivethemacanceloptionbeforetransition.
Forexample,iftheuserpressesabuttononaBypassscreenthatwouldopenaProtectedscreen,showamessagelike“Authenticationwillberequired”withOKandCanceloptions.
Thesameadviceappliestothewarningastothehighlightinthepreviouspoint.Acanceloptionneedonlybeofferedifanidlelockactuallyisineffect.
20of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
InthescenariothattheapplicationUIislockedforinactivity,andaBypassscreenisopen,andtheuserselectsanoptionthatwouldopenaProtectedscreen,theunlockscreen will be superimposed. There won’t then be any option for the end user tocanceltheunlockandreturntotheBypassscreen.
Theaboveimplementationissuggestedasawaytoavoidapooruserexperienceinthesescenarios.
AuthenticationDelegation
Authentication of the end user can be delegated from one application to another.This feature,authentication delegation, is controlled by enterprise policy. Ifauthentication delegation is in use, any delegating application might yield theforegroundtothedelegatewhentheidletimeoutexpires.ThiscouldhaveanimpactonanapplicationthatusesBypassUnlock.
Considerthefollowingscenario:
Anenduserisrunningyourapplicationinforeground.Authenticationdelegationisspecifiedbyenterprisepolicy,toanapplicationotherthanyours.Theidletimeoutexpires.
Whatwillhappenisthattheotherapplicationwillbebroughttotheforeground,andwill show the unlock screen. If your application then attempts to show a Bypassscreen, nothing will appear to the user, because the other application will be inforeground.Notethatthescenarioisunlikelytohappenintypicalusage.
If theapplication is in foreground, then theuserwill probably be interactingwith itandtheidletimeoutwon’texpire.Also,theidletimeoutwouldgenerallybelongerthan the device’s native screen time out. This means that the application userinterfacewillalreadybehiddenwhentheidletimeoutexpires.
You can reduce the likelihood of a poor user experience in the authenticationdelegation scenario, by tracking the native screen state.When your application ishiddenbyexpiryof thenativescreentimer, immediatelydisplayaBypassscreenifthere is one that is suitable to the current screen.When the hidden state of yourapplicationiscleared,checktheidlelock.
Iftheidlelockisn’tinplace,youcandisplaytheoriginalscreenthatwasopenwhenyourapplicationwashidden.Iftheidlelockisinplace,donothingandleavetheBypassscreendisplayed.
21of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
FingerprintAuthentication
Theproductfor iOSsupportsuseofTouchIDforauthenticationoftheenduser, incertainsituationsandascontrolledbyenterprisepolicysettings.Itispossiblethatthedevicewillsuperimposeapromptfortheusertoauthenticatewithafingerprintevenwhen a Bypass screen is displayed. This cannot be controlled by BlackBerryDynamics,norbyyourapplicationcode.
EnterprisePolicySetting
Youmustgive theenterpriseadministrator theoption todisallowBypassUnlock inyourapplication.ImplementthisasanApplicationPolicy.
Implementationhasthefollowingparts.
CreateanApplicationPoliciesdefinitionfile,ifyourapplicationdoesn’thaveone.
Incaseyourequirean introduction to theApplicationPolicies feature, there isatechnicalbriefontheapplicationdeveloperportalhere:https://community.good.com/docs/DOC-1543
Thebriefcontainsreferencestomoretechnicalanddetailedresources,includingtheapplicationprogramminginterfacereferences.
AddadefinitionfortheBypassUnlockPolicysettingtoyourApplicationPolicyfile.
The policy setting must have a number of characteristics, as shown in thefollowingXMLsnippet.
<!-- Bypass Unlock Policy setting ============================ The following setting controls whether Bypass Unlock is allowed or disallowed. It must be a checkbox setting.--><setting name="GD_SDK_Security_AllowBypassUnlock" ><!-- The name attribute in the preceding tag must have the same value as the GDBypassUnlockPolicySetting in the settings.json or Info.plist file.--> <checkbox> <key>GD_SDK_Security_AllowBypassUnlock</key> <!-- The key must have the same value as the name attribute in the setting tag. --> <label >Allow parts of the user interface to be displayed when idle lock is in place.</label> <value>false</value> <!-- The default, above, must be that Bypass Unlock isn't allowed. --> </checkbox></setting>
22of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
IncludethesettinginthestructuralpartoftheApplicationPoliciesfile.
The structural part of the file, i.e. the top-level pview tag, defines how thesettingswillbearrangedinthecollectionthatismadeavailabletotheapplicationcodeby the runtime.Everydefinedsettingmustappear in the structural part ofthefile.
The structural part also defines how settings will appear to the enterpriseadministratorinthemanagementconsolepolicyseteditor.Itisbestpracticetolistthe Bypass screens in description text, so that the enterprise administrator canmakeaninformeddecisionaboutallowingBypassUnlock.
Thefollowingsnippetisanexampleofthestructuralpartofthedefinition.
<pview>
<! -- Rest of the Application Policies go here. -->
<!-- Separate tab for features, like Bypass Unlock. --> <pview type="tabbed" key="BlackBerryDynamicsFeatures"> <title>BlackBerry Dynamics Features</title> <pe ref="GD_SDK_Security_AllowBypassUnlock" /> <!-- The ref attribute in the preceding tag must have the same value as the name attribute of the setting tag.
Following is a list of Bypass screens, for the benefit of the enterprise administrator. --> <desc> - Incoming Call Screen</desc> <desc> - In-Call Screen </desc> </pview></pview>
CheckthepolicybeforeshowingyourBypassscreens.
If your application attempts to display aBypass screen butBypassUnlock isn’tallowed by the enterprise, then the unlock screen will be superimposed on it.Check the Bypass Unlock Policy setting with the normal Application Policyprogramminginterface.Forthedifferentmobileplatforms:
InanAndroidapplication,callthe GDAndroid getApplicationPolicyorgetApplicationPolicyStringmethodtogetthesettingsasacollectionorasaJavaScriptObjectNotation(JSON)string,respectively.
InaniOSapplication,callthe GDiOS getApplicationPolicyorgetApplicationPolicyStringfunctionstogetthesettingsasacollectionorJSONstring,respectively.
Thepolicysettingwillbe in thesetting thatyoudefined in theApplicationPolicyfile. In the above example, it is the GD_SDK_Security_AllowBypassUnlockelement.
23of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
Designationofscreens
DesignatetheBypassscreensinyourapplicationasfollows.
InanAndroidapplication,thedesignation ismadeinthemanifest. Intheactivitytag of each Bypass screen, insert a meta-data tag with the followingcharacteristics:
android:name="com.good.gd.bypassunlock"
android:value="true"
Inan iOSapplication, thedesignation ismade in the Info.plist file, inapropertywiththefollowingcharacteristics:
Key:GDBypassUnlockViewControllers.Type:Arrayofvalues,oneperBypassscreen.Arrayelementtype:StringcontainingtheclassnameofaViewControllerthatrepresentsaBypassscreen.
TherearecodesnippetsintheImplementationEssentials,above.
24of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
SampleApplicationsEach of the SDK distributions that supports Bypass Unlock comes with a sampleapplication.Theapplicationsarepre-registeredwithaccesstothefeature.Theycanbeusedasstartingpointsforimplementationinyourapplication.
EachofthesamplecodeprojectsincludesanApplicationPoliciesdefinitionXMLfile.
SampleBypassUnlockApplicationforAndroid
ThefollowingscreencaptureimagesarefromtheBypassUnlocksampleapplicationforAndroid.
MainActivityscreen.
TheMainActivity isaProtectedscreen. Itgives instructionshow todemonstratetheBypassUnlockfeatureintheapplication,andshowsadiagnosticdumpofthecurrentapplicationpolicysetting.
25of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
IncomingEventActivityscreen.
TheIncomingEventActivityisaBypassscreen.Itdemonstratesnotificationoftheenduserduring idle lock.Theswitchat thebottomof thescreenshowsthe idlelockstate.
26of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
InCallActivityscreen.
TheInCallActivity isalsoaBypassscreen.Itdemonstratesofferingtheenduseranactionwhentheapplication is locked.Theswitchat thebottomof thescreenshows the idle lockstate.Note that there isanoption for theuser toopen theirContacts.
27of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
InCallActivitywarningbeforeattemptingtoopenContacts.
If theuserselects toopen theirContacts fromthe InCallActivityscreen,and theapplication is idle locked, then a warning is displayed. This is shown in thefollowingscreencaptureimage.
Iftheusercancels,theapplicationreturnstotheInCallActivityscreen.Iftheuserproceeds,theywillhavetoauthenticate.Theuser’sContactswon’tbedisplayedunlesstheuserisauthenticated.
28of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
ContactsActivityscreen.
TheContactsActivityisaProtectedscreen.Itdisplaystheuser’sContacts.
29of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
SampleBypassUnlockApplicationforiOS
ThefollowingscreencaptureimagesarefromtheBypassUnlocksampleapplicationforiOS.
Mainscreen.
TheMainscreenisProtected.ItgivesinstructionshowtodemonstratetheBypassUnlock feature in the application, and shows a diagnostic dump of the currentapplicationpolicysetting.
30of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
IncomingCallscreen.
TheIncomingCallscreen isaBypassscreen. Itdemonstratesnotificationof theenduserduringidlelock.
Thisscreenisdisplayedinthesampleapplicationbythefollowingcode:[[BPCallManager sharedManager] simulateCall]
Theswitchatthebottomofthescreenshowstheidlelockstate.Thisistrackedbyreceiptofthe GDErrorIdleLockouteventinthe AppDelegate instance,andthen reflected in a property of the sharedManager object. The firstauthenticationoftheendusersincestart-upistrackedinanotherpropertyofthesameobject.Theobjectandpropertiescanbeaccessedasfollows:
Idlelockedstate: [BPCallManager sharedManager].appIdleLockedAuthenticatedstate:[BPCallManager sharedManager].appStarted
31of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
InCallscreen.
TheInCallscreenisalsoaBypassscreen.Itdemonstratesofferingtheenduseranactionwhentheapplication is locked.Theswitchat thebottomof thescreenshows the idle lockstate.Note that there isanoption for theuser toopen theirContacts.
Inthisscreencapture,theapplicationhappenstobeunlocked.
32of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
InCallwarningbeforeattemptingtoopenContacts.
If the user selects to open their Contacts from the In Call screen, and theapplication is idle locked, then a warning is displayed. This is shown in thefollowingscreencaptureimage.
If the user cancels, the application returns to the In Call screen. If the userproceeds,theywillhavetoauthenticate.Theuser’sContactswon’tbedisplayedunlesstheuserisauthenticated.
33of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
Contactsscreen.
TheContactsscreenisProtected.Itdisplaystheuser’sContacts.
Thisscreen is representedby the BPContactsViewController class.Therearetwowaystoopenthisscreen:
Fromthenavigationbar,bypressingtheContactsbutton,iftheapplicationisn’tlocked.FromtheContactsbuttonontheInCallscreen.Iftheapplicationislockedthentheuserwillhavetoauthenticate.
34of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock
LegalNoticeThisdocument,aswellasallaccompanyingdocumentsforthisproduct,ispublishedbyBlackBerryLimited(“BlackBerry”).BlackBerrymayhavepatentsorpendingpatentapplications, trademarks, copyrights, and other intellectual property rights coveringthesubjectmatterinthesedocuments.Thefurnishingofthis,oranyotherdocument,doesnotinanywayimplyanylicensetotheseorotherintellectualproperties,exceptasexpresslyprovidedinwrittenlicenseagreementswithBlackBerry.Thisdocumentisfortheuseoflicensedorauthorizedusersonly.Nopartofthisdocumentmaybeused, sold, reproduced, stored in a database or retrieval system or transmitted inany formor by anymeans, electronic or physical, for any purpose, other than thepurchaser’s authorized use without the express written permission of BlackBerry.Any unauthorized copying, distribution or disclosure of information is a violation ofcopyright laws. While every effort has been made to ensure technical accuracy,information in this document is subject to change without notice and does notrepresent a commitment on the part of BlackBerry.The software described in thisdocumentisfurnishedunderalicenseagreementornondisclosureagreement.Thesoftwaremaybeusedorcopiedonly inaccordancewith thetermsof thosewrittenagreements.Thedocumentationprovided issubject tochangeatBlackBerry’ssolediscretion without notice. It is your responsibility to utilize the most currentdocumentationavailable.BlackBerryassumesnodutytoupdateyou,andthereforeBlackBerry recommends that you check frequently for new versions. Thisdocumentation is provided “as is” and BlackBerry assumes no liability for theaccuracyorcompletenessofthecontent.ThecontentofthisdocumentmaycontaininformationregardingBlackBerry’sfutureplans,includingroadmapsandfeaturesetsnot yet available. It is stressed that this information is non-binding andBlackBerrycreatesnocontractualobligation todeliver the featuresand functionalitydescribedherein, andexpresslydisclaimsall theoriesof contract, detrimental relianceand/orpromissoryestoppelorsimilartheories.
LegalInformation
(c) Copyright 2017 BlackBerry Limited. Trademarks, including but not limited toBLACKBERRY,DYNAMICSandEMBLEMDesignarethetrademarksorregisteredtrademarks of BlackBerry Limited, its subsidiaries and/or affiliates, used underlicense,andtheexclusiverightstosuchtrademarksareexpresslyreserved.Allothertrademarksarethepropertyoftheirrespectiveowners.
35of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock