Set up seamless credential sharing across Android apps and websites

Maximize user convenience by enabling cross-platform seamless credential sharing across your apps and websites. When multiple websites and Android apps share an account management backend, this feature allows users to save credentials once and have them automatically suggested on any linked website or Android app.

Best practices

For optimal user experience and security, implement seamless credential sharing across these touchpoints:

• Sign-in form: Enable automatic credential filling.
• Sign-up form: Securely store new credentials for use across platforms.
• Password change form: Synchronize password updates across all platforms.
• Password reset form: Allow single password resets to update all platforms.
• Webview domains: Extend credential sharing to webview domains within your app that handle account management (host sign-in, sign-up, password change, or password reset forms).
• Android apps

This approach creates a unified credential management system, enhancing both user convenience and security.

When designing your account management websites, we suggest you follow these best practices for account management sites:

• Design your sign-up form in accordance with best practices
• Design your sign-in form in accordance with best practices
• Add a well-known URL for changing passwords

When designing your Android apps, we recommend you integrate your app with Android Credential Manager.

Prerequisites

Before setting up seamless credential sharing, ensure you have the following for each platform:

For each Android app:

• The Android application ID, as declared in the app's build.gradle file.
• The SHA256 fingerprints of the signing certificate.
• (Recommended) User sign-in implemented with the Credential Manager API.

For each website:

• Ability to publish a /.well-known/assetlinks.json file on each respective domain, following the Digital Asset Links (DALs) syntax.
• All account management domains (sign-in, sign-up, password change, or password reset forms) must be accessible over HTTPS.

Note: Chrome automatically shares saved credentials between same-site websites (for example, www.example.com and m.example.com).

Enable seamless credential sharing across Android apps and websites

To configure seamless credential sharing across apps and websites, you create and publish Digital Asset Links statement lists that declare which entities (websites or Android apps) are allowed to share credentials.

Important: Password Manager treats credential sharing relationships as transitive.

To declare a credential sharing relationship:

1. Create an assetlinks.json file with statements linking to the website and to the Android app, following the DALs statement list syntax:

   [
     {
       "relation":[
         "delegate_permission/common.get_login_creds"
       ],
       "target":{
         "namespace":"web",
         "site":URL
       }
     },
     {
       "relation":[
         "delegate_permission/common.get_login_creds"
       ],
       "target":{
         "namespace":"android_app",
         "package_name":"APP_ID",
         "sha256_cert_fingerprints":[
           "SHA_HEX_VALUE"
         ]
       }
     }
   ]
   

   Where URL is your site's URL, APP_ID is your Android application ID, and SHA_HEX_VALUE is the SHA256 fingerprint of your Android app signing certificate.

   The relation field describes the relationship being declared. To declare that apps and sites share sign-in credentials, specify the relationships as delegate_permission/common.get_login_creds. Learn more about Relation Strings in DALs.

   The target field is an object that specifies the asset the declaration applies to.

   The following fields identify a website:

   namespace

   web

   site

   The website's URL, in the format https://domain[:optional_port]; for example, https://www.example.com. The domain must be fully-qualified, and optional_port must be omitted when using port 443 for HTTPS. A site target can only be a root domain: you cannot limit an app association to a specific subdirectory. Don't include a path in the URL, such as a trailing slash. Subdomains are not considered to match: that is, if you specify the domain as www.example.com, the domain www.counter.example.com is not associated with your app.

   The following fields identify an Android app:

   namespace	android_app
   package_name	The package name declared in the app's manifest. For example, com.example.android
   sha256_cert_fingerprints	The SHA256 fingerprints of your app's signing certificate.

   Important: When establishing seamless credential sharing between a website and an Android app, we include a self-referential statement in the website's assetlinks.json file. This is necessary because the Android app manifest references this file during subsequent configuration steps to enable password sharing.

2. Host the Digital Asset Links JSON file at the following location on the sign-in domains: https://DOMAIN[:OPTIONAL_PORT]/.well-known/assetlinks.json , where DOMAIN is fully-qualified, and OPTIONAL_PORT must be omitted when using port 443 for HTTPS.

   Note: The Digital Asset Links JSON file must be served as Content-Type: application/json in the HTTP headers, and it cannot be a redirect (see, Creating a Statement List).

3. Declare the association in the Android app by embedding a statement in your Android app's res/values/strings.xml file that links to the statement list you created in Step 1. Add an object that specifies the assetlinks.json files to load. For example:

     <string name="asset_statements" translatable="false">
   [{
     \"include\": \"https://DOMAIN[:OPTIONAL_PORT]/.well-known/assetlinks.json\"
   }]
   </string>
   

   Replace DOMAIN and OPTIONAL_PORT (must be omitted when using port 443 for HTTPS)—for example https://www.example.com. Escape any apostrophes and quotation marks you use in the string.

   You can also add a JSON snippet in your strings.xml file as shown in the DALs documentation, but using the include statement lets you change statements without publishing a new version of your app.

4. Reference the statement in the manifest by adding the following line to your app's AndroidManifest.xml file under <application>:

   <meta-data android:name="asset_statements" android:resource="@string/asset_statements"/>
   

5. Publish the new version of your Android app to the Google Play Developer Console

   Important: Seamless credential sharing will take effect only after you publish a new version of your Android app that includes a reference to the assetlinks.json file hosted on your website.

After following these steps, you have successfully set up seamless credential sharing between your website and your Android app.

Note that this is not the only valid way to set up DALs for credential sharing, but this approach simplifies the future process of adding new entities to your seamless credential sharing network, promotes code reusability, and reduces the potential for errors during updates.