Architecture & Security

Token Format

The Approov service uses JSON Web Tokens (JWTs) to represent the authenticity of client apps. This in an open and standard mechanism for representing claims in a tamper proof form and your web service will need to decode and verify these tokens as part of the Approov flow. An Approov token is typically a JWS (a type of JWT) which consists of three parts; the header, payload and signature where each part is base64url encoded and the parts are separated by periods. For a more in depth explanation off JWT tokens, please read this introduction.

JWT libraries take responsibility for generating the header and the signature. We just need to specify the signing algorithm we want to use, the secret key for the algorithm, and the un-encoded payload part. For JWTs, the payload is always a JSON object with the entries referred to as claims.

JWS Token Signing

This section describes the approach used to create signed JWTs (called JWS to differentiate them from JWE tokens which are encrypted). If an app has passed the attestation process according to the selected rejection policy, then a correctly signed token is issued. If the rejection policy causes the app to fail attestation then a token is still issued, but it will not be correctly signed. An observer that does not know the signing secret key will not be able to differentiate between these two cases.

There are a number of different options for token signing depending on the type notified for the API domain when it is added:

• account: This is the default, and this selects a token signed with the HS256 algorithm. This performs HMAC signing using the account secret key. The 512-bit symmetric secret may be exported using the approov CLI. If there are multiple API domains using the account type then they are all signed using this key.
• keyset: If keyset keys have been added then an API domain may be assigned to use one of them for token signing. Each key in the keyset is associated with a particular signing algorithm, providing support for asymmetric key pairs such as RSA and ECDSA.
• restricted: Some specific domains are considered to be restricted and are managed directly by Approov (such as the demonstration Shapes domain). If these API domains are added to the account then they are automatically allocated the restricted type. Approov tokens for them are signed or encrypted using a different key that is not accessible.

info

Be aware of the performance impact when you are selecting your algorithm. Token signing is performed by the Approov cloud service and it impacts the time required to get a token. Token verification is performed by the backend that handles API requests. The precise performance for different algorithms will be specific to the implementation you use and the hardware on which it is running, however, you can use the table below as a rough guide for Approov tokens (using an HS256 base-case with a signing time of x):

Algorithm	Signing	Verifying
HS256	x	2x
ES256	5x	15x
RS256/PS256	250x	10x

JWE Token Encryption

Note that Approov can also support another type of JWT, encrypted JWE tokens. One use case for these is if you wish to provide extended information within the anno and do not want to reveal the contents to any party that is able to read the tokens. JWE tokens use compact serialization which has 5 parts separated by ., where the first part is unencrypted and holds the encoded information about the algorithms used to encrypt the Content Encryption Key (CEK) and the payload. The Approov service uses A256GCMKW (alg claim) for encrypting the CEK and A256GCM (enc claim) for content encryption.

An API domain will use JWEs if the -jwe option is used when adding the domain. A JWE will also be used if a keyset key is used that is associated with the A256GCMKW algorithm.

Checking Token Validity

A checking option is provided that allows any Approov token to be checked. This is useful for debug purposes during your integration with Approov. Simply use:

approov token -check eyJhbGciOiJIUzI1Ni…

Which will output something like the following:

failed: expired alg:HS256
payload: {
  "arc": "CHDCG4GHWJ",
  "did": "h4gubfCFzJu81j/U2BJsdg==",
  "exp": 1669924065,
  "ip": "1.2.3.4"
}
expiry: 2022-12-01 19:47:45 UTC
device-properties: root-risk

The Approov token content is decoded, and information is provided about whether the token is passed or failed. For a JWS it also shows if the token has expired or not. Remember that expiry and signature validity are independent. The validity of a token (i.e. whether it is signed with the account secret key) depends on whether the request came from a valid app instance and also the security policy in place in the account. The expiry is purely related to how long ago the token was issued. Tokens normally only have a 5 minute lifetime, and the human readable form of the expiry is also shown.

The signing algorithm of the token (alg) is also shown, as well as any key ID (kid) in the token. The content of the token payload will depend on other Approov features that are being used.

If Attestation Response Codes are enabled for the account then this command will also provide a list of the device properties associated with the device to which the Approov token was issued.

tip

Note that the token check is also able to process encrypted JWE tokens. It shows if they are valid and can decode their content, even if they are invalid.

Reporting Token Misuse

