PIV-D Certificate Access for Android

VMware Workspace ONE^® integrated authentication supports derived personal identity verification credentials. Electronic certificates for end user authentication can be generated by integrating with a derived credential provider. The certificates can be stored securely on end user mobile devices. Stored certificates can be accessed by applications on the mobile device through the Android Keystore system.

Integrated authentication with derived credentials is configured in the Workspace ONE Unified Endpoint Manager (UEM) console. Identity certificate storage on the device is handled by the Workspace ONE PIV-D Manager mobile application for Android.

Derived personal identity verification credentials (PIV-D) certificate access for Android works as follows.

Integrated authentication by derived credentials is configured in the UEM.
The Workspace ONE Intelligent Hub application is installed on end user devices, and enrolled with the UEM.
The Workspace ONE PIV-D Manager application is also installed on end user devices, and enrolled with the UEM via Hub.
The PIV-D Manager application is enrolled with a derived credential provider.
PIV-D electronic certificates are generated and stored on the device.
Other Android applications on the same device request access to stored certificates through the Android Keystore system. Access is only granted if confirmed by the end user.

Prerequisites

To integrate PIV-D certificate access into your Android application, ensure you have access to the compatible software versions. The following table shows the earliest supported versions of the applicable Workspace ONE components.


Software	Available
Workspace ONE management console	19.12
Workspace ONE Intelligent Hub for Android	19.10
Workspace ONE PIV-D Manager for Android	1.3

Note: Your application doesn’t have to integrate the Workspace ONE Software Development Kit for Android.

Procedure

Console Configuration

An integrated authentication configuration that gives accessible PIV-D identity certificates is setup in the Workspace ONE management console. The following instructions are intended for application developers or other users wishing to try out certificate export. Full documentation can be found in the online help.
1. Log in to the management console. The dashboard will be displayed.
2. Select an organization group.By default, the Global group is selected.
3. Navigate to: Devices, Profile & Resources, Profiles.This opens the Profiles list.
4. Either add a new profile, or edit an existing profile, as follows. To create a new profile, select Add, Add Profile, then Android. Enter a name for your new profile. To edit an existing profile, click its label in the list. It must be an Android profile.In either case, a profile editing screen will be displayed.
5. Select Credentials and then Configure, then make the following selections: Credential Source: Derived Credentials.Key Usage: Authentication.
6. Select Save and Publish to commit your changes to the configuration.This completes UEM configuration.See also the Console User Interface Screen Capture in the appendix to this document.
Device Configuration

Configure your developer device as follows. Do this after Console Configuration.
1. Install the Workspace ONE Intelligent Hub application, for example from the Google Play store.
2. Enroll the Hub application with the UEM configured for derived credentials.
3. Install the Workspace ONE PIV-D Manager application.The Hub might automatically install PIV-D Manager, depending on UEM configuration.
4. Unless your derived credential provider is Workspace ONE, log in to your derived credential provider’s website.The website will require login credentials, a smart card, or some other authentication factor.
5. Launch PIV-D Manager, choose your credential provider and follow the provided instructions for enrollment.The outcome should be that PIV-D Manager fetches electronic certificates from the provider.
6. Hub will present a notification to request permission to install the certificates from PIV-D.Click on the notification and follow the provided instructions to permit certificate installation to the system secure store.
Programming Interface

Use the native Android programming interface to access PIV-D certificates. You can try this out in your application after completing Console Configuration and Device Configuration.

The following interfaces are typically used for access to PIV-D certificates. See the Android developer website for reference documentation and programming guides. Links are given here for convenience.
1. KeyChain class.The reference includes a typical sequence of calls, at time of writing. See: https://developer.android.com/reference/kotlin/android/security/KeyChain
2. KeyChain.choosePrivateKeyAlias static method.Called to prompt the user to select a certificate.
3. KeyChainAliasCallback interface.Implemented to receive the user selection. See: https://developer.android.com/reference/kotlin/android/security/KeyChainAliasCallback
4. KeyChain.getPrivateKey and KeyChain.getCertificateChain static methods.Called from the KeyChainAliasCallback.alias callback, to access the credentials data.
5. Code Snippet
```
class MainActivity : AppCompatActivity(), KeyChainAliasCallback {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
//....
// Following code will prompt the user to choose a certificate when
// the specified TextView control is tapped.
findViewById<TextView>(textViewID).setOnClickListener {
KeyChain.choosePrivateKeyAlias(this, this, null, null, null, -1, null)
}
}
override fun alias(alias: String?) {
// Add a debugger breakpoint on the next line if you want to
// check the alias string value.
alias?.let {
val privateKey: PrivateKey? = KeyChain.getPrivateKey(
this.applicationContext, alias)
val certificateChain: Array<X509Certificate>? = KeyChain.getCertificateChain(
this.applicationContext, alias)
// The certificateChain object can be used to respond to authentication challenges.
}
}
}
```
  Note:
  Changes can be made by administrators at any time, for example to the UEM configuration, or to the infrastructure. The following possibilities at least should be handled by your application.
  - Your KeyChainAliasCallback alias method receives a null parameter.
  - Your response to an authentication challenge is rejected.