Skip to content

Commit 8edeb8e

Browse files
dturnerGerrit Code Review
dturner
authored and
Gerrit Code Review
committed
Merge "Add README" into main
2 parents 5c66330 + 6b6030b commit 8edeb8e

File tree

1 file changed

+112
-0
lines changed

1 file changed

+112
-0
lines changed

‎MyVault/README.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
MyVault App
2+
==================
3+
4+
This is a sample app which allows users to save, view and use their login credentials for websites and other apps. It's a credential provider app which saves passkeys and passwords.
5+
6+
The app demonstrates how to use the [Jetpack Credential Manager API](https://developer.android.com/jetpack/androidx/releases/credentials).
7+
It provides a reference implementation of the [Credential Manager guidance](https://developer.android.com/training/sign-in/credential-provider)
8+
for developers wishing to create a credential provider app.
9+
10+
# Features
11+
12+
The app demonstrates how to:
13+
14+
- Register as a `CredentialProviderService` so that users can store and retrieve passwords and passkeys using the app.
15+
- Save passwords/passkeys to the app. These are stored locally in a database for demonstration purposes only. In a real app this data should be sent to a server to allow the user's credentials to be synchronized across all their devices.
16+
- Retrieve credentials from the app to assist with user login in another app or website.
17+
- Delete passkeys or passwords.
18+
19+
# Requirements
20+
21+
- Latest [Android Studio stable release](https://developer.android.com/studio)
22+
- An Android device or emulator running Android 14 or higher.
23+
- Up-to-date Google Play Services (GMS version should be above 230815045).
24+
25+
# Using the app
26+
27+
## Set MyVault as a credential provider
28+
The MyVault app must be selected as a credential provider on the Android device before any credentials from other apps can be saved.
29+
30+
- Ensure that a screen lock mechanism (e.g. a PIN) has been set
31+
- Build and run the MyVault app
32+
- Go to Android device settings -> Passwords and accounts
33+
- Under the "Additional providers" section, enable MyVault as a provider
34+
35+
Now, whenever you create a new passkey or password in an app that supports the CredentialManager API, you will be prompted to save it in the MyVault app.
36+
37+
## Create a credential in another app
38+
- Build and run the [Credential Manager app](../CredentialManager) also in this code repository
39+
- Choose "Sign up"
40+
- Enter a username
41+
- Choose "Sign up with passkey"
42+
43+
This will create a passkey for the Credential Manager app and store it in the MyVault app.
44+
45+
<img src="docs/images/save-passkey-in-my-vault.png" alt="Save passkey in MyVault" style="width:200px;"/>
46+
47+
Note: You can use any app which supports passkey creation, just ensure that you choose "MyVault" as the destination for the passkey.
48+
49+
## View and delete credentials
50+
- Run the MyVault app to see the passkeys and passwords which have been saved to the MyVault app
51+
- To delete all credentials, open the app drawer -> Settings -> Delete all data
52+
53+
<img src="docs/images/credentials-list.png" alt="List of all saved app credentials displayed in MyVault" style="width:200px;"/>
54+
<img src="docs/images/passkey-credentials.png" alt="Passkeys meta data displayed in MyVault for a particular domain" style="width:200px;"/>
55+
<img src="docs/images/password-credentials.png" alt="Password metadata displayed in MyVault for a particular domain" style="width:200px;"/>
56+
<br/>
57+
58+
## Retrieve a credential in another app
59+
- Run the [Credential Manager app](../CredentialManager)
60+
- Choose "Sign in"
61+
- Choose the previously entered username
62+
63+
<img src="docs/images/credentials-in-client-sample.png" alt="All credentials saved in MyVault thought CredentialMangerSample app" style="width:200px;"/>
64+
65+
# Understanding the app
66+
This app follows the [official Credential Manager guidance](https://developer.android.com/training/sign-in/credential-provider).
67+
Please read that first to understand how the app has been implemented.
68+
69+
## Project structure
70+
Here are the folders in the project and what they contain:
71+
72+
- `<root>` - Application and app dependencies.
73+
- `data` - Repository, database and service classes. Key classes are `CredentialsRepository` and `MyVaultService`.
74+
- `fido` - Classes for parsing responses according to FIDO guidelines. This implementation
75+
is for demonstration purposes only and should not be used directly in production. Refer to the
76+
official WebAuthn specs [here](https://www.w3.org/TR/webauthn-2).
77+
- `ui` - Activities for handling requests from other apps. Screens and UI elements (written using Compose).
78+
79+
## Key classes
80+
81+
### Credential provider service
82+
`MyVaultService` subclasses [`CredentialProviderService`](https://developer.android.com/reference/androidx/credentials/provider/CredentialProviderService) and responds to requests from the Credential Manager API, such as when creating or reading a passkey.
83+
84+
Each `onBegin` method responds with an entry which will be shown on the account selector, allowing the user to choose one of those entries.
85+
86+
Each entry also has a `PendingIntent` which will be called when the user selects that entry.
87+
88+
This is the first phase in the [two-phased approach to provider interaction](https://developer.android.com/training/sign-in/credential-provider#two-phased-approach).
89+
90+
### Activities
91+
92+
This project contains 6 activities - `MainActivity` for the main app UI, plus 5 additional activities to handle the `PendingIntents` created when responding to Credential Manager API calls in `MyVaultService`. The second phase in the [two-phased approach to provider interaction](https://developer.android.com/training/sign-in/credential-provider#two-phased-approach).
93+
94+
These additional activities are described below.
95+
96+
- `CreatePasskeyActivity`: Creates a passkey
97+
- `GetPasskeyActivity`: Gets a passkey
98+
- `CreatePasswordActivity`: Creates a password
99+
- `GetPasswordActivity`: Gets a password
100+
- `UnlockActivity`: Unlocks the requested credential by surfacing a biometric authentication flow
101+
102+
103+
### Data classes
104+
- `CredentialRepository` - contains the logic for creating, storing and reading credentials.
105+
- `CredentialsDataSource` - CRUD operations for credentials, backed by a Room DAO.
106+
107+
For more detailed information on how to create, save and retrieve credentials using the Credential Manager API, refer to the [official documentation]((https://developer.android.com/training/sign-in/credential-provider))
108+
109+
## License
110+
111+
The **MyVault Sample** is distributed under the terms of the Apache License (Version 2.0).
112+
See the [LICENSE](/LICENSE) file for more information.

0 commit comments

Comments
 (0)