codesanitize

Posted by Niharika Arora – Senior Developer Relations Engineer, Joseph Lewis – Employees Technical Author, and Kumareshwaran Sreedharan – Product Supervisor, Zoho.

As an Android developer, you are continually in search of methods to reinforce safety, enhance person expertise, and streamline improvement. Zoho, a complete cloud-based software program suite centered on safety and seamless experiences, achieved important enhancements by adopting passkeys of their OneAuth Android app.

Since integrating passkeys in 2024, Zoho achieved login speeds as much as 6x sooner than earlier strategies and a 31% month-over-month (MoM) development in passkey adoption.

This case research examines Zoho’s adoption of passkeys and Android’s Credential Supervisor API to deal with authentication difficulties. It particulars the technical implementation course of and highlights the impactful outcomes.

Overcoming authentication challenges

Zoho makes use of a mix of authentication strategies to guard person accounts. This included Zoho OneAuth, their very own multi-factor authentication (MFA) answer, which supported each password-based and passwordless authentication utilizing push notifications, QR codes, and time-based one-time passwords (TOTP). Zoho additionally supported federated logins, permitting authentication by way of Safety Assertion Markup Language (SAML) and different third-party id suppliers.

Challenges

Zoho, like many organizations, aimed to enhance authentication safety and person expertise whereas decreasing operational burdens. The first challenges that led to the adoption of passkeys included:

• Safety vulnerabilities: Conventional password-based strategies left customers inclined to phishing assaults and password breaches.
• Consumer friction: Password fatigue led to forgotten passwords, frustration, and elevated reliance on cumbersome restoration processes.
• Operational inefficiencies: Dealing with password resets and MFA points generated important assist overhead.
• Scalability considerations: A rising person base demanded a safer and environment friendly authentication answer.

Why the shift to passkeys?

Passkeys have been applied in Zoho’s apps to deal with authentication challenges by providing a passwordless method that considerably improves safety and person expertise. This answer leverages phishing-resistant authentication, cloud-synchronized credentials for easy cross-device entry, and biometrics (akin to a fingerprint or facial recognition), PIN, or sample for safe logins, thereby decreasing the vulnerabilities and inconveniences related to conventional passwords.

By adopting passkeys with Credential Supervisor, Zoho minimize login occasions by as much as 6x, slashed password-related assist prices, and noticed robust person adoption – doubling passkey sign-ins in 4 months with 31% MoM development. Zoho customers now get pleasure from sooner, simpler logins and phishing-resistant safety.

Implementation with Credential Supervisor on Android

So, how did Zoho obtain these outcomes? They used Android’s Credential Supervisor API, the beneficial Jetpack library for implementing authentication on Android.

Credential Supervisor offers a unified API that simplifies dealing with of the varied authentication strategies. As a substitute of juggling totally different APIs for passwords, passkeys, and federated logins (like Sign up with Google), you utilize a single interface.

Implementing passkeys at Zoho required each client-side and server-side changes. This is an in depth breakdown of the passkey creation, sign-in, and server-side implementation course of.

Passkey creation

To create a passkey, the app first retrieves configuration particulars from Zoho’s server. This course of features a distinctive verification, akin to a fingerprint or facial recognition. This verification knowledge, formatted as a requestJson string), is utilized by the app to construct a CreatePublicKeyCredentialRequest. The app then calls the credentialManager.createCredential methodology, which prompts the person to authenticate utilizing their machine display screen lock (biometrics, fingerprint, PIN, and so on.).

Upon profitable person affirmation, the app receives the brand new passkey credential knowledge, sends it again to Zoho’s server for verification, and the server then shops the passkey info linked to the person’s account. Failures or person cancellations throughout the course of are caught and dealt with by the app.

Signal-in

