Self-issued JWT for mobile client authentication

Overview

Mobile applications frequently authenticate their backend calls via JWT. These tokens are frequently used in conjunction with OIDC to authenticate a user. Sometimes, particularly in high-assurance scenarios, it can be preferable to authenticate both a user and a device. This article describes a JWT-based scheme that produces user and device authentication without abandoning the JWT transfer format.

In particular, we provide a blueprint implementation of both client—and server-side code that achieves the goal of secure identification of both user and client devices, preventing potentially unauthorized spread of credentials by insecure or compromised client devices.

Our approach leverages the secure enclave (StrongBox) keychain implemented in recent Android operating systems. It offers tamperproof storage of cryptographic material, with even the device owner unable to extract private keys. We can also require the operating system to require user authentication before signing operations.

Background

Our use case is an application that allows collaborating groups to access shared resources with elaborate security requirements. The application includes end-to-end encrypted chat, secure file sharing, and server-agnostic state changes. Due to the high sensitivity of shared content (financial and reputational risks), we need to prevent simple attacks (such as replay attacks) and attempts of key theft on compromised client devices.

Onboarding and device verification are not part of this document. We assume that operating system integrity is maintained (i.e., no rooted devices) to establish a trusted path towards the StrongBox module. StrongBox and its HSM protect the key material even on a compromised device. However, deep compromises can potentially still introduce problems, such as misuse of accessibility features in order to fake user interactions.

JWTs are an industry standard for exchanging authentication information. They consist of base-64 encoded JSON documents. Our scheme exclusively uses ECDSA-signed JWTs instead of the more common RSA and HMAC-based signature algorithms. The backend system exposes a REST interface and transmits the token using the usual mechanism (an Authorization header with the Bearer-Scheme).

Elliptic curve cryptography is a variant of the discrete logarithm problem with several attractive properties for a signature scheme. It features short key sizes and has withstood the test of time for both mathematical and computational attacks.

EC cryptography is well-established and available for all current operating systems and development platforms. It is one of the signature schemes supported by StrongBox.

Protocol

In our scheme, we utilize several standard JWT claims to identify the user, the device, and other required metadata to authenticate a client request. These are:

Header claims

• alg: Must be "ES256"
• typ: Must be "JWT"

Body claims

• sub - the standard subject claim. This claim contains the opaque user ID. Our application uses version 4 UUIDs to ensure that user IDs are distinct and not discoverable by iteration.
• iss: The "issuer" of the token is the device that performed the signature (also identified by a UUID). Although this claim is frequently understood to refer to a service URL, in our case, it identifies the second factor (the authorized device)
• aud: Identifies the service to authenticate against
• iat, exp: All tokens must declare both an issuing timestamp and expiry. Used in conjunction with jti to prevent replay attacks (see below)
• jti: The token identifier serves as a replay protection mechanism. Each token is single-use and "burned" afterward.

The server side imposes some constraints on top of the (client-controlled) claims. It ensures that iat within the interval of -5 to .1 seconds of the current server time. It ensures that exp is within the interval of -.1 to 5 seconds of current server time It matches the audience against a configured list of acceptable audiences It looks up a public key established for the iss/sub combination, and validates the signature against this key.

Serverside Implementation

As previously stated, signup and onboarding are out of scope for this document. For our example implementation, we assume a relational database backend comes preloaded with the following table:

1CREATE TABLE devices (
2   user_id UUID NOT NULL REFERENCES users(id),
3   device_id UUID NOT NULL,
4   public_key BYTEA NOT NULL,
5   PRIMARY KEY (user_id, device_id)
6)

In addition we maintain the following auxiliary table:

1CREATE TABLE burn_record (
2  user_id UUID NOT NULL REFERENCES users(id),
3  jti TEXT NOT NULL, 
4  expiry TIMESTAMP NOT NULL,
5  PRIMARY KEY (user_id, jti)
6)

Our server is implemented in Rust and utilizes the Axum framework as an HTTP server. Access checking and authorization are implemented in middleware, where protected routes (which are all but a handful of liveness/metrics endpoints) require the injection of an AuthorizedUser structure.

1#[derive(Debug, Copy, Clone, Deserialize, Serialize, FromSql, ToSql, PartialEq, Eq, Hash)]
2#[postgres(transparent)]
3pub struct DeviceId(Uuid);
4#[derive(Debug, Copy, Clone, Deserialize, Serialize, FromSql, ToSql, PartialEq, Eq, Hash)]
5#[postgres(transparent)]
6pub struct UserId(Uuid);
7
8pub struct AuthenticatedUser {
9    pub user_id: UserId,
10    pub device_id: DeviceId,
11}

