# FIDO2 API for Android

The FIDO2 API allows Android applications to create and use strong, attested
public key- based credentials for the purpose of authenticating users. The API
provides a [WebAuthn Client](https://www.w3.org/TR/webauthn/#webauthn-client)
implementation, which supports the use of BLE, NFC, and USB roaming
authenticators (security keys) as well as a platform authenticator, which allows
the user to authenticate using their fingerprint or screen lock.

> [!NOTE]
> **Note:** If your app requires passkeys, you should use [Credential Manager](https://developers.google.com/identity/android-credential-manager) instead.

## Integration

The [FIDO2 API](https://developers.google.com/android/reference/com/google/android/gms/fido/fido2/package-summary)
entry point is the [Fido2ApiClient](https://developers.google.com/android/reference/com/google/android/gms/fido/fido2/Fido2ApiClient).

The API supports two operations:

- [Registration](https://developers.google.com/android/reference/com/google/android/gms/fido/fido2/Fido2ApiClient#getRegisterIntent(com.google.android.gms.fido.fido2.api.common.MakeCredentialOptions)) is done once per authenticator per account, when the user associates an authenticator with an account.
- [Signing](https://developers.google.com/android/reference/com/google/android/gms/fido/fido2/Fido2ApiClient#getSignIntent(com.google.android.gms.fido.fido2.api.common.PublicKeyCredentialRequestOptions)) is done whenever the relying party wants to authenticate a user.

Both registration and signing require user interaction.

## Interoperability with your website

It is simple to allow users to seamlessly share credentials across your website
and Android application. To do so, leverage [the Digital Asset Links](https://digitalassetlinks.org).
You can declare associations by hosting a Digital Asset Links JSON file on your
website, and adding a link to the Digital Asset Link file to your app's manifest.

For example, if you want to associate `https://example.com` with an Android app
`com.example.android`, here's 3 required steps:

### Step 1. Host `assetlinks.json` at your domain

Create a JSON file like this and host it at `https://example.com/.well-known/assetlinks.json`.

    [
      {
        "relation" : [
          "delegate_permission/common.handle_all_urls",
          "delegate_permission/common.get_login_creds"
        ],
        "target" : {
          "namespace" : "web",
          "site" : "https://example.com"
        }
      },
      {
        "relation" : [
          "delegate_permission/common.handle_all_urls",
          "delegate_permission/common.get_login_creds"
        ],
        "target" : {
          "namespace" : "android_app",
          "package_name" : "com.example.android",
          "sha256_cert_fingerprints" : [
             "DE:AD:BE:EF"
          ]
        }
      }
    ]

Make sure it's crawlable from Google and is served with HTTP header
`Content-Type: application/json`.

`sha256_cert_fingerprints` is the SHA256 fingerprints of your app's signing certificate.
Find more details in the [Android App Links documentation](https://developer.android.com/training/app-links/verify-site-associations#web-assoc).

> [!NOTE]
> **Note:** The `relation` will eventually only require `"delegate_permission/common.get_login_creds"` in order to share credentials between websites and apps, however, until we complete migrating our logic to accept it, please include both `"delegate_permission/common.handle_all_urls"` and `"delegate_permission/common.get_login_creds"`.

### Step 2. Link to `assetlinks.json` in Android app

In your Android app, add the following line to the manifest file under `<application>`:

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

### Step 3. Add an `asset_statements` string resource to the strings.xml file

The `asset_statements` string is a JSON object that specifies the `assetlinks.json`
files to load. You must escape any apostrophes and quotation marks you use in
the string. For example:

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

To learn more about associating your app and your website, read the [SmartLock
for Passwords on Android documentation](https://developers.google.com/identity/smartlock-passwords/android/associate-apps-and-sites).