Lifecycle and Claim Configuration
Token Lifespan
The normal lifetime for an Approov token is 5 minutes, plus a grace period, from the point of issue by the Approov cloud service. The grace period of a few seconds is added to allow a valid token to be propagated and checked within a backend API system. If a particular device is identified as being risky in some way (such as it being rooted or jailbroken), then, independently of the overall security rejection policy that is set, it will receive a shorter lived 2 minute token instead of a 5 minute one. This forces the device to make more frequent checks as it receives tokens.
The app itself should never cache Approov tokens that it gets from the Approov as the underlying SDK does this in a secure way. Each Approov call does some basic app environment checking and, if issues are discovered, performs a complete attestation check to fetch a new token. Thus an Approov token lifetime should be considered to be up to 5 minutes, since any cached token may be discarded at any point.
Token Claims
Depending on the source of an Approov token (the main Approov service or the Failover) the claims it contains may vary. However, the expiry (exp) claim is always present. The details of the claims are provided in the table below:
| Key | Name | Type | Description |
anno | Annotation | Embedded JSON | This is an embedded JSON array of strings showing the list of flags that are set and are in the annotation set for the security policy that is selected. This allows additional information to be collected about the state of a particular device without necessarily causing an attestation failure. Note that if there are no possible annotations then this claim is not present at all. This claim is not included by tokens from the failover. |
arc | Attestation Response Code | String | This is an optional claim that encodes information about a subset of the device property flags and also whether the attestation was a pass or fail. The claim is encoded in base32 and is typically 10 characters long (although it may be longer in some circumstances). See Attestation Response Code. This claim is not included by tokens from the failover. |
aud | Audience | String | An optional claim that is added if the audience inclusion option is enabled. This provides the domain for which the token was issued. It can be used as an additional layer of backend verification to ensure that tokens intended for one domain cannot be used to access a different one. |
device_state | DeviceCheck Device State | Embedded JSON | This is provided for tokens issued to iOS devices if the DeviceCheck option is enabled. It provides embedded JSON providing the status of the two bits held per device, and the last month when those bits were updated. This can be used to direct some optional behaviour based upon that status. |
did | Device ID | String | This claim identifies the app installation for which the token was issued. This is a base64 encoded string representing a 128-bit identifier. This may change if the same app is uninstalled and then reinstalled on the same device. |
dmh | Device Measurement Hash | String | An optional claim to provide the device measurement hash if a measurement has been requested by the SDK on the domain for which the token is issued. This is a base64 encoded 256-bit SHA256 measurement value. Note that if measurement is being used, then JWE tokens will be used to keep this claim secret. |
ipk | Installation Public Key | String | An optional claim that is a base64 DER encoding of an ASN.1 represented installation public key. This key should always be an Elliptic Curve (EC) key using the P-256 curve. If this claim is present then it should be used as a signal that Installation Message Signing is being used. This is only present in Approov tokens issued to devices with SDKs that support installation message signing. It should be used as an indication to the backend verification that installation message signatures should be expected in requests. |
embed | Embedded Installation Attributes | Embedded JSON | An optional claim that may be included for all Approov tokens issued on a particular app installation if these have been previously set via an Application Installation Attributes token. This is a signed JWT provided by the backend that indicates some particular attributes should become associated with the installation. |
exp | Expiry | Number | The only mandatory claim for Approov tokens. It specifies the expiry time for the token as a Unix timestamp. |
iat | IssuedAt | Number | An optional claim that is added if the issued-at inclusion option is enabled. It provides the time at which the token was issued as a Unix timestamp. |
imh | Integrity Measurement Hash | String | An optional claim to provide the integrity measurement hash if a measurement has been requested by the SDK on the domain for which the token is issued. This is a base64 encoded 256-bit SHA256 measurement value. Note that if measurement is being used, then JWE tokens will be used to keep this claim secret. |
ip | IP Address | String | This holds the IP address of the device as seen by the Approov cloud service. It is provided in a human readable IP address format (in either IPv4 or IPv6 format). In practice this value can often change between the time a token is issued and the time it is sent to your backend, so you should never block if it differs, but you may include it as a signal that tokens have somehow been stolen and are being replayed. This claim is not included by tokens from the failover or if the IP Tracking Policy for the account has been set to |
iss | Issuer | String | An optional claim that is added if the issuer inclusion option is enabled. This provides the Approov account ID that was used to issue the token (suffixed with |
mpk | Measurement Proof Key | String | An optional claim to provide the measurement proof key if a measurement has been requested by the SDK on the domain for which the token is issued. This is a base64 encoded 128-bit proof key value. Note that if measurement is being used, then JWE tokens will be used to keep this claim secret. |
mskid | Account Message Signing Key ID | String | This is an optional claim that encodes the ID of a key being used for Account Message Signing. This is only present in Approov tokens for which account message signing is active. It should be used as a signal to the backend verification that account message signatures should be expected in requests. |
pay | Payload Hash | String | An optional claim that is added if the protected app passes a token binding argument to the setDataHashInToken method. The claim value is set to the base64 encoded SHA256 hash of the provided payload string. This is typically used to bind an Approov token to some other data used by your app to enhance security (like a user auth token). |
sub | Subject | String | An optional claim that is added if the subject inclusion option is enabled. This provides the subject of the token, which is the particular device and app to which it was issued. The claim is compromised of |
Obtaining Additional Token Information
An API is provided that allows additional information to be obtained for a previously issued Approov token. Note that for additional information to be available the Attestation Response Code feature must be enabled.
Information about how to access the API endpoint is provided as follows:
approov token -showTokenInfoCurl
Which will output the example curl command as follows:
curl -X PUT -H "Authorization: Bearer xxx..." -H "Approov-Token: <token>" https://<account-domain>/token-info/
add `-H "Report-Message: <message>" to report a particular token
The API key in the Authorization is account specific and should not change unless a specific support request is made to request its rotation. The API key only allows the decoding of tokens and obtaining additional token information and does not enable any other actions on the account. However, as with any account credential, steps should be taken to keep it secured and to prevent accidental disclosure or inclusion in source code repositories.
You should provide an issued Approov token to the API endpoint and this will generate output such as the following:
{
"did": "qZka0yfv+ExvOq3PRh6pGw==",
"status": "failed",
"claims": {
"arc": "B3Y5SLMO2K",
"did": "qZka0yfv+ExvOq3PRh6pGw==",
"exp": 1607528162,
"ip": "1.2.3.4"
},
"expiryTime": "2020-12-09 15:36:02 UTC"
"deviceProperties": [
"app-not-registered",
"rooted",
"root-risk",
"xposed"
]
}
The status indicates if the attestation was passed or failed. If the provided token was issued to a different account then the status is likely to be arc invalid (and if it does happen to be valid it will not report the correct decoding). The did property provides the Device ID. The full set of token claims are provided, even if the Approov token is an encrypted JWE. The expiryTime provides a readable form of the expiry time of the Approov token. Note that, the tokens you provide may have expired and this will not impact their status or the ability to decode them.
The deviceProperties lists the device property flags that have been determined from the device. If the status is failed then this will almost certainly pinpoint the reason(s).
Note that although the syntax is provided for curl for your convenience, any standard tool or mechanism can be used to perform the PUT request to the endpoint.
This API is for the use of your backend systems only. Never build calls to this API into your mobile app and, especially, never expose the Authorization key.
You should never use this endpoint to check the validity of the token. Always check validity by verifying the signature of the Approov token directly. This endpoint should only be used for informational purposes on a subset of received tokens; it may be subject to rate limiting and does not have the Cloud Server Redundancy features of the Approov token issuance service.
Long Lived Approov Tokens
It is possible to generate Approov tokens that have a long expiry time. Approov tokens issued via the Approov SDK only have an expiry time of 5 minutes or less. This facility allows tokens for an arbitrary duration to be created. It requires an admin role. To create one use:
approov token -genLongLived server-token,90d
Which will output the expiry date and the token itself:
token will expire at 2019-06-03 13:24:38
WARNING: Long lived token should never be integrated into public clients and their security must be carefully managed
eyJhbGciOiJIUzI…
This generates an Approov token that is valid for 90 days. The server-token parameter is included in the iss claim of the token. Change this to whatever name you would like. It can be used to identify particular long lived tokens, or even to revoke certain ones by backend API checking. In effect this claim could be used as a type of API key within the overall signed Approov token. The expiry time should be specified in days and cannot be less than 1 day.
Long lived tokens can be used to authorize communication to the protected backend API for server-to-server communication and test environments (such as Postman). This allows a particular API to be accessible both from mobile apps and also via other servers without having to create a different authorization mechanism. Generating a long lived token has no impact on the expiry time of tokens issued normally through the Approov SDK.
Long lived tokens must never be included in public clients, such as web pages or mobile apps. They should only be used in circumstances where the token can be protected in a server environment.
Long lived tokens cannot be generated for restricted domains, such as shapes.approov.io demo endpoint. Moreover, it is only possible to generate long lived JWS tokens signed with the account secret key. It is not possible to create tokens signed with a keyset key.
Audience Inclusion
The audience inclusion feature allows the aud claim to be populated in all Approov tokens issued for the account. This will be set to the domain name for which the Approov token was issued. This can be useful to ensure that tokens issued for one domain cannot be used to gain access to a different domain that shares the same signing secret key. This needs to be checked by the backend API integration.
The audience inclusion feature can be enabled as follows:
approov policy -setAudience on
An admin role and confirmation is required to make an audience policy change:
WARNING: updating the audience policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
The current audience policy can always be retrieved as follows:
approov policy -getAudience
Note that wildcard tokens are issued with an aud claim of *.
Issuer Inclusion
The issuer inclusion feature allows the iss claim to be populated in all Approov tokens issued for the account. This will be set to the name of the account suffixed with approov.io. This is useful as an additional verification if signing keys are being shared between multiple accounts. The backend API integration is able to verify that the token was issued for the expected account.
The issuer inclusion feature can be enabled as follows:
approov policy -setIssuer on
An admin role and confirmation is required to make an issuer policy change:
WARNING: updating the issuer policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
issuer policy was set successfully
The current issuer policy can always be retrieved as follows:
approov policy -getIssuer
IssuedAt Inclusion
The issued-at inclusion feature allows the iat claim to be populated in all Approov tokens issued for the account to show the timestamp of when it was issued. The feature can be enabled as follows:
approov policy -setIssuedAt on
An admin role and confirmation is required to make the policy change:
WARNING: updating the issuedat policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
issuedat policy was set successfully
The current issued-at policy can always be retrieved as follows:
approov policy -getIssuedAt
Subject Inclusion
The subject inclusion feature allows the sub claim to be populated in all Approov tokens issued for the account. This is set with the string approov| and then the device ID that the token was issued to. This is then followed by a | separator and then the app package identifier.
The feature can be enabled as follows:
approov policy -setSubject on
An admin role and confirmation is required to make the policy change:
WARNING: updating the subject policy will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
subject policy was set successfully
The current subject policy can always be retrieved as follows:
approov policy -getSubject