The Zoho Android app initiates the passkey sign-in course of by requesting sign-in choices, together with a singular problem, from Zoho’s backend server. The app then makes use of this knowledge to assemble a GetCredentialRequest, indicating it’ll authenticate with a passkey. It then invokes the Android CredentialManager.getCredential() API with this request. This motion triggers a standardized Android system interface, prompting the person to decide on their Zoho account (if a number of passkeys exist) and authenticate utilizing their machine’s configured display screen lock (fingerprint, face scan, or PIN). After profitable authentication, Credential Supervisor returns a signed assertion (proof of login) to the Zoho app. The app forwards this assertion to Zoho’s server, which verifies the signature towards the person’s saved public key and validates the problem, finishing the safe sign-in course of.

Server-side implementation

Zoho’s transition to supporting passkeys benefited from their backend programs already being FIDO WebAuthn compliant, which streamlined the server-side implementation course of. Nonetheless, particular modifications have been nonetheless needed to totally combine passkey performance.

Essentially the most important problem concerned adapting the credential storage system. Zoho’s present authentication strategies, which primarily used passwords and FIDO safety keys for multi-factor authentication, required totally different storage approaches than passkeys, that are based mostly on cryptographic public keys. To deal with this, Zoho applied a brand new database schema particularly designed to securely retailer passkey public keys and associated knowledge in keeping with WebAuthn protocols. This new system was constructed alongside a lookup mechanism to validate and retrieve credentials based mostly on person and machine info, making certain backward compatibility with older authentication strategies.

One other server-side adjustment concerned implementing the power to deal with requests from Android gadgets. Passkey requests originating from Android apps use a singular origin format (android:apk-key-hash:instance) that’s distinct from normal internet origins that use a URI-based format (https://instance.com/app). The server logic wanted to be up to date to accurately parse this format, extract the SHA-256 fingerprint hash of the app’s signing certificates, and validate it towards a pre-registered listing. This verification step ensures that authentication requests genuinely originate from Zoho’s Android app and protects towards phishing assaults.

This code snippet demonstrates how the server checks for the Android-specific origin format and validates the certificates hash:

val origin: String = clientData.getString("origin")

if (origin.startsWith("android:apk-key-hash:")) { 
    val originSplit: Checklist = origin.cut up(":")
    if (originSplit.measurement > 3) {
               val androidOriginHashDecoded: ByteArray = Base64.getDecoder().decode(originSplit[3])

                if (!androidOriginHashDecoded.contentEquals(oneAuthSha256FingerPrint)) {
            throw IAMException(IAMErrorCode.WEBAUTH003)
        }
    } else {
        // Optionally available: Deal with the case the place the origin string is malformed    }
}

Error dealing with

Zoho applied sturdy error dealing with mechanisms to handle each user-facing and developer-facing errors. A typical error, CreateCredentialCancellationException, appeared when customers manually canceled their passkey setup. Zoho tracked the frequency of this error to evaluate potential UX enhancements. Based mostly on Android’s UX suggestions, Zoho took steps to higher educate their customers about passkeys, guarantee customers have been conscious of passkey availability, and promote passkey adoption throughout subsequent sign-in makes an attempt.

This code instance demonstrates Zoho’s method for a way they dealt with their commonest passkey creation errors:

personal enjoyable handleFailure(e: CreateCredentialException) {
    val msg = when (e) {
        is CreateCredentialCancellationException -> {
            Analytics.addAnalyticsEvent(eventProtocol: "PASSKEY_SETUP_CANCELLED", GROUP_NAME)
            Analytics.addNonFatalException(e)
            "The operation was canceled by the person."
        }
        is CreateCredentialInterruptedException -> {
            Analytics.addAnalyticsEvent(eventProtocol: "PASSKEY_SETUP_INTERRUPTED", GROUP_NAME)
            Analytics.addNonFatalException(e)
            "Passkey setup was interrupted. Please attempt once more."
        }
        is CreateCredentialProviderConfigurationException -> {
            Analytics.addAnalyticsEvent(eventProtocol: "PASSKEY_PROVIDER_MISCONFIGURED", GROUP_NAME)
            Analytics.addNonFatalException(e)
            "Credential supplier misconfigured. Contact assist."
        }
        is CreateCredentialUnknownException -> {
            Analytics.addAnalyticsEvent(eventProtocol: "PASSKEY_SETUP_UNKNOWN_ERROR", GROUP_NAME)
            Analytics.addNonFatalException(e)
            "An unknown error occurred throughout Passkey setup."
        }
        is CreatePublicKeyCredentialDomException -> {
            Analytics.addAnalyticsEvent(eventProtocol: "PASSKEY_WEB_AUTHN_ERROR", GROUP_NAME)
            Analytics.addNonFatalException(e)
            "Passkey creation failed: ${e.domError}"
        }
        else -> {
            Analytics.addAnalyticsEvent(eventProtocol: "PASSKEY_SETUP_FAILED", GROUP_NAME)
            Analytics.addNonFatalException(e)
            "An sudden error occurred. Please attempt once more."
        }
    }
}

Testing passkeys in intranet environments

Zoho confronted an preliminary problem in testing passkeys inside a closed intranet setting. The Google Password Supervisor verification course of for passkeys requires public area entry to validate the relying social gathering (RP) area. Nonetheless, Zoho’s inside testing setting lacked this public Web entry, inflicting the verification course of to fail and hindering profitable passkey authentication testing. To beat this, Zoho created a publicly accessible check setting, which included internet hosting a short lived server with an asset hyperlink file and area validation.

This instance from the assetlinks.json file utilized in Zoho’s public check setting demonstrates the best way to affiliate the relying social gathering area with the desired Android app for passkey validation.

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "goal": {
            "namespace": "android_app",
            "package_name": "com.zoho.accounts.oneauth",
            "sha256_cert_fingerprints": [
                "SHA_HEX_VALUE" 
            ]
        }
    }
]

