Mobile Fallback Attestation
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 login.
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 Identity Server. The architecture is fully explained in the HAAPI Whitepaper.
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:
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 manufacturers 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 could have the same problem.
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 a secondary form of attestation 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.
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 fallback attestation, 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.
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.
A simple string 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.
The app can use a client certificate installed in a keystore on the device, then send proof of ownership to the Identity Server over a Mutual TLS connection. The Identity Server is configured to verify the trust chain of the client certificate. It must also allow Mutual TLS requests to the token endpoint.
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 Identity Server is configured with a way to get the public key of received assertions. In some setups, the easiest to manage option is to point to an external JWKS URI.
To use the highest security option for fallback attestation, a third party component is usually involved, which provisions Android keystores on each device. The two most common options are summarized below.
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 attestation. The Identity Server will be configured to trust credentials issued by the MDM system.
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 Identity Server will be configured to trust credentials issued by the framework.
To account for both types of user, two different OAuth clients are configured in the 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.
The security level with which each mobile user has performed attestation before authentication is represented by a
Client Assurance Level claim. This is issued in application level access tokens as a
cal value. APIs can use this claim to authorize requests to sensitive data, e.g, to deny access to high privilege operations such as money transfers, unless authentication strength is high.
|Client Assurance Level||Description|
|by-policy||The user retrieved a HAAPI access token via signing key attestation, with the properties configured in the Identity Server|
|by-provisioned-key||The user retrieved a HAAPI access token with credentials created via a client certificate or assymmetric key|
|none||The user retrieved a HAAPI access token via credentials created with a string client secret|
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 Identity Server 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.
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, fallback attestation 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 user will then be able to successfully use hypermedia based authentication.