AT&T VERIFY CONNECT (V3.2.0) GETTING STARTED GUIDE FOR MOBILE SDK

Transcription

1 AT&T VERIFY CONNECT (V3.2.0) GETTING STARTED GUIDE FOR MOBILE SDK AT&T Verify Connect is powered by SecureKey Technologies Inc. briidge.net Connect service platform. No part of this document may be copied, modified or disseminated without permission of SecureKey and AT&T. AT&T and the AT&T logo are trademarks of AT&T Intellectual Property. SecureKey and briidge.net are trademarks of SecureKey Technologies. Other marks are property of their respective owners SecureKey Technologies Inc. and AT&T Intellectual Page 1 of 53

2 Document Control Change Record Date Revision Section(s) Editor Change Reference 27/11/ DH Initial Release 28/11/ Authenticate User DH Added use case for authenticate user. 05/01/ Integration Prerequisites 30/03/ SDK Methods: Enroll User Authenticate User VM DH Added instruction for Android applications using ProGuard Updated methods for v New global listeners Briidge.UserEnrollmentListener and Briidge.UserAuthenticationListener. Server APIs: Authenticate User (Init) Authenticate User (Result) Enroll User (Init) Enroll User (Result) Updated URL endpoints for v SecureKey Technologies Inc. and AT&T Intellectual Page 2 of 53

3 Table of Contents 1. Introduction About briidge.net Connect Audience Notation Integration Overview Server API briidge.net Connect URLs Integration Prerequisites Device Provisioning User Authentication Enroll User Authenticate User Device Authentication Authenticate Device Provision Device User Management APIs Get Paired Users per Device Unpair User from Device Change Crypto PIN EMV Card Services Card Read Authenticate with Card Key Management Inter-Channel Communication Server Reference API Reference Parameter Descriptions Page 3 of 53

4 1. Introduction 1.1 About Verify Connect and briidge.net Connect briidge.net Connect is a cloud-based multi-factor authentication service platform that provides customers the ability to strongly authenticate their users, and facilitate strong authentication. Verify Connect powered by bridge.net is the AT&T instance of the solution. The platform is designed to support many in-market devices today, enabling strong security across all delivery channels. 1.2 Audience This guide introduces several usage scenarios for the briidge.net Connect Mobile SDK. It is assumed the reader is familiar with JSON requests and objects. 1.3 Notation briidge.net Connect uses the following terms: Relying Party - to describe a person or organization that is interested in verifying and establishing the credential of another person using the briidge.net Connect platform. Crypto PIN (or Cryptographic PIN) - to describe the briidge.net Connect managed passcode. Use of passcode, QuickCode, and Crypto PIN may be used interchangeably. Page 4 of 53

5 2. Integration Overview To integrate the SecureKey briidge.net Connect platform with a Relying Party (RP) application involves the following: Integrating the briidge.net Connect SDK into your application client. The client integration process involves implementing callback functions in support of the SDK methods. The callback functions return either the applicable data or an identifier that will enable your application server to retrieve the data. Implementing server endpoints to communicate identifiers and statuses between your application server and client. Implementing JSON server endpoints to call and receive data from the briidge.net Connect Server. Note: In some cases, additional processing is required between the RP server and client to complete a request. The following diagram shows the logical communication lines between briidge.net Connect components and your application. Figure 1: briidge.net Connect System Overview Most requests involve both a client and server call to complete a transaction. Transactions can be initiated by calling either the briidge.net Connect Server API or briidge.net Connect SDK (depicted by side A in the diagram above) and then involves passing some data between the RP client and server to access the resulting data (depicted by side B in the diagram above). Finally, another call to the briidge.net Connect platform can be made to retrieve the resultant data. Page 5 of 53

6 A Represents communication lines between the RP and briidge.net Connect: Client calls can be made to the briidge.net Connect SDK, and Server calls can be made to the briidge.net Connect Server. B Represents communication lines between the RP application client and RP application server. 2.1 Server API The briidge.net Connect JSON API is a server-to-server API that facilitates initiation of functional briidge.net Connect methods. The following points are common to all calls described in this section: Transport Protocol HTTPS (or TLS 1.0+) is required for communication between the RP's web site and the briidge.net Connect server. Authentication is performed via a client X.509 certificate. Requests will use the POST method. JSON Requests Many of the requests exposed through the API provide parameters. These parameters are passed in JSON format in the body of the HTTP POST message. HTTP Responses The HTTP response code will report the status of the HTTP communication and no the status of the briidge.net Connect transaction. This means that all messages that are accepted and processed by the server will return an HTTP 200 status code. Responses provided with a 200 response code must be checked for an error element to determine if the request was successful. 2.2 briidge.net Connect URLs In the following sections, URLs will be shown with the host portion as HOST. HOST is a placeholder for the briidge.net Connect server hostname for the environment you are assigned. There are various briidge.net Connect environments for development and production. The appropriate host value to use for a particular purpose is provided by SecureKey. 2.3 Integration Prerequisites Prior to integration, ensure you have all development tools and components SecureKey Mobile SDK You will need the SecureKey Mobile SDK libraries as well as any dependencies for your platform. Consult the README file for detailed requirements (available with platform libraries). Page 6 of 53