Combine with an present FIDO server

Android’s passkey system makes use of the trendy FIDO2 WebAuthn normal. This normal requires requests in a particular JSON format, which helps keep consistency between native purposes and internet platforms. To allow Android passkey assist, Zoho did minor compatibility and structural adjustments to accurately generate and course of requests that adhere to the required FIDO2 JSON construction.

This server replace concerned a number of particular technical changes:

// Convert rawId bytes to a normal Base64 encoded string for storage
val base64RawId: String = Base64.getEncoder().encodeToString(rawId.toByteArray())

2. Transport listing format: To make sure constant knowledge processing, the server logic handles lists of transport mechanisms (akin to USB, NFC, and Bluetooth, which specify how the authenticator communicated) as JSON arrays.

3. Consumer knowledge alignment: The Zoho staff adjusted how the server encodes and decodes the clientDataJson discipline. This ensures the information construction aligns exactly with the expectations of Zoho’s present inside APIs. The instance under illustrates a part of the conversion logic utilized to shopper knowledge earlier than the server processes it:

personal enjoyable convertForServer(sort: String): String {
    val clientDataBytes = BaseEncoding.base64().decode(sort)
    val clientDataJson = JSONObject(String(clientDataBytes, StandardCharsets.UTF_8))
    val clientJson = JSONObject()
    val challengeFromJson = clientDataJson.getString("problem")
    // 'problem' is a technical identifier/token, not localizable textual content.
    clientJson.put("problem", BaseEncoding.base64Url()
        .encode(challengeFromJson.toByteArray(StandardCharsets.UTF_8))) 

    clientJson.put("origin", clientDataJson.getString("origin"))
    clientJson.put("sort", clientDataJson.getString("sort"))
    clientJson.put("androidPackageName", clientDataJson.getString("androidPackageName"))
    return BaseEncoding.base64().encode(clientJson.toString().toByteArray())
}

Consumer steering and authentication preferences

A central a part of Zoho’s passkey technique concerned encouraging person adoption whereas offering flexibility to align with totally different organizational necessities. This was achieved by way of cautious UI design and coverage controls.

Zoho acknowledged that organizations have various safety wants. To accommodate this, Zoho applied:

