Verify your ID with Samsung Wallet

Objective

Learn how to verify a user's identity with the ID information registered in their Samsung Wallet app.

Partnership Request

To create, manage, and monitor performance of wallet cards with the Samsung Wallet Partners site, you must become an official Samsung partner. Once done, you can fully utilize this Code Lab. You can learn more by visiting Samsung Wallet Partner Onboarding process, here in Samsung Developers.

Overview

Verify with Samsung Wallet enables users to utilize the Digital ID added to their wallets to simplify online transactions that require an identity verification. A mobile device with Samsung Wallet installed is required to verify the user’s identity through this feature. This feature uses the Relying Party card type to verify a user's identity using the ID information stored in Samsung Wallet.

This feature supports app-to-app (App2App) and web-to-app (Web2App) integration models. The Web2App integration supports the partner's mobile web application to request a verification to the Samsung Wallet app. The App2App integration supports the partner’s mobile application to request a verification to the Samsung Wallet app.

When the partner site requests the user to verify their identity, the Verify with Samsung Wallet button is displayed. The user is redirected to the Samsung Wallet app where they verify their identity via PIN or biometrics. Once verified, the user's identity information is sent to the partner and the transaction will proceed.

For detailed description, see Verify with Samsung Wallet.

Set up your environment

You will need the following:

• Access to Samsung Wallet Partners site
• Samsung Galaxy device that supports Samsung Wallet app
• Samsung Wallet app (latest version)
• Android Studio (latest version recommended)
• Java SE Development kit (JDK) 11 or later
• Supported mobile driver's license be added to Samsung Wallet app
• Internet browser, such as Google Chrome
• OpenSSL
• IntelliJ IDEA or any Java IDE (Optional)

Sample Code

Here is a sample code for you to start coding in this Code Lab. Download it and start your learning experience!

Start the onboarding process

Partners can manage wallet cards and monitor performance with the Samsung Wallet Partners site. To join as partner:

1. Generate a private key and certificate signing request (CSR) using the OpenSSL command. You can follow the instructions in Security Factors.

2. Proceed to register in the Samsung Wallet Partners site using your Samsung Account.  Follow the Samsung Wallet Partner Onboarding process.

3. Upload the generated CSR for data encryption in Encryption Setting Management section.

4. After registration, you will receive a welcome email.

Create a Relying Party wallet card

Follow the steps below to create a wallet card in Samsung Wallet Partners site:

1. Go to Wallet Cards > Manage Wallet Card and click Add Wallet Card.

2. In Wallet Card Template field, choose [Wallet] Relying Party as wallet card type and Relyingparty > Others as sub type.

3. Select the design type and click Done.

4. In Wallet Card Custom Setting, click Change, and choose Drivers as Authentication Issuer. You can also select specific mDLs such as below:

7. In Main(Headquarters) Location, select United States.

8. Once finished, select Save to view all registered information.

Launch wallet cards

You can launch and request activation of the cards by clicking the Launch button.

Upon agreeing to proceed, the Launch button text changes to Launched and the card status becomes Verifying.

Create a Verify with Samsung Wallet button (App2App)

For the App2App integration, you need to setup the button inside the mobile application.

1. In Android Studio, click Open.

2. Locate the downloaded Android project (RpClient_codelab) from the directory and click OK.

3. Go to app > kotlin+java > com.samsung.android.sample.rpclient > presentation > partners and, in the PartnersRequestFragment.kt file, add the Verify with Samsung Wallet button inside the onCreateView function:

Glide.with(this).load(partner.getVerifyButtonImage()).into(binding.verifyButton) 

4. Set up a click listener for the verifyButton:

binding.verifyButton.setOnClickListener { 

   /// Add the requestData variable to prepare the request fields 
   /// Add the appLink variables to request the card information
   /// Call the appLink method to request verification 
   
} 

5. Inside the listener, add the requestData variable to prepare the request fields for verification:

val requestData = DemoData.requestData 

6. Add the appLink variables to request the card information:

val appLink = rpClientApis.buildAppLink( 
    partnerId = partner.getPartnerId(), 
    cardId = partner.getCardId(), 
    payload = partner.buildApp2AppPayload(), 
    samsungPublicKey = partner.getSamsungPublicKey(), 
    partnerPublicKey = partner.getPartnerPublicKey(), 
    partnerPrivateKey = partner.getPartnerPrivateKey(), 
    isStagingServer = true 
) 

The data being requested are as follows:

• partnerId = gets the Partner ID from the identification card used.
• cardId = gets the Card ID from the identification card used.
• payload = builds the App2App payload.
• samsungPublicKey = gets the Samsung Public Key.
• partnerPublicKey = gets the Partner's Public Key
• partnerPrivateKey = gets the Partner's Private Key
• isStagingServer = checks if the application runs on a staging environment.

7. Call the appLink method to request verification. This method creates a channel between the test app and Samsung Wallet app to create the request and response data for the verification process:

appLink?.let { 
    Log.i(TAG, appLink) 
    rpClientApis.request("com.samsung.android.spay", UUID.randomUUID().toString(), appLink, object : RpClientApis.OnResponseListener { 
        override fun onGetMdocRequestData(deviceEngagementBytes: ByteArray): ByteArray? { 
            Log.i(TAG, "deviceEngagementBytes=${deviceEngagementBytes.toHex()}") 
            val keyPair = secureRepository.generateEcKeyPair() 
            Log.i(TAG, "requestData=$requestData") 
            val encryptedSessionEstablishmentBytes = secureRepository.buildSessionEstablishment(requestData, deviceEngagementBytes, keyPair) 
            Log.i(TAG, "encryptedSessionEstablishmentBytes=${encryptedSessionEstablishmentBytes?.toHex()}") 
            return encryptedSessionEstablishmentBytes 
        } 
 
        override fun onMdocResponse(encryptedResponseBytes: ByteArray) { 
            Log.i(TAG, "encryptedResponseBytes=${encryptedResponseBytes.toHex()}") 
            try { 
                val plainResponse = secureRepository.decryptMdocResponse(encryptedResponseBytes) 
                Log.i(TAG, "plainResponse=${plainResponse?.toPrettyJson()}") 
                val responseData = plainResponse?.toPrettyJson() 
                onResponse.postValue(responseData) 
            } catch (e: Exception) { 
                e.printStackTrace() 
            } 
        } 
 
        override fun onMdocResponseFailed(exception: Exception) { 
            Log.i(TAG, "onMdocResponseFailed(${exception})") 
            onError.postValue(exception) 
        } 
    }) 
} 

Run and test the application (App2App)

Go to Build > Build App Bundle(s) / APK(s) > Build APK(s) to build the application. Install the APK file to your mobile device and test the sample app as follows:

1. Open the sample app and choose SDC CODE LAB.

2. Press the Verify with Samsung Wallet button.

3. Once you are redirected to the Samsung Wallet app, press the Verify button.

4. The Samsung Wallet app shows a checkmark to indicate that the identity has already been verified while the sample app displays a Verification Success screen.

Test the Verify with Samsung Wallet button (Web2App)

For the Web2App integration, you can use the Test Tool to test the Verify with Samsung Wallet button.

1. Open a web browser on your computer or Galaxy mobile device and go to the following link: partner.walletsvc.samsung.com/addToWalletTest

2. Go to Verify with Wallet tab and click Choose Key File to upload your private key.

3. In the Select Card dropdown menu, select the card you created to display its details.

4. Navigate to the Form tab and modify the data as desired. You can change the logo image or provider name.

5. Press the Verify with Samsung Wallet button.

6. Once you are redirected to Samsung Wallet, press the Verify button.

7. The Samsung Wallet app shows a checkmark to indicate that the identity has already been verified.

8. Go back to the Test Tool, open the MDOC tab, and click the Check Result button. It displays a Result success popup when the verification process is successful.

Tokenize card data and implement the Verify with Wallet button to your service (optional)

The Samsung Wallet Partners site provides generated Verify with Samsung Wallet scripts for each wallet card you create. You can simply copy and paste these scripts into your partner apps (Web and Android) or include them in emails/MMS messages.

To implement the Verify with Wallet button, follow these steps:

1. Go to the [Verify with Wallet Script Guide] section of the card you created. Click Show to view the available scripts and then copy the appropriate script for your service.

2. Develop a program that can generate tokenized card data (CData). The CData represents the actual content of the wallet card and comes in different formats depending on the card type. You can check the CData Generation Sample Code for reference.

3. The CData is derived from the card data, which is in JSON format. For testing purposes, you can utilize the generated JSON from the Test Tool.

4. Follow the Implementing Button guide to determine where to incorporate the generated CData and gain further insights into this process.

5. You are redirected back to your app and your identity is verified.

You're done!

Congratulations! You have successfully accomplished the topic of this Code Lab.
Now, you are ready to verify your ID with the Verify with Samsung Wallet button into your application on your own! If you're having trouble, you may download this file:

To learn more about Samsung Wallet, visit:
developer.samsung.com/wallet