Application Installation Attributes

Application installation attributes allow arbitrary attributes to be set for a particular app installation. These attributes are stored securely in the app installation and are included in all subsequent Approov tokens fetched by the installation, in the embed claim. The attributes may be arbitrary formed JSON set by your backend application.

When an app is first installed it will not have any of these embedded attributes. The idea is that these should be added by your backend application as more data is gathered about the app installation, and the user of that app. For instance, this mechanism can be used to mark that an app installation has completed particular security gates after initial installation to demonstrate the veracity of the installation and the user. The backend application can determine the current state by reading the embedded claim in the Approov token.

New installation attributes are added via a call made by the app to the Approov SDK. The information is then transmitted to the Approov servers for validation, and if it is accepted it is strongly protected against any tampering. Thus your backend application can trust the embedded attributes presented in the Approov token.

In order to make the system secure, although the data is set inside the app, it must actually be signed by your backend systems. To achieve this the installation attributes are actually provided as the payload of a signed JWT. These JWTs are also given expiry times and are also bound to particular device IDs. It is only if the token is correctly signed and meets all other requirements that the installation attributes are accepted. Thus such attributes can never be spoofed by the mobile application alone.

The keys used to sign and verify installation attributes tokens are managed by Approov. In order to cleanly handle key rotation, and to support various different key signing algorithms, Approov is able to manage a number of different installation token signing keys. A token may be signed by any one of these.

info

A maximum size is imposed for installation attributes tokens of 2KB. This means that the maximum size of the attributes payload will be somewhat smaller than this, depending on the signature size for the JWT. Attempts to set a token larger than this will generate an error.

warning

Application installation attributes can only be set in 3.4.0 and later SDKs.

note

The information in the installation attributes token must be sent to the Approov servers for it to be verified, and for its payload data to be persisted in the device state and included in subsequently issued Approov tokens. Note that the Approov services only hold this data temporarily and no long term copy of the data is made. You must consider this with respect to Personal Identifiable Information (PII) compliance. It is typically best if the installation attributes do not directly identify individual users, but only provides hashes of such data or confirmations that certainly security checks have been completed.

Setting Installation Attributes

In order to set installation attributes it is necessary to create a signed JSON Web Token containing a payload of the installation attributes. This token must be signed on your backend systems and then sent to the running mobile app. Since the signing is done server side the key material is never exposed to mobile apps, so it is not possible for such attributes to be forged by a client side attack.

The JWT has the following requirements:

• The JWT header must contain a kid claim with the name of the signing key that is being used. This must correspond to an active installation attributes key in Approov. The alg field must also be consistent with the key signing type.
• The payload must contain an exp claim providing an expiry for the token. You may set any value for this that you wish, but we suggest that lifetimes should be restricted to 5 minutes or less. The token only needs to be active long enough to be transmitted from your servers back to the app, and then on to the Approov servers for verification.
• The payload should also contain a did claim providing the base64 encoded device ID to which the token is being issued. This should be identical to the did field in the Approov token received. This provides an additional level of security to ensure attributes can only be applied to the correct app installation.

There are various JWT Libraries available for signing tokens. Please contact Approov support if you need any assistance in creating valid tokens. We anticipate that in the future we will also expand our backend API integrations with additional specific information about installation attribute token creation.

Once the token is signed it can be transmitted to the app as part of a request response. Inside the app, the installation attributes token may be set using the setInstallAttrsInToken method in the SDK. It is necessary to make another Approov token fetch to ensure that this information has been transmitted to the Approov server. Typically though the Mobile App Quickstarts will also provide a way to call this method and will also ensure that a new Approov token is fetch immediately to ensure that the data has been communicated correctly.

The installation attributes are then available in the embed claim of the generated Approov token. The same value is retained in all subsequently generated Approov tokens until it is changed with another setInstallAttrsInToken call.

Your backend may then use the embed claim as reliable information that has been supplied to a particular app installation. If the app is uninstalled then this information will be lost.

tip

To assist your development, the Approov CLI includes commands to generate example installation attributes tokens for your testing. There is also an option to verify tokens that you have created to ensure that they meet the requirements.

warning

Note that once a embed claim has been added it is not possible to remove its inclusion completely from the running app, only change its value with a new valid installation attributes token.

Adding a New Installation Key

A new, randomly generated, installation attributes token signing key can be added as follows. You must specify the name which you wish to give the key and the algorithm used for signing as follows:

approov installattrs -kid your-key -add ES256

In this case a new key named your-key is generated for use with the ES256 signing algorithm. A random ECC private key is generated by Approov and added to your account.

The following signing algorithm are available:

• HS256, HS384, HS512: These HMAC signing methods use a symmetric key, with differing hashing algorithms.
• RS256, RS384, RS512: These use RSASSA-PKCS1-v1_5 asymmetric cryptography, with differing hashing algorithms.
• PS256, PS384, PS512: These use RSASSA-PSS asymmetric cryptography, with differing hashing algorithms.
• ES256, ES384, ES512: These use ECDSA asymmetric cryptography, with differing hashing algorithms. ES256 uses curve P-256 (secp256r1), ES384 uses P-384 (secp384r1), and ES512 uses P-521 (secp521r1).

This article provides a good overview of the different options.

It is also possible to specify a key length override parameter when specifying an algorithm that uses RSA (RS256, RS384, RS512, PS256, PS384, PS512) or symmetric keys (HS256, HS384, HS512).

approov installattrs -add RS256 -kid your-key -keyLength 4096

The default length for an RSA key is 2048 bits, but it may be overridden to 1024 or 4096 bits. The default length for a symmetric key is 256 bits, but may be overridden to 128 or 512 bits.

info

It is only possible to have a maximum of 5 application installation keys at any one time.

Listing Installation Keys

The current keys that are valid for application attributes tokens are listed as follows:

approov installattrs -list

The key ID is shown alongside the algorithm associated with each key.

1 key:
 your-key  alg:ES256

Removing Installation Keys

An installation attributes key can be removed as follows:

approov installattrs -kid your-key -remove

Note that you need an admin role to remove a key and you will need to provide confirmation. Any installation attributes tokens signed with the removed key will no longer be accepted.

Getting Private Installation Key PEM

It is possible to obtain the PEM file for a specific private key. Obtain the PEM as follows:

approov installattrs -kid your-key -getPEM your-key.pem

The contents of the your-key.pem file will be something like the following:

-----BEGIN PRIVATE KEY-----
MIGfMA0GCSqGSIb3DQEBAQU...
-----END PRIVATE KEY-----

Various languages may support this format to define the private key that you are going to use in your backend to create installation attributes tokens. It is only possible to obtain a PEM for RSA and ECDSA key types, that use asymmetric cryptography.

Getting Installation Keys JWKS

It is possible to obtain the JSON Web Key Set for all keys as follows:

approov installattrs -getJWKS keys.jwks

The contents of the keys.jwks will be something like the following:

{
  "keys": [
    {
      "alg": "ES256",
      "crv": "P-256",
      "d": "r6Ehii2dXfeM...",
      "kid": "your-key",
      "kty": "EC",
      "use": "sig",
      "x": "BfOBn3oodNo...",
      "y": "6HUHrnhLdT6..."
    }
  ]
}

This contains all of the private keys that can be used to sign installation attributes tokens. Note that you need an admin role to get the JWKS for the key set.

Importing Installation Keys

It is possible to import a JSON Web Key as an installation attributes token signing key. Imagine you have a file byok.jwk with the following content:

{
  "alg": "RS256",
  "use": "sig",
  "d": "FumDxNCs...",
  "dp": "mUxVEADBN...",
  "dq": "Yv9xjIj5vOo...",
  "e": "AQAB",
  "kid": "byok",
  "kty": "RSA",
  "n": "05yGbvzgIobbtaeJ...",
  "p": "9_NNlMTz_S5jcxORGz...",
  "q": "2ns2LBc5-1f3m7iI...",
  "qi": "TxLIVbqDsTvmhTgmR..."
}

Import it as follows:

approov installattrs -import byok.jwk

A kid claim must be present and not be the same as any existing key in the key set. The alg and use claims must also be present and be consistent with algorithms supported by Approov, or else the import request will be rejected.

Generating Example Installation Attributes Tokens

It is possible to generate example installation attribute instructions if you provide a JSON file with the payload contents that you want. For instance create a file attrs.json containing the following:

{
 "did": "qZka0yfv+ExvOq3PRh6pGw==",
 "my-claim": "include me in Approov token"
}

This must include a did claim, and it can only be used on that particular device ID. An expiry claim will be added automatically. Otherwise you are free to add your own claims depending upon the requirements of your application.

Create the token as follows, supplying the name of the file containing the payload and the ID of the key you wish it to be signed by:

approov installattrs -genExample attrs.json -kid your-key

This generates the example token as the output. The result is a valid token that lasts for one hour. The extended expiry time of these tokens provides for longer debug sessions using the example token.

Verifying Installation Attributes Tokens

A verification option is provided for installation attributes tokens. Simply use:

approov installattrs -verify eyJhbGciOi…

Which will output something like the following:

passed: {"did":"qZka0yfv+ExvOq3PRh6pGw==","exp":1737315313,"my-claim":"include me in Approov token"}

The payload content is decoded, and information is provided about whether the token is passed or failed. Expired tokens are still considered to be passed, to assist with debug of tokens extracted from logs where tokens may have since expired.