Several potential storage mechanisms are supported, but in this document, we refer only to the relational DB storage introduced earlier.

1pub trait KeyStorage {
2    /** Retrieve the signing key for the specified user/device combo. Treat
3    the arguments as attacker-controlled (n.b. how they are not wrapped in an
4    `AuthenticatedUser`!). Implementors should perform the following steps in order:
5    
6    * Burn the token, reporting JTIAlreadyBurned if this user has already used the JTI
7    * Look up the user/device combinations key, returning UserDeviceNotFound if required
8    * Perform any implementation-dependant checks (such as user-locking) if supported
9    * Return the key
10    
11    */
12    fn burn_token_and_load_key(&self, token: String, user_id: UserId, device_id: DeviceId)
13        -> impl Future<Output = Result<Vec<u8>, KeyLoadError>>;
14}

With this abstraction, we can implement access checking as follows:

1impl<KL: KeyStorage + Send + Sync> FromRequestParts<KL> for AuthenticatedUser {
2    type Rejection = StatusCode;
3
4    fn from_request_parts(
5        parts: &mut Parts,
6        state: &KL,
7    ) -> impl Future<Output=Result<Self, Self::Rejection>> {
8        let auth = parts.headers.get("authorization");
9        async move {
10            let auth = extract_token_from_header_value(auth)?;
11
12            let (user_id, device_id, jti) =
13                extract_user_from_unverified_token(&auth)?;
14            let loaded_key = state
15                .burn_token_and_load_key(jti, user_id, device_id)
16                .await?;
17            let authenticated = validate_bearer_token_with_key(&auth, &loaded_key)?;
18
19            Ok(authenticated)
20        }
21    }
22}
23
24/* Interface with the axum header representation, and extract the bearer token - stripping the prefix and rejecting authentication if anything goes wrong */
25fn extract_token_from_header_value(auth: Option<&HeaderValue>) -> Result<String, AuthenticationError> {
26    let auth = auth.ok_or(AuthenticationError::Unauthenticated)?;
27    let auth = auth
28        .to_str()?
29        .trim();
30    let auth = auth
31        .strip_prefix("Bearer ")
32        .or_else(|| auth.strip_suffix("bearer "))
33        .ok_or(AuthenticationError::Unauthenticated)?;
34    Ok(auth.to_string())
35}
36
37/**
38Perform an unvalidated(!) parse of the token to extract iss and sub - the
39result of this parse is potentially attacker-controlled and must not be
40relied upon for anything but key lookup.
41
42Returns a tuple of (user_id, device_id, jti)
43*/
44fn extract_user_from_unverified_token(
45    auth: &str,
46) -> Result<(UserId, DeviceId, String), AuthenticationError> {
47    const DUMMY_KEY_FROM_UNVALIDATED_PARSE: &'static [u8] = &[];
48    if auth == "" {
49        return Err(AuthenticationError::Unauthenticated)?;
50    }
51
52    let mut extract_unvalidated = Validation::new(Algorithm::ES256);
53    extract_unvalidated.insecure_disable_signature_validation();
54    extract_unvalidated.validate_aud = false;
55    extract_unvalidated.validate_exp = false;
56
57    let pre_verification_token =
58        jsonwebtoken::decode::<Claims>(auth, &DecodingKey::from_ec_der(DUMMY_KEY_FROM_UNVALIDATED_PARSE), &extract_unvalidated)?;
59
60    Ok((UserId(Uuid::parse_str(&pre_verification_token.claims.sub)?),
61        DeviceId(Uuid::parse_str(&pre_verification_token.claims.iss)?), 
62        pre_verification_token.claims.jti))
63}
64
65/** Validate the bearer token against the loaded key */
66fn validate_bearer_token_with_key(
67    jwt: &str,
68    key: &[u8],
69) -> Result<AuthenticatedUser, AuthenticationError> {
70    let mut extract_verified = Validation::new(Algorithm::ES256);
71    extract_verified.validate_nbf = true;
72    extract_verified.set_audience(&CONFIG.acceptable_audiences);
73    let decoding_key = DecodingKey::from_ec_pem(&key);
74    let decoding_key = decoding_key?;
75    let token = jsonwebtoken::decode::<Claims>(
76        &jwt,
77        &decoding_key,
78        &extract_verified,
79    )?;
80
81    verify_timestamp_contraints(&token)?;
82
83    Ok(AuthenticatedUser {
84        user_id: UserId(Uuid::parse_str(&token.claims.sub)?),
85        device_id: DeviceId(Uuid::parse_str(&token.claims.iss)?),
86    })
87}