7 Copy the SecureKey Mobile SDK files to the appropriate location to include them in your project. For example, if developing Android, copy skaplibobf-sandbox.jar to your lib folder and include it in your Eclipse project for Android development. Note: If using ProGuard to obfuscate your Android application, add the following lines to the end of the ProGuard configuration file (proguard-project.txt) to use the briidge.net Connect SDK: # Following warnings can be ignored -dontwarn com.samsung.android.** briidge.net Connect Server API Certificates RPs and the briidge.net Connect Administrator must exchange certificates to perform mutual authentication during server-to-server connections; a trusted connection using HTTPS (TLS 1.0+) must be established for the RP server to make API calls to the briidge.net Connect server. Authentication is performed via a client X.509 certificate Domain Name Registration As part of the on-boarding process, RPs must register their domain name with SecureKey to ensure the RP application is recognized by the briidge.net Connect server. This information is used to uniquely identify an RP and ensures that only registered domains are served by the briidge.net Connect server Using Sample RP Server To use the SDK samples as-is, you can download and run the Sample RP Server on a local Java App Server (such as Tomcat 7). This sample server provides full implementation for all briidge.net Connect Server APIs and exposes only the required subset to the sample client application. You can easily extend the sample code to add support for additional features. The Sample RP Server includes applicable certificates to establish trusted server-to-server connections with the briidge.net Connect server. The certificates are located under a resources/keystores folder, in a samplerp.jks file. 2.4 Device Provisioning All devices must be provisioned prior to use with the briidge.net Connect SDK. Provisioning a device enables briidge.net Connect to identify device specifications and assign a device identifier that is unique to the device and the requesting RP. The RP will use this device identifier in all device-related transactions performed on the briidge.net Connect platform. Note: Device provisioning can be completed during user enrollment (see Enroll User), or can be done separately (see Provision Device). Page 7 of 53

8 3. User Authentication Use briidge.net Connect as a first-factor form of authentication, or enhance an existing RP implementation to introduce second-factor or multi-factor authentication. The following section introduces briidge.net Connect Server APIs related to authentication. 3.1 Enroll User This method is used to perform several registration operations in one call. It enables you to: Add a user (if not registered with briidge.net Connect), Provision and register a device to the user, Select and set up authentication methods (for example, Passcode (QuickCode) or local authentication methods such as fingerprint and device pin), and Set a Passcode (QuickCode) for the user. The following sequence diagram illustrates the calls made to enroll a user: Page 8 of 53