The Token Information endpoint provides an optional facility to report the misuse of particular tokens. This endpoint can be used in conjunction with Approov support to allow automatic reporting of tokens that appear to be being misused in some way. This may be because you have reason to believe that a valid Approov token is being issued when it should not have been. Alternatively, if you believe that the Approov token has been somehow extracted from a running app and is being used to make API calls outside of the official app then these should be reported.

You should include a short message (256 characters or less) describing the issue in the Report-Message header for the request, for example:

curl -X PUT -H "Authorization: Bearer xxx..." -H "Approov-Token: eyJh..." -H "Report-Message: Expected a token fail on this device, contact ops@your.domain" https://<account-domain>/token-info/

Token reports are automatically forwarded to Approov support and they will be notified at the end of day in which the report is made. Unless you are already in dialogue with Approov support about this issue, we suggest you include email contact information in your report message. Approov support will analyze the information provided, and may gather more information from the specific device reported, and will respond with some additional diagnosis of the issue.

info

Token reports are rate limited, typically restricted to one per minute. If you exceed the rate limit then the API will return Ok but the report will not be forwarded to Approov support. Note also that subsequent token reports are ignored if they are issued on the same day and about the same device ID.

Loggable Tokens

It is generally not recommended to log Approov tokens within an app. This is because it might be possible for an attacker to turn logging on in a production app and use this as a mechanism to steal valid Approov tokens that have been received. Furthermore, the raw Approov tokens are also very opaque since they are just base64url encoded JWT strings and therefore not very useful for debugging.

Loggable tokens are output in the logging generated by the Mobile App Quickstarts. They provide a decoded string form of the Approov token, and are therefore much more useful for debug purposes. The returned string holds a JSON object containing the payload contents with an additional sip claim, as demonstrated by the following example:

{
  "anno": [
    "app-not-registered"
  ],
  "did": "h4gubfCFzJu81j/U2BJsdg==",
  "exp": 1558626228,
  "ip": "1.2.3.4",
  "pay": "6ZIvH1YelZyc2hx1iRRqD3dWNcFgjVtCon+7921XDjg=",
  "sip": "HggK-u"
}

Note that if no valid token was returned from the Approov token fetch request, or the returned token was a JWE, then a marshaled JSON string with the status is provided, e.g.:

JWS

{
  "status": "POOR_NETWORK"
}

JWE

{
  "status": "JWE"
}

As mentioned, a loggable token includes a special sip claim. This contains the first few characters of the signature of the token. Six characters are provided in base64, giving 36 bits out of the 256 bits provided in the complete signature. Thus it is not sufficient to create a validly signed token, but, if the signing key is known, it is sufficient to check, with a very high degree of accuracy, whether an Approov token is valid. Note that app itself never knows the symmetric secret used for signing tokens. Its possible to check a loggable token in the same way as a JWT as follows:

approov token -check '{"anno":["app-not-registered"...'

tip

Note that the loggable token must be enclosed in single quotes so that it is treated properly as a single command line parameter.

A statement is provided about whether the token was valid or not. It does this by reproducing the complete Approov token on the cloud service with the correct signature and then checking this against the prefix part of the signature that it knows from the sip.

warning

The sip claim cannot be used to determined token validity if the token was signed with a the probabilistic signature scheme. Probabilistic schemes include keyset key that use one of the following algorithms: PS256, PS384, PS512, ES256, ES384 or ES512. For these algorithms the loggable token will always be interpreted as a fail.

IP Tracking Policy

The IP tracking policy determines how Internet Protocol addresses are dealt with in your Approov account. When your account is setup the policy will be token. This means that the IP address of the device requesting an Approov token will be included in the token itself in the ip claim. However, in accordance with Approov's privacy notice, no record will be kept of the IP address in Approov's internal logs or records. This is because IP addresses can be considered to be Personally Identifiable Information (PII) and the Approov service does not collect this by default for an account holder's end customers. IP addresses are only stored by Approov services after transformation through a one-way hash function from which the original IP address cannot be recovered.

If desired the IP tracking policy can be changed to none so that the IP address claim is not even included in the issued Approov token.

approov policy -setIPTracking none

An admin role and confirmation is required to make an IP tracking policy change:

WARNING: updating the IP tracking policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
IP tracking policy was set successfully

A policy of full is also available whereby permission is given for Approov services to record unhashed IP addresses. This allows more sophisticated correlation analysis between IP addresses and device characteristics, carried out in conjunction with Approov support. Note, however, that if this option is used then the Approov service is collecting PII on your behalf and this may have GDPR implications.

The current IP tracking policy can always be retrieved as follows:

approov policy -getIPTracking