Update Shrine README

cy245 · cy245 · commit d3454bb29a87 · 2025-10-27T08:42:16.000-04:00
diff --git a/Shrine/README.md b/Shrine/README.md
@@ -1,4 +1,4 @@
-# Credential Manager Sample App
+# Shrine Sample App
 
 This is the repository for the Credential Manager API code integration app,
 also known as the **"Shrine"** app.
@@ -14,242 +14,99 @@ Credential Manager with your own apps.
 This sample app implements the following use cases:
 
 * Create an account using username and set the session using password.
-* Generate a new passkey for an existing account
+* Generate a new passkey for an existing account.
+* Create a passkey-only account using username.
 * Store the credentials for created accounts in the user's Google Password Manager account.
-* Sign in flow with passkeys support
-* Sign in flow with restore credentials support
-* Logout from the account.
+* Sign in flow with passkeys and password support.
+* Sign in flow with Sign in with Google.
+* Sign in flow with restore credentials support.
+* Passkey management in settings.
+* Internal session management.
 
 ## Requirements
 
 * Latest release of [Android Studio](https://developer.android.com/studio)
 * Java 11 or higher
-* A web browser with the ability to access [Glitch](https://glitch.com/).
 
 ## Typical account creation and login flow
 
-* Launch the app
-* Create an account by sending any username to the server
-* Set a session by sending a password in step 2
-* Register user credentials using your fingerprint sensor
-* From the list of passkeys options shown in the bottom sheet, select the correct passkey option to login
-* Logout of the application and close the app
-* [Optional] Create multiple accounts and switch accounts to test the implementation
-
-
-## How to setup your own Glitch.me server
-
-The Shrine app sends requests to a Glitch.me server, and out of the box this code example has been
-configured to use a Glitch instance that we've created. To use your own Glitch-hosted backend,
-follow these steps. The backend code uses your Android package and SHA fingerprint, and you will
-update these on the server.
-
-1.  Go to the edit page of the website at [https://glitch.com/edit/#!/credential-manager-app-test](https://glitch.com/edit/#!/credential-manager-app-test)
-
-2.  Find the ***"Remix to Edit"*** button at the top right corner. By pressing the button, you can fork the code and continue this tutorial with your own version of the project and services.
-
-3.  To use the API on an Android app, you need to associate it with a website and share credentials between them. To set this up, you'll use [Digital Asset Links](https://developer.android.com/training/sign-in/passkeys#add-support-dal). Digital Asset Links files are used to declare associations by hosting a JSON file on your website, and adding a link to this file to your app's manifest. Normally, you'll define an association between your app and the website by creating a JSON file and put it at `.well-known/assetlinks.json` on your HTTPS server. **For this demo, we have a server code that creates an `assetlinks.json` file automatically, just by adding the following environment params to the `.env` file in Glitch:**
-
-  1. In the Glitch left nav Files section, click on the `.env` file. This opens up your project's Environment Config. Fill in the following values:
-
-  2.  `HOSTNAME`: The name of your newly created Glitch service. The project name is found on top left of your Glitch project screen. It'll be something like `peaceful-banana-fern`. Paste or type in the name of your Glitch project into the `HOSTNAME` section.
-
-  3.  `ANDROID_PACKAGENAME`: The package name of your app, such as `com.google.credentialmanager.sample`. You can find the package name in your project's app-level `build.gradle` file as the value of the `applicationId` property within the `android` block.
-
-  4.  `ANDROID_SHA256HASH`: SHA-256 hash of your signing certificate. To get the SHA-256 hash of your developer signing certificate, use the following command: `keytool -list -v -alias androiddebugkey -keystore ~/.android/debug.keystore`. The default password of the debug keystore is "android". The SHA256 value appears under Certificate fingerprints. (`75:89:78:74:...`)
-
-
-4.  In your `build.gradle`'s `android` block, find the fields for `buildConfigField` and `resValue`, and update the following values.
-
-    1.  `buildConfigField / API_BASE_URL`: The URL of your new Glitch server's API. It'll be the full URL + /path appended to the end. For example: `https://peaceful-banana-fern.glitch.me/auth`
-
-    2.   `resValue / host`: The root URL for your server. For example: [https://peaceful-banana-fern.glitch.me](https://peaceful-banana-fern.glitch.me)
-
-
-5.  Sync your `build.gradle` changes by running **File > Sync Project with Gradle Files**.
-
-6.  Test building your app. Run a physical or emulated device that has a valid and passkey-enabled Google account set up, then run your app on it. You should see the Shrine app home screen appear, with Sign In and Sign Up buttons. Don't click anything just yet, you'll do that in the next step.
-
-
-## Integration
-
-Follow these steps to test Credential Manager integration. In the app, look for a toast to appear to indicate a response success or failure on each step.
-
-### Create an account for username on the server
-
-1.  When your app runs the first time, you should see a screen with buttons for Sign In and Sign Up. Click the **Sign Up** button. The **Create Account** screen appears.
-
-2.  Enter an email address and unique password and click the **Submit** button.
-
-3.  You should now see a **Create a passkey** screen. Click **Create a passkey**.
-
-4.  You should see a Google Password Manager bottom sheet appear, offering to save your credentials. Click **Continue**.
-
-5.  The Shrine app should then show the **Create a passkey** screen. Click the **Create a passkey** button and a Google Password Manager bottom sheet should appear that offers to create a passkey for your app. Click **Continue**. You should now see the Shrine main menu.
-
-6.  Click **Step 1: Send Username** after adding a username and email in the 1st field. For demo purposes, the app and the server will accept any username.
-
-7.  Check the username, and create a new account if it doesn't exist.
-
-8.  Set a `username` in the session.
-
-9.  Wait for the toast to appear saying "Username verified successfully". If you don't see toast, check the logs for errors.
-
-
-### **Set a session on server**
-
-This step demonstrates if developers want to do additional authentication (2FA). This step shows how 2FA can be done while using passkeys for authentication.
-
-1.  Check **Step 2: Send Password**. Above that field, add any password. Type and send the request.
-
-2.  Verify the user credential and let the user sign-in. No preceding registration is required.
-
-3.  Wait for the toast to appear that says "Session-id stored successfully, Do register!"
-
-4.  If you don't see toast, check the logs for errors.
-
-
-### **Pass required information to a passkey creation prompt**
-
-This section describes how to send a registration request to the server and pass the required information to a passkey creation prompt.
-
-1.  Register the passkey credential. Inside `AuthRepository.kt`, find `registerRequest`.
-
-2.  Once the request is sent from the client, this method calls the server API `/auth/registerRequest`. The API returns an `ApiResult` with all the `PublicKeyCredentialCreationOptions` that the client needs to generate a new credential.
-
-
-### **Create a passkey**
-
-In this section, you'll create a passkey with the response received from `/registerRequest`.
-
-1.  Parse the params as per needed for the create credentials call. Call `createPasskey()` from `Auth.kt`
-
-2.  Give users the choice to enroll a passkey and use it for re-authentication by registering a user credential using a `CreatePublicKeyCredentialRequest()` object.
-
-3.  This method calls `createCredential()` from *Credential Manager API*, which registers a user credential that can be used to authenticate the user to the app in the future. This method launches framework UI flows for a user to view their registration options, grant consent, etc.
-
-4.  Use your fingerprint or other auth. Methods from your device to register.
-
-
-### **Send the registration response and register a user credential**
-
-This section describes how to send a registration response back to the server and register a user credential on a server.
-
--   Call `/registerResponse`. This `registerResponse` method is called after the user interface successfully generates a new credential, and you want to send it back to the server.
-
--   Use the response received from the `createPasskey()` call and pass it back to your server.
-
--   Remember the ID of your local key so you can distinguish it from other keys registered on the server. In the `PublicKeyCredential` object, use the `rawId` property.
-
--   The returned value contains a list of all the credentials registered on the server, including the new one.
-
-
-### **How to retrieve previously stored credentials for user’s account**
-
-You now have a credential registered on the app and the server. You can now use it to let the user sign in.
-
-1.  Initiate a server check:
-
--   Open the file `AuthRepository.kt`.
-
--   Examine the `signinRequest` object.
-
--   Send a request to your server to confirm if Credential Manager APIs can be used for user sign-in.
-
--   Provide the `sessionId` and `credentialId` (which were stored locally) as data for this request.
-
-
-2.  Prompt the user for stored credentials:
-
--   If the server request is successful, call the `getPasskey()` function from the `Auth.kt` file to display the user's stored credentials.
-
-3.  Configure the retrieval request:
-
--   Create a `GetCredentialRequest()`.
-
--   Provide the previously created registration options to this request.
-
--   For the `isAutoSelectAllowed()` flag:
-
-
--   Set to `true` if you want a single stored credential to be automatically selected.
-
--   Set to `false` to require manual selection.
-
-
-4.  Retrieve credentials:
-
--   Use `PublicKeyCredentialOptions` with the `GetCredentialRequest` to retrieve all the user's eligible credentials.
-
--   Ensure that the `requestJson` argument is in a valid WebAuthn JSON format.
-
-
-5.  Display the credential selection interface:
-
-
--   Call `CredentialManager.getCredential()` to display a bottom sheet interface.
-
--   This UI displays a list of previously saved credentials. The user can then select a credential and provide consent to proceed with authentication.
-
-
-### **Send a sign-in response and authenticate the user**
-
-This section describes how to send a sign-in response to the server and authenticate your user.
-
-1.  Call `signinResponse` from `AuthRespository.kt`. Pass the response and credential to the method as parameters.
-
-2.  If successful, the user has been signed in and you can redirect them to the home screen.
-
-
-### **Restore credentials of a returning user on a new device**
-
-This section describes how to implement restore credentials
-
-1. On a successful user authentication, create a Restore Key
-
-   1. Call `AuthRepository`'s `registerPasskeyCreationRequest` method 
-   
-   2. With the PasskeyCreationRequest recieved from the above method, call `CredentialManagerUtils`'s `createRestoreKey` method 
-   
-   3. Then call `AuthRepository`'s `registerPasskeyCreationResponse` method
-
-
-2. Once on a new device, check if there is any restore key present on the device or not (brought to the new device in the process of Backup and Restore)
-
-   1. Call `AuthRepository`'s `signInWithPasskeyOrPasswordRequest` method 
-   
-   2. With the PasskeyCreationRequest recieved from the above method, call `CredentialManagerUtils`'s `getRestoreKey` method 
-   
-   3. If there is a RestoreKey present this will return a `GenericCredentialManagerResponse.GetCredentialSuccess` else this will return a `GenericCredentialManagerResponse.Error`
-
-
-3. Sign in using the found Restore Key
-
-   1. If a restore key is found in the above step, simply use it to sign-in using `AuthRepository`'s `signInWithPasskeysResponse` method
-
-
-4. Delete a Restore Key
-
-   1. If a user logs out of the app, make sure to clear the stored restore key by calling `CredentialManagerUtils`'s `deleteRestoreKey`
-
-
-## **Specific use case handling**
-
--   When there are no passkeys associated with accounts registered, the developer should catch the exception code and let the user know that first he needs to create a passkey before they try to fetch it.
-
--   For Begin Sign In Failure: 16: Caller has been temporarily blocked due to too many canceled sign-in prompt errors: This is a FIDO-specific error.
-
--   For Begin Sign In Failure: 8: Unknown internal error. If the phone isn't set up properly with a Google account, the passkey JSON is being created incorrectly.
-
--   For `publickeycredential.CreatePublicKeyCredentialDomException`: The incoming request cannot be validated: This means your application package ID is not registered with your server. Validate this with your server code.
-
-
-### **How to build a debug signed version**
-
-To build a debug signed version of this sample app, you need to update the `API_BASE_URL` to `https://credential-manager-app-test.glitch.me/auth` and `host` field to `https://credman-glitch-sample.glitch.me` under `buildConfigField` in your `build.gradle` file.
+* Launch the app.
+* Create an account with a passkey or password, or directly log in with your Google account
+* When creating a passkey, you will need to use your lock screen credentials. This means you will
+  need to enable a lock screen if you don't have one.
+* Once an account is created, you can sign in with the method you chose.
+* For passkey login, select the passkey from the list of passkeys options shown in the bottom sheet.
+  For password login, select the respective password option shown in the bottom sheet.
+* Manage your passkeys by going into settings.
+* Log out of the application to restart the flow.
+* [Optional] Create multiple accounts and switch accounts to test the implementation.
+
+## Design
+
+This section will cover the general components of the Shrine app. The typical app flow would look
+like the following:
+
+1. User interacts with a screen, i.e. to create a credential via the "Sign up" button on
+   `RegisterScreen.kt`.
+2. A callback is triggered, usually tied to a View Model function, i.e.
+   `viewModel.onPasskeyRegister()`.
+3. The View Model function calls the appropriate `AuthRepository.kt` function to send a request to
+   the server, i.e. `repository.registerUsername()` to first register the username with the server.
+4. `AuthRepository.kt` contains an injected `AuthApiService` instance which implements Retrofit
+   calls to the Project Sesame (app) server. Server requests and responses are handled in
+   `AuthRepository.kt` and then passed to the calling View Model. Internal session states are also
+   updated as needed.
+5. The View Model handles the returned response and makes other server calls as needed, i.e.
+   `createPasskey()`. In this case, `createPasskey()` also contains a callback with
+   `credentialManager.createCredential()` once initial server communication succeeds, via a
+   `CredentialManagerUtils` object that was passed from the Screen.
+6. The View Model updates the UI with success or failure, and navigates the user to the next screen
+   as appropriate.
+
+### Server
+
+This app utilizes the server at https://project-sesame-426206.appspot.com/ which is specified in the
+`app/build.gradle.kts` file. This server handles all requests related to passwords and passkeys (
+creation, authentication, deletion), as well as Sign in with Google. You can see the implementation
+of this server at https://github.com/GoogleChromeLabs/project-sesame. The app uses Retrofit to
+handle web communications with the server, with endpoints specified in`api/AuthApiService.kt` and
+called in `repository/AuthRepository.kt`.
+
+### Screens
+
+The frontend elements are contained in the various Screens in the `ui` package. Each Screen utilizes
+a View Model that generally has the same name, with a few exceptions. These Screens primarily handle
+frontend element placements and error message displays.
+
+Some Screens utilize Credential Manager calls (i.e. `RegisterScreen.kt`). As a Credential Manager
+object requires an Activity, the corresponding Context is passed in through the Screen to the
+`CredentialManagerUtils.kt` file which creates and manages the actual Credential Manager object.
+
+### View Models
+
+The View Models generally manage sending, receiving, and processing responses between the Screens
+and app server. Server communication is handled via an injected `AuthRepository` object. Uistate is
+also updated in the View Model, which is in turn monitored and updated in the Screen.
+
+### Credential Manager
+
+Credential manager calls are made in `CredentialManagerUtils.kt`. The usage is fairly
+straightforward, i.e. `.createCredential()` and `.getCredential()` for creating and retrieving
+credentials, respectively. Please note the handling of exceptions, as some may be caused by fairly
+common usage, i.e. user cancelling the selector.
+
+### Requests and responses
+
+The requests and responses sent and received from the server are defined in the `model` package.
+These consist of various data classes that are defined based on the expected response from the
+Project Sesame server, i.e. the data class `RegisterRequestResponse` defines fields expected from
+server response from requesting passkey registration options. This is then used in `registerRequest`
+in `AuthApiService.kt`, and the server's returned JSON is expected to have those fields. You can
+verify this by looking at the logs in Logcat after making any server request.
 
 ## **License**
 
-Shrine is distributed under the terms of the Apache License (Version 2.0). See the license for more information.
+Shrine is distributed under the terms of the Apache License (Version 2.0). See the license for more
+information.
 
 **