For completeness' sake, we use the following SQL commands to implement KeyStorage (slightly simplified):

impl KeyStorage for Client {
    fn burn_token_and_load_key(&self, token: String, user_id: UserId, device_id: DeviceId) -> impl Future<Output=Result<Vec<u8>, KeyLoadError>> {
      async move {
            load_keys(self, token, user_id, device_id).await
        }
    }
}

async fn load_keys(client: &Client, token: String,  user_id: UserId, device_id: DeviceId) -> Result<Vec<u8>, KeyLoadError> {
    let burn = client.execute("INSERT INTO burn_record (user_id, jti, expiry) VALUES ($1, $2, now() + INTERVAL 2 DAYS)", &[&user_id, &token]).await
    let Ok(burn_count) = burn else { return Err(KeyLoadError::JTIAlreadyBurned) };
    if burn_count != 1 {
        return Err(KeyLoadError::JTIAlreadyBurned);
    }
    let row = client.query_opt("SELECT public_key FROM devices WHERE user_id = $1 AND device_id = $2", &[&user_id, &device_id]).await;
    let Some(row) = row else { return Err(KeyLoadError::UserDeviceNotFound) };
    let key_material = row.map(|r|r.get("public_key"));
    Ok(key_material)
}

Clientside implementation

For client authentication, we have selected the fusionauth-jwt library (https://github.com/FusionAuth/fusionauth-jwt). This library allows an implementation of the Signer interface, which we use to interact with the StrongBox secure enclave.

The Android Keystore API leverages the java standard library, and is easy to interact with. Therefore, the implementation required for fusionauth is not complex:

1class SecureEnclaveSigner(val keyAlias: String) : Signer {
2    override fun getAlgorithm(): Algorithm {
3        return Algorithm.ES256
4    }
5
6    override fun sign(payload: String): ByteArray {
7        val data = payload.toByteArray(StandardCharsets.UTF_8)
8        val ks: KeyStore = KeyStore.getInstance("AndroidKeyStore").apply {
9            load(null)
10        }
11        val entry = ks.getEntry(keyAlias, null) as KeyStore.PrivateKeyEntry;
12        val derEncoded = Signature.getInstance("SHA256withECDSA").run {
13            initSign(entry.privateKey)
14            update(data)
15            sign()
16
17
18        }
19        return ECDSASignature(derEncoded).derDecode(algorithm)
20    }
21}

Due to this easy integration, we can fallback to the standard java APIs for signing, resulting in very ergonomic and easily-audited code.

We also include a simplified version of our signing key generator here for easy reference. This omits significant infrastructure code you would usually expect but showcases the general usage.

object SigningKeyGenerator {

    fun newKey(keyAlias: String, requireBiometrics: Boolean): PublicKey {
        val authRequirement = if (requireBiometrics) {
            AUTH_BIOMETRIC_STRONG
        } else {
            AUTH_DEVICE_CREDENTIAL
        }
        val keyPairGenerator = KeyPairGenerator.getInstance(
                KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
        keyPairGenerator.initialize(
            KeyGenParameterSpec.Builder(keyAlias, KeyProperties.PURPOSE_SIGN)
            .setAlgorithmParameterSpec(ECGenParameterSpec("secp256r1"))
            .setDigests(KeyProperties.DIGEST_SHA256,
                KeyProperties.DIGEST_SHA384,
                KeyProperties.DIGEST_SHA512)
            .setUserAuthenticationRequired(true)
            .setUserAuthenticationParameters(0, authRequirement)
            .setIsStrongBoxBacked(true)
            .build());
        val keyPair = keyPairGenerator.generateKeyPair();

        return keyPair.public!!
    }
}

Further work

While this article only deals with the Android enclave implementation, similar facilities exist in iOS, and future work could easily achieve similar results using the primitives available on Apple devices. This work hasn't been relevant to our use case, but it is very probably possible with relatively little effort.

Similarly, smartcard/dongle implementations or using PC TPM features were outside the scope of our project but could probably be implemented.

Some features (such as token burning) could be omitted in lesser-assurance situations.

As with any security-relevant solution, further research, independent validation, and public scrutiny are essential, which is part of what motivates this article.