9 Figure 2: Enrolling a user Procedure 1. Call briidge.net Connect Server Initialize the enrollment process by calling enroll. Pass a new or existing userid. The method to call is ENROLL: Where, HOST, is provided to you by SecureKey. The result is a transaction identifier, txnid, to be passed to the client application. 2. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 3. Call SDK Make a call to briidge.enroll. Ensure to pass the transaction identifier (txnid) obtained in previous steps and a class that implements the Briidge.EnrollListener interface. briidge.enroll(transactionid, new public void getcurrentactivity(getcurrentactivitycallback callback) public void verifypinrequested(final VerifyPinCallback callback) // Get Pin from user public void setupquickcode(final SetQuickCodeCallback callback) //The app should ask the user to enter a new quick code if(usercancels) callback.cancel();//in this case enrollcomplete will not be called. else public void enrollcomplete(int status) if (status == Briidge.STATUS_OK) // success else if (status == Briidge.STATUS_CONNECTIVITY_ERROR) // tell user that there is a connectivity error else if (status == Briidge.STATUS_FATAL_CONNECTIVITY_ERROR_UPDATE_SDK) Page 9 of 53

10 // tell user that there is a fatal connectivity // error that requires app developer to update sdk else // could not set the quick code (null, empty, server error, publc void selectauthenticationmethods( List<AuthenticationMethod> authenticationmethods, List<AuthenticationMethod> existingauthenticationmethods, SelectAuthenticationMethodsCallback callback) // Example of Passcode (QuickCode) Authentication // Note: The auth method is used only if it is in the authenticationmethods list callback.selectauthenticationmethods (Arrays.asList(AuthenticationMethod.QuickCodeAuthentication)); ); Note: If multiple authentication methods are available - for example, Passcode (QuickCode) and local authentication methods such as fingerprint or device pin - then the callback selectauthenticationmethodsrequested may be called for the client application to select the authentication methods to register. See the Mobile SDK reference for more details. 4. Call briidge.net Connect Server After a period of time, the RP can call the briidge.net Connect server to check on the status of enrollment and retrieve the corresponding device information, deviceinfo. Pass the same transaction identifier from previous steps. The endpoint for this call is ENROLL-DATA: Where, HOST, is provided to you by SecureKey. If enrollment was successful, the result will be a JSON object containing the device information: "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b-6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false Otherwise, an error is returned with error code and description. Page 10 of 53

11 3.2 Authenticate User This method is used to perform authentication of a user's device and user's selected authentication method (for example, Passcode (QuickCode) or local authentication methods such as fingerprint or device pin) in a single call. The following sequence diagram illustrates the calls made to authenticate a user: Prerequisites Figure 3: Authenticating a user User must be enrolled on the briidge.net Connect platform. For more information, see Enroll User. Note: Although RPs can make separate calls to the API (ADD-USER, ADD-DEVICE, and INIT-SET- PASSCODE), it is recommended that they use the enroll API for ease of use and to streamline code. Page 11 of 53

12 3.2.2 Procedure 1. Call briidge.net Connect Server to initiate Initiate the user authentication process by calling the authenticate server API. Pass an existing userid. The method to call is AUTHENTICATE: Where, HOST, is provided to you by SecureKey. The result is a transaction identifier, txnid, to be passed to the client application. 2. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 3. Call SDK Make a call to briidge.authenticate. Ensure to pass the transaction identifier (txnid) obtained in previous steps and a class that implements the Briidge.AuthenticateListener interface with the following callback methods: getcurrentactivity(getcurrentactivitycallback callback) If the registered authentication method is local fingerprint authentication, then use this callback to request the current UI activity. Note: This is only applicable for Samsung devices with TEE. quickcoderequested(final VerifyQuickCodeCallback callback) If the registered authentication method is Passcode (QuickCode), then use this callback to authenticate the user. For more information, see the selectauthenticationmethodsrequested callback for Enroll User. Implement code that prompts the user for their Passcode (QuickCode) and verify it by passing the Passcode (QuickCode) to VerifyQuickCodeCallback.verifyQuickCode. If the user cancels the request, call VerifyQuickCodeCallback.cancel(). authenticatecomplete(int status, String transactionid) Check the status of the result and if successful, pass the transaction identifier to your RP server to retrieve the result of the authentication. 4. Call briidge.net Connect Server to retrieve results Once the RP server receives the transaction identifier, txnid, they can call the briidge.net Connect server to confirm the results of the authentication. Page 12 of 53

13 The endpoint for this call is AUTHENTICATE-DATA: Where, HOST, is provided to you by SecureKey. If authentication was successful, the result will be a JSON object containing the user identifier and device information: "userid" : "user123", "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b-6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false Otherwise, an error is returned with error code and description. Page 13 of 53

14 4. Device Authentication 4.1 Authenticate Device Device authentication enables RPs to independently verify device specifications using briidge.net Connect. There are two options for performing device authentication: Requesting a transaction identifier to retrieve the resulting data from the briidge.net Connect server, or Requesting a signed JSON Web Token (JWS) that is returned directly to the client Transaction Identifier The following sequence diagram illustrates the calls made to authenticate a device. Figure 4: Authenticate Device Procedure 1. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); Page 14 of 53

