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.
NoteIn accordance with the applicable Samsung Wallet Partners agreements, this Code Lab covers the setup and use of the Verify with Samsung Wallet service for purposes of integrating Samsung Wallet with partner sites and apps. The use cases and corresponding code samples included are representative examples only and should not be considered as either recommended or required.
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!
Verify with Wallet Sample Code for App2App integration (802.3 KB)
Start the onboarding process
Partners can manage wallet cards and monitor performance with the Samsung Wallet Partners site. To join as partner:
- Generate a private key and certificate signing request (CSR) using the OpenSSL command. You can follow the instructions in Security Factors.
NoteA private key enables encryption and is the most important component of certificates. While CSR, which is a necessary factor to obtain a signed certificate, includes the public key and additional information like organization and country.
-
Proceed to register in the Samsung Wallet Partners site using your Samsung Account. Follow the Samsung Wallet Partner Onboarding process.
-
Upload the generated CSR for data encryption in Encryption Setting Management section.
-
After registration, you will receive a welcome email.
NoteUpon receiving the certificates via email, be sure to keep the information safe from exposure and only use them for the following purposes:
- Signed Certificate: used along with the private key to sign data.
- Samsung Certificate: used to encrypt card data and validate authentication tokens in server API headers.
Create a Relying Party wallet card
Follow the steps below to create a wallet card in Samsung Wallet Partners site:
- Go to Wallet Cards > Manage Wallet Card and click Add Wallet Card.
-
In Wallet Card Template field, choose [Wallet] Relying Party as wallet card type and Relyingparty > Others as sub type.
-
Select the design type and click Done.
- In Wallet Card Custom Setting, click Change, and choose Drivers as Authentication Issuer. You can also select specific mDLs such as below:
NoteThe Authentication Issuer is a unique property of the Relying Party card type. The Identity Provider of the Authentication Issuer is supported depending on the Service Location set. For example, if the Service Location is in the United States, the Authentication Issuer field only supports any Identity Provider in the United States region.
-
In Main(Headquarters) Location, select United States.
-
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.
For the App2App integration, you need to setup the button inside the mobile application.
- In Android Studio, click Open.
- Locate the downloaded Android project (RpClient_codelab) from the directory and click OK.
- 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)
- 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
}
- Inside the listener, add the
requestData
variable to prepare the request fields for verification:
val requestData = DemoData.requestData
- 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.
NoteRequested data such as partnerId
, public keys, and private keys are generated during the onboarding process, while cardId
is generated when you create a wallet card. However, in this Code Lab, these data is already predefined and included in the sample mobile app.
- 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:
- Open the sample app and choose SDC CODE LAB.
- Press the Verify with Samsung Wallet button.
- Once you are redirected to the Samsung Wallet app, press the Verify button.
- 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.
For the Web2App integration, you can use the Test Tool to test the Verify with Samsung Wallet button.
-
Open a web browser on your computer or Galaxy mobile device and go to the following link: partner.walletsvc.samsung.com/addToWalletTest
-
Go to Verify with Wallet tab and click Choose Key File to upload your private key.
- In the Select Card dropdown menu, select the card you created to display its details.
- Navigate to the Form tab and modify the data as desired. You can change the logo image or provider name.
-
Press the Verify with Samsung Wallet button.
-
Once you are redirected to Samsung Wallet, press the Verify button.
- The Samsung Wallet app shows a checkmark to indicate that the identity has already been verified.
- 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.
NoteThis step is optional, but if you want to learn how to integrate the Verify with Wallet button into your services like an Android app, web app, or email, you can follow these steps.
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:
-
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.
-
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.
-
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.
-
Follow the Implementing Button guide to determine where to incorporate the generated CData and gain further insights into this process.
-
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:
Verify with Wallet Complete Code for App2App integration (802.5 KB)
To learn more about Samsung Wallet, visit:
developer.samsung.com/wallet