Custom JWTs
This feature provides a facility to fetch custom JWTs via the SDK, where most of the payload claims are defined by the app. This is provided for very specific circumstances where it is not possible to use the claim structure of Approov tokens.
One particular use case is for the creation of software statement JWTs for OAuth2 Dynamic Client Registration. Such a JWT needs particular claims that can be provided by the app regarding the properties of that app. This allows a particular app instance to prove that it is a true and valid instance of the particular app type, in order to register itself with an Authorization provider and obtain a per-app instance client secret. This client secret can then be stored securely in the app instance using the Secure Strings feature.
The payload claims that are required are provided to the custom JWT fetch request in the form of a marshaled JSON object. These claim values are included verbatim within the generated custom JWT, except with the following claims added (or usurping the same claim provided in the payload):
exp: The expiry time of the JWT. This is set to the same expiry time period as Approov tokens, which is normally 5 minutes but may be shorter for some risky devices.iat: The time that the JWT was issued.did: The base64 encoding of the device ID that requested the custom JWT.
A valid custom JWT is only provided if the app passes the attestation checks. The same choice of signing algorithms is provided for custom JWTs as for Approov token JWTs.
The information in the payload claims must be sent to the Approov servers for the Custom JWT to be signed. Note that the Approov servers only hold this data temporarily in memory 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 payload contents do not directly identify individual users, but only provide abstract identity information.
Enabling Custom JWTs
Custom JWTs are not enabled by default, and any attempt to fetch them from the SDK will result in a DISABLED / disabled status error. Enable the feature using:
approov customjwt -setEnabled
You will need an admin role and to provide confirmation to do this.
WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
custom JWT enablement updated
By default custom JWTs will be signed using the HS256 algorithm and the standard account secret key.
You can obtain the status of the custom JWT feature at any point using:
approov customjwt -get
Finally, the custom JWT can be disabled if you have an admin role:
approov customjwt -setDisabled
You will need an admin role and to provide confirmation to do this:
WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
custom JWT enablement updated
Fetching Custom JWTs
The Mobile App Quickstarts provide a method to fetch a custom JWT, given a parameter of a payload to be included within it.
If the app fails its integrity check then a REJECTED / rejected status is provided and the custom JWT is not available (this differs from the behavior of Approov tokens, which would provide an incorrectly signed JWT in this case). Your app implementation will need to handle this gracefully and provide feedback to the user. This may include a retry option, but most rejection causes will likely persist. You should consider the use of Attestation Response Code or Rejection Reasons in order to provide feedback. An Attestation Response Code will provide an alphanumeric code that can only be decoded if it is given to your app support team (and they are setup to decode it). Rejection Reasons will provide a direct indication of the cause of the problem.
The fetch might also fail due to network connectivity issues, in which case you should provide a user initiated retry option.
Custom JWTs are only supported in version 3.0.0 and later SDKs.
Custom JWT Key Set Usage
When the feature is first enabled the HS256 signing algorithm is used for the custom JWT using the account secret. However, it is possible to use Key Sets to select different keys and signing algorithms. This also allows the use of an imported private key if desired.
Assuming the addition of a new key called your-key, you can select this as follows:
approov customjwt -keySetKID your-key
An admin role and confirmation is required:
WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
custom JWT keyset KID changed
The kid claim in the JWT header will be populated with the selected key identifier, and the appropriate signing algorithm and secret is used for subsequently generated custom JWTs.
It is possible to revert back to HS256 and the account secret with the following:
approov customjwt -clearKeySetKID
Again, an admin role and confirmation is required.
WARNING: this will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
custom JWT keyset KID changed