15 2. Call SDK Make a call to briidge.authenticatedevice. Ensure to pass a class that implements the Briidge.AuthenticateDeviceListener interface. This callback function has only one method that requires implementing: briidge.authenticatedevice(authenticatedevicelistener( void authenticatedevicecomplete(int status, string txnid) //Check status //Pass txnid to server if request is successful ) 3. Call briidge.net Connect Server Obtain the results of the device authentication by passing the transaction identifier (txnid) in the call to your server. The method to call is DEVICE-INITIATED-GET-DEVICE: Where, HOST, is provided to you by SecureKey. The JSON body of the request is simply: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" If device validation is successful, the result is a JSON object containing the device information; otherwise, an error is returned. For example: "deviceinfo" : "softwareavailable": true, "nfc" : false, "deviceavailable" : true, "provisioned" : false, "setype" : "WEB_VSE", "deviceinterface" : "webvse", "id" : "webvse WEB_VSE" 4. Pass result to application client Complete the authentication by passing the results back to your application client. At this point, if the authentication was satisfactory, then the end user can be given access to the protected resource. That's it. Your application client now knows that it is running on the authenticated device. Page 15 of 53

16 4.1.2 JWT Token The following sequence diagram illustrates the calls made to authenticate a device using a JWT signed or encrypted assertion. Figure 5: Authenticate Device with JWT Procedure 1. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 2. Call SDK Make a call to briidge.assertdevice. Ensure to pass a class that implements the Briidge.AssertDeviceListener interface. This callback function has only one method that requires implementing: briidge.assertdevicecomplete(assertdevicelistener( void assertdevicecomplete(int status, string resultdata) //Check status //Pass txnid to server if request is successful ) 3. Interpreting Result The resultdata in the example code from the previous step is a signed JWT containing three (3) parts delimited by a period ("."): a header, a payload, and a signature. Page 16 of 53

17 The device information is contained in the payload under the key securekey.com/deviceinfo. "deviceinfo" : "softwareavailable": true, "nfc" : false, "deviceavailable" : true, "provisioned" : false, "setype" : "WEB_VSE" "deviceinterface" : "webvse", "id" : "webvse WEB_VSE" That's it. Your app now knows that it is running on the authenticated device. 4.2 Provision Device Provisioning a device enables briidge.net Connect to identify device specifications and assign a device identifier that is unique to the device and the requesting RP. The RP will use this device identifier in all device-related transactions performed on the briidge.net Connect platform. Note: Every device must be provisioned on first use. The following sequence diagram illustrates the calls made to provision a device Procedure 1. Initialize the SDK Figure 6: Initialize SDK and Provision Device Page 17 of 53

18 Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); Tip: Add a check after initialization to ensure all transactions are performed on a provisioned device. if (!briidge.isprovisioned()) //Request provision id through RP server. 2. Call briidge.net Connect Server Obtain a provisioning authorization code from the server to complete the provisioning. The method to call is GET-DEVICE-PROVISION-ID: Where, HOST, is provided to you by SecureKey. The result is a transaction identifier, txnid, to be used as the provisioning authorization code. Pass the authorization code to your application client to provision the device. "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" 3. Provision device Complete the provisioning by calling setprovisionid(). Pass the txnid as obtained by your server in the previous step. That's it. You application can now perform authentication. Page 18 of 53

19 5. User Management APIs briidge.net Connect offers user registration and management functions to enable RPs to set up user profiles in the cloud. RPs can securely store and access user information such as identifiers, phone numbers, and device information. Note: RPs can only access users that they have registered. Third party applications cannot directly access this data. The following sections describe the methods to register and access users; method typically do not involve user interaction and may not require an initiation request. 5.1 Get Paired Users per Device Getting a list of users paired to a device enables RPs to track which users can set up a Passcode (QuickCode) or perform other device-related operations such as device-based authentication Procedure 1. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 2. Call SDK Make a call to briidge.getpairedusers. Ensure to pass a class the implements the GetPairedUsers interface. This interface has one callback method that needs to be implemented: briidge.getpairedusers( new public void getpaireduserscomplete(int status, Vector users) if(status!= Briidge.STATUS_OK) // check which status, possibly try again // or maybe authentication problems else Vector <SKPairedUser> skusers = (Vector <SKPairedUser>) users; for( SKPairedUser user: skusers) Log.d("Users: ", user.getuserid() + " " + user.getcreationdate()); if (skusers.size() == 0) Page 19 of 53

20 ); // no users 5.2 Unpair User from Device Unpairing removes the relationship established between a user and device. Use this method if a user changes devices or is removed. Calling this method also removes any associations established as a result of such a pairing, such as passcodes. Note: briidge.net Connect allows multiple users to pair to the same device. Unpairing one user disassociates the relationship between that user and the device and does not impact any other users Procedure 1. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 2. Call SDK Make a call to briidge.unpair. Pass the user identifier (userid) and a class that implements the UnpairListener interface. This interface has one callback method that needs to be implemented: briidge.unpair( userid, new public void unpaircomplete(int status) ); if (status == Briidge.STATUS_OK) // success else if (status == Briidge.STATUS_CONNECTIVITY_ERROR) // tell user that there is a connectivity error else // could not un-pair That's it. The user and device are now unpaired. Page 20 of 53

21 5.3 Change Crypto PIN Changing a user Passcode (QuickCode) is a simple operation that does not require communication between the application client and RP app server. However, there is, communication between the Mobile SDK and briidge.net services that is transparent to the application client developer Procedure 1. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 2. Call SDK Make a call to briidge.changequickcode. briidge.changequickcode( oldquickcode, newquickcode, userid, new public void changequickcodecomplete(int status) ); if (status == Briidge.STATUS_OK) // success else if (status == Briidge.STATUS_INVALID_QUICK_CODE) // Failed to verify old passcode. else if (status == Briidge.STATUS_UNPAIRED_USER) // User is not paired on this device. else if (status == Briidge.STATUS_PASS_CODE_NOT_SET) // User has no passcode set, nothing to change. else if ( status == Briidge.STATUS_TRY_LATER_TOO_MANY_INVALID_QUICKCODE_ATTEMPTS) // too many failed attempts to change passcode - try later else // could not change the passcode // (null, empty, server error, etc) Page 21 of 53

22 6. EMV Card Services 6.1 Card Read Use briidge.net Connect to authenticate users or transactions with RP-issued or RP-approved contactless credentials. Contactless credentials are typically cards that users can tap on supported near field communication (NFC) enabled terminals. Terminals can include NFC-enabled USB sticks or certain mobile devices. Note: When using mobile device terminals, this method is only applicable for select Android devices with NFC capability. Many contactless cards allow the terminal to provide data to the card during transactions. briidge.net Connect enables RPs to specify terminal option data for this purpose. If a required terminal option data element is not provided by the RP, or the provided value does not meet the requirement of the card, the device terminal will provide the terminal option data. The actual values used will be provided in the response Procedure 1. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 2. Call SDK Make a call to briidge.readcard. Ensure to pass a class that implements the Briidge.ReadCardListener interface. Several callback functions must be implemented, including: void presentcardreadui(cardreadtransaction transaction) void cardreadstatus(int status) void cardreadcomplete(int status, Sting transactionidentifier) presentcardreadui This method is called when the SDK is ready to perform card reading. The RP should present a user interface to indicate to the user to tap their card. The app MUST set up an NFC intent filter to receive Android NFC events at this time (see below for clarification). cardreadstatus This method is called when the state of the card read is available. States include when the card read completes, when an error occurs, or when a wrong intent was passed. cardreadcomplete Page 22 of 53

23 This method is called when the card read completes. If successful, a transaction identifier is returned. briidge.readcard(null, new public void presentcardreadui(cardreadtransaction transaction) this.transaction = transaction; // Prepare for reading NFC to pass the Intent from it to the public void cardreadstatus(int status) if (status == Briidge.STATUS_CARD_READ_READING_DONE) // inform user of success and wait for cardreadcomplete to be called. else if (status == Briidge.STATUS_CARD_READ_ERROR) // inform user of tap error and ask to tap again or cancel. else if (status == Briidge.STATUS_CARD_READ_NON_NFC_INTENT) // Wrong Intent was passed to transaction.readcard. // Use transaction.isnfcintent to determine if you received an NFC public void cardreadcomplete(int status, String transactionid) if (status == Briidge.STATUS_OK) // API finished without errors, //use transactionid to get the API result from the RP server. else if (status == Briidge.STATUS_CONNECTIVITY_ERROR) // tell user that there is a connectivity error else if (status == Briidge.STATUS_FATAL_CONNECTIVITY_ERROR_UPDATE_SDK) // tell user that there is a fatal connectivity error that requires // app developer to update sdk else // Server error while performing card tap API. ); 3. Call briidge.net Connect Server Obtain the card information by passing the transaction identifier to the briidge.net Connect server. The method to call is device-initiated-card-read-data.action Where, HOST, is provided to you by SecureKey. The JSON body of the request is simply: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" If card validation is successful, the result is a JSON object containing the card and device information; otherwise, an error is returned. For example: Note: The data returned by briidge.net Connect server is the raw card data and is different for each card type. The RP must be familiar with the card specification standards. Page 23 of 53

24 "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b-6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false, "cardtype" : "DISCOVER_DCVV", "interfacetype" : "Contactless", "carddata":[ "tag":"84", "value":"a ", "tag":"50", "value":" f766572", "tag":"87", "value":"01", "tag":"9f38", "value":"9f3701", "tag":"82", "value":"0000", "tag":"94", "value":" ", "tag":"9f80", "value":"040608", "tag":"56", "value":" f23", "tag":"57", "value":"3b f3e" ], "cardterminaloptionsused":[ "tag":"9f37", "value":"65" ] 4. Pass result to application client The RP server can now interpret the data and pass the result back to the application client. That's it. Your application client has finished reading the card NFC Intent When presentcardreadui is called, the RP app should begin filtering for the intent nfcadaptor.action_tech_discovered and save the CardReadTransaction object received by this method. To be able to capture the NFC intent, you have to add android.permission.nfc to permissions in your manifest. For example: // Begins filtering for the NFC intent. private void enableforegrounddispatch() if (NfcAdapter.getDefaultAdapter(this)!= null) try NfcAdapter.getDefaultAdapter(this).enableForegroundDispatch(this, PendingIntent.getActivity(this, 0, new Intent(this, this.getclass()).addflags(intent.flag_activity_single_top), 0), new IntentFilter[] new IntentFilter(NfcAdapter.ACTION_TECH_DISCOVERED), new String[][] new String[] NfcA.class.getName(), new String[] NfcB.class.getName() ); Page 24 of 53

25 catch (Exception e) // Show error to user. // Stops filtering for the NFC intent. private void disableforegrounddispatch() if (NfcAdapter.getDefaultAdapter(this)!= null) try NfcAdapter.getDefaultAdapter(this).disableForegroundDispatch(this); catch (Exception e) 6.2 Authenticate with Card This method enables you to perform user authentication and read card in a single transaction. It is similar to the card read method, except the server response returns a user identifier instead of card data. RPs must first set up a Credential Mapper Class with the briidge.net Connect administrator to provide mappings between user identifier and card data. To perform user authentication and card read together, call briidge.authenticatewithcard method. This method takes cardterminaloptions and timeout as parameters to specify the accepted types of terminals and to place a time limit on the card read itself. Callback methods will have to be implemented as well to track the card read progress Procedure 1. Initialize the SDK Initialize the Mobile SDK to access the briidge.net platform. Briidge briidge = SKBriidgeFactory.getBriidgePlatform(context); 2. Call SDK Make a call to briidge.authenticatewithcard. briidge.authenticatewithcard(null, new public void presentcardreadui(cardreadtransaction transaction) this.transaction = transaction; // Prepare for reading NFC to pass the Intent from it to the public void cardreadstatus(int status) if (status == Briidge.STATUS_CARD_READ_READING_DONE) // inform user of success and wait for cardreadcomplete to be called. else if (status == Briidge.STATUS_CARD_READ_ERROR) // inform user of tap error and ask to tap again or cancel. else if (status == Briidge.STATUS_CARD_READ_NON_NFC_INTENT) // Wrong Intent was passed to transaction.readcard. // Use transaction.isnfcintent to determine if you received an NFC intent. Page 25 of 53

26 @Override public void cardreadcomplete(int status, String transactionid) if (status == Briidge.STATUS_OK) // API finished without errors, //use transactionid to get the API result from the RP server. else if (status == Briidge.STATUS_CONNECTIVITY_ERROR) // tell user that there is a connectivity error else if (status == Briidge.STATUS_FATAL_CONNECTIVITY_ERROR_UPDATE_SDK) // tell user that there is a fatal connectivity error that requires // app developer to update sdk else // Server error while performing card tap API. ); 3. Call briidge.net Connect Server Obtain the results of the card authentication by passing the transaction identifier (txnid) in the call to your server. The method to call is AUTHENTICATE-WITH-CARD: Where, HOST, is provided to you by SecureKey. The JSON body of the request is simply: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" If card validation is successful, the result is a JSON object containing the user identifier, userid, and device information, deviceinfo; otherwise, an error is returned. For example: "userid" : "user123", "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b-6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false That's it. Your mobile app has now authenticated the user using a card. Page 26 of 53

27 7. Key Management briidge.net Connect offers a suite of key management services that enable Relying Parties (RPs) to securely synchronize and store keys or key components to perform encrypt/decrypt operations, sign data, and generate cryptograms locally from a user s mobile device. Once transmitted to the device, RPs can perform operations such as OTP transactions, encrypting and/or decrypting data, signing data, and generate cryptograms locally from the mobile device. For more information, see the briidge.net Connect - RP Key Management and Operations guide. Page 27 of 53

28 8. Inter-Channel Communication Inter-channel communication refers to messages that are passed between user-facing applications on different devices for various consumer channels such as web, mobile, call center, and so forth. The ability to send messages between multiple channels enable implementations involving out-of-band second factor authentication, transaction confirmation, credential transfer from one device to another, and so on. One example of a user flow that incorporates inter-channel communication is Web-to-Mobile; where an end user may first engage with a web application and then engage with a mobile application to complete the task. For example, the user can be performing a money transfer from the web application. The web application may then request that the user provide confirmation through a mobile application to complete the transfer. Another example is a user leveraging their mobile ID (that is, using their mobile device as their user credential) to sign-in to a web application by snapping a QR code presented on the web page. The web application can have a companion mobile app to process the code for verification. For more information, see the briidge.net Connect - Solution Guide - Web to Mobile guide. Page 28 of 53

29 9. Server Reference The following sections provide additional details and descriptions for briidge.net Connect Server APIs and JSON parameters applicable to this guide. 9.1 API Reference Add Device Use this method to associate a provisioned device to an existing user. Endpoint: Request Requests can contain the following data: Request Parameter Type Short Description userid [Required] String A user identifier in the RP s namespace. For example: "userid" : "user123" deviceid [Required] String A unique identifier for the mobile device. For example: "deviceid" : "04a96c35-aef5-4ad7-ac6b-6c5c890d3b1b" verifieddevice [Optional] Boolean Indicates whether or not the device used to authenticate the user was in a verified state according to RP policy rules. For example: "verifieddevice" : true Response Response Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Page 29 of 53

30 Error Codes Error codes for this response can include: invalid_credentials no_device unknown_user Add User Use this method to register a user with briidge.net Connect. Endpoint: Request Requests can contain the following data: Request Parameter Type Short Description userid [Required] String A user identifier in the RP s namespace. For example: "userid" : "user123" phone [Optional] Array An array of objects listing the user's contact details. For example: "phone" : [ "name" : "Home", "number" : " ", "name" : "Mobile", "number" : " " ] Response Response Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" phone [Optional] Array An array of objects listing the user's contact details. For example: "phone" : [ "name" : "Home", "number" : " ", "name" : "Mobile", "number" : " " ] Page 30 of 53

31 Error Codes Error codes for this response can include: invalid_access_token user_exists system_error Authenticate User (Init) Use this method to authenticate a user. Initiation Endpoint: Initiation Request Requests can contain the following data: Request Parameter Type Short Description userid [Required] String A user identifier in the RP s namespace. For example: "userid" : "user123" Initiation Response Request Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Error Codes Error codes for this response can include: unsupported_authentication invalid_credentials invalid_request_property invalid_request Authenticate User (Result) Use this method to authenticate a user. Page 31 of 53

32 Result Retrieval Endpoint: Result Retrieval Request Request Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Result Retrieval Response Request Parameter Type Short Description userid [Required] String A user identifier in the RP s namespace. For example: "userid" : "user123" deviceinfo [Required] Object An object listing information about the device if the authentication was successful. For example: "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b- 6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false Error Codes Error codes from this response can include: invalid_access_token unknown_txn authentication_failed unknown_user user_declined user_cancelled device_preempted user_cancelled_update Page 32 of 53

33 system_error txn_not_complete no_device invalid_device device_update_required timeout card_read_error unrecognized_card_type invalid_card_data device_removed device_network_error Authenticate with Card Use this method to perform user authentication and read card in a single transaction. Endpoint: Request Requests can contain the following data: Request Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Response Response Parameter Type Short Description userid [Required] String A user identifier in the RP s namespace. For example: "userid" : "user123" deviceinfo [Required] String An object listing information about the device if the authentication was successful. For example: "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b- 6c5c890d3b1b", Page 33 of 53

34 Response Parameter Type Short Description "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false Error Codes Error codes for this response can include: unknown_txn authentication_failed request_mismatch Enroll User (Init) This method is used to perform several registration operations in one call. It enables you to: Add a user (if not registered with briidge.net Connect), Provision and register a device to the user, Select and set up authentication methods (for example, Passcode (QuickCode) or local authentication methods such as fingerprint and device pin), and Set a Passcode (QuickCode) for the user. Endpoint: Initiation Request The body of the request can contain the following data: Request Parameter Type Short Description userid [Required] String A user identifier in the RP s namespace. For example: "userid" : "user123" Initiation Response The body of the response can contain the following data: Response Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile Page 34 of 53

35 Response Parameter Type Short Description SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Error Codes Error codes for this response can include: invalid_credentials invalid_request_property invalid_request unknown_user Enroll User (Result) This method is used to perform several registration operations in one call. It enables you to: Add a user (if not registered with briidge.net Connect), Provision and register a device to the user, Select and set up authentication methods (for example, Passcode (QuickCode) or local authentication methods such as fingerprint and device pin), and Set a Passcode (QuickCode) for the user. Endpoint: Result Retrieval Request The body of the request can contain the following data: Request Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Result Retrieval Response The body of the response can contain the following data: Response Parameter Type Short Description Page 35 of 53

36 Response Parameter Type Short Description deviceinfo Object An object listing information about the device if the authentication was successful. For example: "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b- 6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false Error Codes Error codes for this response can include: invalid_access_token user_exists system_error Get Device (Device Initiated) Use this method to retrieve user device information after initiating an SDK call using the briidge.net Connect Web or Mobile SDKs. Endpoint: Request Requests can contain the following data: Request Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" useripaddress [Optional] String An IP address for the device as identified by the RP for the connecting user. For example: "useripadress" : " " Page 36 of 53

37 Response Response Parameter Type Short Description deviceinfo [Required] String An object listing information about the device if the authentication was successful. For example: "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b- 6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", "model" : "LGE OCCAM", "lastconnected" : " T15:20: ", "pushable" : false Error Codes Error codes for this response can include: unknown_txn system_error Get Device Provision ID Use this method to provision a device for use with briidge.net Connect. Endpoint: Request There is no request body for this request Response Response Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Note: The transaction identifier, txnid, is the provisioning authorization code. Pass this value to the SDK to complete provisioning. Page 37 of 53

38 Note: txnid is used as the provisioning authorization code in the SDK Error Codes Error codes for this response can include: invalid_credentials unknown_user Pair Device (Init) Use this method to initiate device association with an existing user. When a device is "paired" with a user, a user Passcode (QuickCode) can be set up for this user. Endpoint: Initiation Request Requests can contain the following data: Request Parameter Type Short Description userid [Required] String A user identifier in the RP s namespace. For example: "userid" : "user123" expiry [Required] String The expiry date and time for the pairing request. For example: "expiry" : " T00:00:00.000Z" If the pairing is not complete within the specified expiry, the pairing request terminates in failure. language [Optional] String A two character language code and optional two character country/region code to specify the language for text appearing in the widget. For example: "language" : "en-ca" Where, en-ca represents Canadian English. context [Optional] String A custom text field for specifying the context of the request. For example: Page 38 of 53

39 Request Parameter Type Short Description "context" : "Device Authentication" deviceconstraints [Optional] Array An array of constraints on the type of devices accepted (by the RP) for device pairing. For example: "deviceconstraints": "remoteallowed" : true, "nfcrequired" : false, "apptype" : null verifydevice [Optional] Boolean Indicates if a device should be marked as verified for the specified user. For example: "verifydevice" : true Initiation Response Response Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" pairingcode [Required] String A code used to initiate pairing from the client application. The pairingcode is referenced in the SDK call from the client. "paircode" : "XVTBMNCUVEXA" pairingurl [Optional] URL A URL to a SecureKey landing page where links and instructions (specific to a client platform) will be provided to invoke the SDK from the client application to initiate pairing. "pairingurl" : " notificationchannel [Optional] URI A notification channel handle to enable a client to wait for a response notification. This will be provided if the request indicated Page 39 of 53

40 Response Parameter Type Short Description that the notification should be through a notification channel. "notificationchannel" : "..." Error Codes Error codes for this response can include: invalid_request invalid_request_property unknown_user system_error Pair Device (Result) Use this method to retrieve the result after initiating device association with an existing user. When a device is "paired" with a user, a user Passcode (QuickCode) can be set up for this user. Endpoint: Result Retrieval Request Requests can contain the following data: Request Parameter Type Short Description txnid [Required] String The identifier for the current transaction. The transaction identifier is supplied by briidge.net Connect - Server, Web SDK, or Mobile SDK. For example: "txnid" : "7b632adf-ee64-4a49-9d42-5cb95d5edc1f" Result Retrieval Response Response Parameter Type Short Description deviceinfo Object An object listing information about the device if the authentication was successful. For example: "deviceinfo" : "deviceid" : "04a96c35-aef5-4ad7-ac6b- 6c5c890d3b1b", "devicetype" : "SW_SE", "supportsnfc" : true, "devicename" : "LGE", Page 40 of 53