Mobile Attestation Fallback

Intro

The Hypermedia Authentication API (HAAPI) enables OpenID Connect to be implemented in an API driven manner, without the need for the system browser. This improves the user experience, since in most cases the user does not need to leave the app in order to log in.

HAAPI also strengthens security by verifying the mobile client's identity before the authentication flow is allowed to begin, then using an access token for every authentication request to the Curity Identity Server. The architecture is fully explained in the HAAPI Whitepaper.

Client Attestation via Signing Keys

When a mobile app is published to an app store it is signed with a private key issued by Apple or Google. The most secure attestation option is to use hardware support on modern devices to access the corresponding public certificate details. This data is cryptographically verified, along with the trust chain, up to the Apple or Google root authority. The security details are managed by simply integrating and configuring an SDK, as explained in these tutorials:

• iOS HAAPI Overview
• Android HAAPI Overview

Non-Compliant Devices

For the signing key-based client attestation method to work, there must be hardware support, and this can sometimes be uncertain when users bring their own device. This is especially true for the Android platform, where devices have been issued by various vendors for many years.

Older Android devices, such as those released before Android 8, will not have the hardware support needed for signing key-based attestation, and upgrading the Android operating system does not fix this problem. Other categories of device, from particular manufacturers, could have the same problem.

Multiple Users and Client Attestation

Signing key-based attestation should remain the default behavior, for most users. For other devices a secondary credential must be used as a backup option, so that all users can authenticate successfully. The Android app needs to be coded to work for both categories of user.

The following simplified diagram shows the same app being used by multiple users, where for most users the app is attested in the preferred way, but the app provides an alternative for users with non-compliant devices.

The diagram represents a simplified version of events, since a number of other messages are used, as described in the whitepaper. The final result will be that all users of the app receive an access token with a haapi scope, so that API driven authentication can begin.

Attestation Fallback with Dynamic Clients

Non-compliant devices provide their alternative proof via the Client Credentials Flow, in a request for an access token with the dcr scope. There are multiple ways in which the credential can be supplied during this request. The dcr access token is then returned, and used in a Dynamic Client Registration (DCR) request:

A dynamic client is then registered for each user that uses the fallback, and the mechanism supports a different DCR credential per user. Use of a separate dynamic client per mobile user is discussed further in Mobile Best Practices.

The dynamic client ID and secret are then stored securely on the device by the SDK. From that point onwards, whenever authentication begins, the app must first present its dynamic client ID and client secret to get a HAAPI access token.

Attestation Fallback Credentials

Various ways to onboard users can be designed, based on the credential types the client credentials flow supports, and there are also many ways of provisioning credentials using Android keystores. The most secure options use a different cryptographic credential per user as discussed in the following sections.

Client Secret

A simple client secret can be used to make the client credentials request, which will then need to be the same for all users. This is not a secure option, but can be useful in some setups, such as when first getting integrated, or as a solution for a development stage of the deployment pipeline.

Client Certificate

The app can use a client certificate installed in a keystore on the device, then send proof of ownership to the Curity Identity Server over a Mutual TLS connection. The Curity Identity Server is configured to verify the trust chain of the client certificate. It must also allow Mutual TLS requests to the token endpoint.

Client Assertion

The app can load an asymmetric keypair installed in a keystore on the device, then use it to produce a JWT Client Assertion, which it then sends as proof of ownership. The Curity Identity Server is then configured with a way to get the public key with which to verify received assertions.

Device Specific Credentials

To use the highest security option for attestation fallback, a third party component is usually involved, which provisions Android keystores on each device. The two most common options are summarized below.

Mobile Device Management

In some corporate setups it is common that all devices integrate with a Mobile Device Management (MDM) system. In these cases it is common for each user to already have a distinct key or certificate installed on the device, which the mobile app can retrieve and use for DCR registration. The Curity Identity Server will be configured to trust credentials issued by the MDM system.

Bring your Own Device

In internet setups there is no control over devices, and it is common to instead use a software attestation framework within the app. This will follow the same principles of supplying a unique registration client credential per user. The Curity Identity Server will be configured to trust credentials issued by the framework.

Client Management

To account for both types of user, two different OAuth clients are configured in the Curity Identity Server. The first of these is the main HAAPI client, which must be updated with an authentication method, so that requests with a DCR client credential can be verified.

Next, a template client is configured, with the same OAuth settings as the HAAPI client. DCR requests from the HAAPI SDK will supply the Software ID of this client when they register, resulting in the actual dynamic clients being created.

Use of a template client ensures that settings are easy to manage over time. For example, to add a scope to the mobile app it is added to both the HAAPI client and the template client, and it will then come into immediate effect for all previously created dynamic clients.

Client Assurance Level

After successful user authentication, a Client Assurance Level authentication attribute is available, to represent the strength with which the client proved its identity. This can be issued to access tokens or ID tokens. APIs can use the access token claim when authorizing requests to sensitive data, e.g, to deny access to high privilege operations such as money transfers, unless there is a strong level of client assurance.

Worked Example

The Implementing HAAPI Fallback tutorial provides worked examples of using DCR fallback. This first runs the Android HAAPI Code Example with a simple string secret, to explain the Curity Identity Server configuration and code changes. It then explains how to use stronger credentials based on Android keystores, to send either a client certificate or a client assertion during DCR registration.

Conclusion

The Hypermedia Authentication API requires a mobile app's client identity to be verified before allowing authentication to be attempted. The preferred way to do this, for the majority of users, is by verifying the public signing certificate details of the production app.

For the minority of users who have non-compliant devices, attestation fallback can be used. This is done using dynamic client registration, and supports a separate onboarding credential per user. Strong credentials based on public key infrastructure (PKI) is recommended. Both categories of users will then be able to successfully use hypermedia-based authentication.