Attestation and Fallback#

Attestation is how the Curity Identity Server confirms that an HAAPI request originates from a genuine, unmodified copy of a registered mobile app — not from a tampered binary, an emulator, or a script masquerading as the client. Because HAAPI exposes the full authentication flow to API callers, this assurance is what allows public clients (apps without a static secret) to obtain access tokens safely.

How It Works#

The client performs a platform-specific attestation protocol on first use:

• iOS uses Apple’s DCAppAttestService to generate a cryptographic key whose authenticity Apple has signed.
• Android uses hardware-backed Key Attestation; the device’s TEE or StrongBox produces a certificate chain rooted in Google’s hardware-attestation CA.

The client sends the resulting attestation data to the Curity Identity Server, which validates the platform’s signature, checks any configured policy (boot state, security level, certificate chain), and on success issues a Client Attestation Token (CAT). The CAT is exchanged for an HAAPI access token at the token endpoint.

Server-Side Configuration#

OAuth clients carry their attestation settings under <attestation>, with one sub-element per platform.

For Android, declare the application package name and the SHA-256 hash of the signing certificate (Base64-encoded):

<attestation>
    <android>
        <package-name>com.example.client.app</package-name>
        <signature-digest>Z2DK...9oKQ=</signature-digest>
    </android>
</attestation>

For iOS, declare the Apple-assigned app-id (team ID plus bundle ID, separated by a dot) and a reference to the iOS attestation policy:

<attestation>
    <ios>
        <app-id>AAAAAAAA.com.example.client.app</app-id>
        <ios-policy>policy</ios-policy>
    </ios>
</attestation>

Custom attestation policies — useful for emulators or non-production builds — are defined under facilities/client-attestation and explicitly referenced from the client.

When Attestation Is Not Available#

Some devices cannot attest: jailbroken phones, simulators during development, older operating system versions, or rare hardware faults reported by Apple as Error Domain=com.apple.devicecheck.error Code=3. For these, the Curity Identity Server supports a fallback based on Dynamic Client Registration: the app uses a configured main HAAPI client to register a per-device dynamic client, then uses that dynamic client for subsequent token requests. The fallback is secure but loosens the guarantees attestation provides, so enable it only when the trade-off is acceptable.