BlackBerry Dynamics Application Developer Guide: Bypass …...(Application Policies are sometimes...

transcript

BlackBerryDynamicsApplicationDeveloperGuide

BypassUnlock

Contents

IntroductionAvailabilityBackgroundBypassUnlockintheBlackBerryDynamicsauthenticationcycleDiagramNotesonauthenticationstateDivisionoftheuserinterfaceBypassUnlockPolicyBypassUnlockRegistrationSummaryofBypassUnlockconditions

ImplementationEssentialsStartwithacopyofaBypassUnlocksampleapplicationRegisterforaccesstothefeaturewhencompleteDeclareandimplementBypassscreensCreateaBypassUnlockpolicydefinitionDeclarethepolicysettingnameImplementtrackingoftheIdlelock

RegistrationWhentorequestreqistrationProcedureTemplatesExampleRegistrationMessagesWhentomakeasubsequentregistrationrequest

DiscussionUserExperienceandUserInterfaceBypassUnlockDataFurtheroptionsforadministratorsandendusersBypassversionsofscreensBypassUnlockisoptionalTransitionfromBypasstoProtectedAuthenticationDelegationFingerprintAuthentication

2of35BlackBerryDynamicsApplicationDeveloperGuide:BypassUnlock

EnterprisePolicySettingDesignationofscreens

SampleApplicationsSampleBypassUnlockApplicationforAndroidSampleBypassUnlockApplicationforiOS

LegalNoticeLegalInformation

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/

Notauthenticated.

Authenticated.

BypassUnlockintheBlackBerryDynamicsauthenticationcycle

BypassUnlockappliesataparticularpointintheauthenticationcycle.

ABlackBerryDynamicsapplicationgoesthroughthefollowingauthenticationstatesatstart-up.

Theinitialstate.Theapplicationwillbeinthisstateuntiltheenduserhasenteredtheirsecuritypasswordforthefirsttimeafterstart-up.Notethattheendusercouldsupplyadifferentauthenticationsecret,insteadofapassword,ifaTrustedAuthenticatorisinuse.

Thestateimmediatelyaftertheuserhassuppliedtheirpassword,orotherauthenticationsecret.Dataonthedeviceisprotectedwithanencryptionkeythatisderivedfromthesecret.Afterthesecrethasbeensupplied,thekeyisderivedandtheruntimecanaccessitsmanagementdata,andanyapplicationdata.

Thestateenteredwhentheuserhasn’tinteractedwiththeapplicationfortheidletimeout.Thedurationoftheidletimeoutissetinthemanagementconsole,asasecuritypolicysetting.TheruntimelockstheapplicationuserinterfacewhentheIdlestateisentered.

BypassUnlockappliesintheIdlestateonly.

Diagram

Theabovestatesareillustratedinthefollowingdiagram.

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.

SummaryofBypassUnlockconditions

TheconditionsfordisplayofascreeniftheapplicationisintheIdlelockedstateare:

TheparticularscreenhasbeenmarkedforBypassUnlockintheapplicationdeclaration.Theenduserhasauthenticatedatleastoncesincetheapplicationstarted.BypassUnlockisallowedbyenterprisepolicy.AvalidBypassUnlockregistrationmessageisembeddedintheapplication.

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.

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

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:

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.

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

<title>BlackBerry Dynamics Features</title>

<desc> - Incoming Call Screen</desc>

<desc> - In-Call Screen </desc>

</pview>

NotethatalistofBypassscreensisincluded.Thelistwillappearinthepolicyseteditorinthemanagementconsole.

Checkthepolicysettingatruntime.

InanAndroidapplication,callthe GDAndroid getApplicationPolicyorgetApplicationPolicyStringmethodtogetthesettingsasacollectionorasaJavaScriptObjectNotation(JSON)string,respectively.

InaniOSapplication,callthe GDiOS getApplicationPolicyorgetApplicationPolicyStringfunctiontogetthesettingsasacollectionorJSONstring,respectively.

ThenameoftheiteminthecollectionorJSONstringwillbethesameasinthedeclaration.Intheaboveexample,itisGD_SDK_Security_AllowBypassUnlock.

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.

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.

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:BlackBerryDynamicsRegistrar@blackberry.com

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.

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:BlackBerryDynamicsRegistrar@blackberry.comSubject: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.>

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

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.

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.

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.

Anapplicationforworkflowcoulddisplaythenumberofoutstandingitemsintheuser’sinbox,andthenumberofitemsforwhichtheuserisawaitingactionsbyothers.Anapplicationwithaprojectstatusdashboarddisplaysinformationfromyesterday,orfromthelasttimetheuserauthenticated.

LimitedenterprisedataonBypassscreens.

Anotherapproachthatislesssecurethandisplayingnoenterprisedatawouldbetodisplayaverylimitedsubsetofenterprisedata.

TheInboundCallscreenintheearlierexamplescoulddisplaythenameofthecaller,butnotanyothernames.TheUtilitiesscreenintheearlierexamplescoulddisplaythelastphototaken,butnotanyothers.Theworkflowapplicationinthepreviousexamplecoulddisplaythenewestitemintheuser’sinbox,butnotanyotheritems.

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.

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.

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.

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.

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

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

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

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.

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.

IncomingEventActivityscreen.

TheIncomingEventActivityisaBypassscreen.Itdemonstratesnotificationoftheenduserduring idle lock.Theswitchat thebottomof thescreenshowsthe idlelockstate.

InCallActivityscreen.

TheInCallActivity isalsoaBypassscreen.Itdemonstratesofferingtheenduseranactionwhentheapplication is locked.Theswitchat thebottomof thescreenshows the idle lockstate.Note that there isanoption for theuser toopen theirContacts.

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.

ContactsActivityscreen.

TheContactsActivityisaProtectedscreen.Itdisplaystheuser’sContacts.

SampleBypassUnlockApplicationforiOS

ThefollowingscreencaptureimagesarefromtheBypassUnlocksampleapplicationforiOS.

Mainscreen.

TheMainscreenisProtected.ItgivesinstructionshowtodemonstratetheBypassUnlock feature in the application, and shows a diagnostic dump of the currentapplicationpolicysetting.

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

InCallscreen.

TheInCallscreenisalsoaBypassscreen.Itdemonstratesofferingtheenduseranactionwhentheapplication is locked.Theswitchat thebottomof thescreenshows the idle lockstate.Note that there isanoption for theuser toopen theirContacts.

Inthisscreencapture,theapplicationhappenstobeunlocked.

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.

Contactsscreen.

TheContactsscreenisProtected.Itdisplaystheuser’sContacts.

Thisscreen is representedby the BPContactsViewController class.Therearetwowaystoopenthisscreen:

Fromthenavigationbar,bypressingtheContactsbutton,iftheapplicationisn’tlocked.FromtheContactsbuttonontheInCallscreen.Iftheapplicationislockedthentheuserwillhavetoauthenticate.

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.

BlackBerry Dynamics Application Developer Guide: Bypass …...(Application Policies are sometimes...

Documents