• Admin enforcement: By the Zoho Listing admin panel, directors can designate passkeys because the obligatory, default authentication methodology for his or her whole group. When this coverage is enabled, workers are required to arrange a passkey upon their subsequent login and use it going ahead.
• Consumer alternative: If a corporation doesn’t implement a particular coverage, particular person customers keep management. They’ll select their most popular authentication methodology throughout login, choosing from passkeys or different configured choices through their authentication settings.

To make adopting passkeys interesting and simple for end-users, Zoho applied:

• Simple setup: Zoho built-in passkey setup straight into the Zoho OneAuth cell app (obtainable for each Android and iOS). Customers can conveniently configure their passkeys inside the app at any time, smoothing the transition.
• Constant entry: Passkey assist was applied throughout key person touchpoints, making certain customers can register and authenticate utilizing passkeys through:
• The Zoho OneAuth cell app (Android & iOS);

This methodology ensured that the method of establishing and utilizing passkeys was accessible and built-in into the platforms they already use, no matter whether or not it was mandated by an admin or chosen by the person. You’ll be able to study extra about the best way to create easy person flows for passkey authentication by exploring our complete passkeys person expertise information.

Impression on developer velocity and integration effectivity

Credential Supervisor, as a unified API, additionally helped enhance developer productiveness in comparison with older sign-in flows. It decreased the complexity of dealing with a number of authentication strategies and APIs individually, resulting in sooner integration, from months to weeks, and fewer implementation errors. This collectively streamlined the sign-in course of and improved total reliability.

By implementing passkeys with Credential Supervisor, Zoho achieved important, measurable enhancements throughout the board:

• Dramatic pace enhancements
• 2x sooner login in comparison with conventional password authentication.
• 4x sooner login in comparison with username or cell quantity with electronic mail or SMS OTP authentication.
• 6x sooner login in comparison with username, password, and SMS or authenticator OTP authentication.
• Diminished assist prices
• Diminished password-related assist requests, particularly for forgotten passwords.
• Decrease prices related to SMS-based 2FA, as present customers can onboard straight with passkeys.
• Robust person adoption & enhanced safety:
• Passkey sign-ins doubled in simply 4 months, displaying excessive person acceptance.
• Customers migrating to passkeys are totally protected from widespread phishing and password breach threats.
• With 31% MoM adoption development, extra customers are benefiting each day from enhanced safety towards vulnerabilities like phishing and SIM swaps.

Suggestions and finest practices

To efficiently implement passkeys on Android, builders ought to contemplate the next finest practices:

• Leverage Android’s Credential Supervisor API:
• Credential Supervisor simplifies credential retrieval, decreasing developer effort and making certain a unified authentication expertise.
• Handles passwords, passkeys, and federated login flows in a single interface.
• Guarantee knowledge encoding consistency whereas migrating from different FIDO authentication options:
• Be sure you deal with constant formatting for all inputs/outputs whereas migrating from different FIDO authentication options akin to FIDO safety keys.
• Optimize error dealing with and logging:
  • Implement sturdy error dealing with for a seamless person expertise.
  • Present localized error messages and use detailed logs to debug and resolve sudden failures.
• Educate customers on passkey restoration choices:
• Stop lockout situations by proactively guiding customers on restoration choices.
• Monitor adoption metrics and person suggestions:
  • Observe person engagement, passkey adoption charges, and login success charges to maintain optimizing person expertise.
  • Conduct A/B testing on totally different authentication flows to enhance conversion and retention.

Passkeys, mixed with the Android Credential Supervisor API, supply a robust, unified authentication answer that enhances safety whereas simplifying person expertise. Passkeys considerably scale back phishing dangers, credential theft, and unauthorized entry. We encourage builders to check out the expertise of their app and produce essentially the most safe authentication to their customers.

Get began with passkeys and Credential Supervisor

Get fingers on with passkeys and Credential Supervisor on Android utilizing our public pattern code.

In case you have any questions or points, you’ll be able to share with us by way of the Android Credentials points tracker.