Management
Temporary Registrations
By default an app registration is permanent. This also means that an admin role is required to remove it. Removal needs to be restricted since an accidental removal will stop apps in production from receiving valid tokens, which may effectively bring an app service down. Note that in such a circumstance the Approov failover system will not be enabled, since this is not an Approov cloud system failure but explicit user action.
A temporary registration is performed just like a permanent registration, but with the addition of the -expireAfter option.
approov registration -add your-app.ipa -expireAfter 3d
This creates a registration that is active for 3 days. The expiry time is given in local time in the output:
registering app YourCoolApp
P6nTmI3fhftxUr740ZnUMGKuAyTYjxP5dxKzJGd9yOk=my.app.com-2.0[3]-2974 TeamID:953D8M53YN SDK:iOS(2.5.0)
registration successful, expires 2019-06-01 16:27:01
Note that if the registration already exists and is permanent or has a longer lived temporary expiration time, then that later time is retained.
The -expireAfter parameter takes a duration which may be specified in y (years), d (days), h (hours), m (minutes) or s (seconds). Multiple time units may be used as long as they are specified in this order, e.g. 3d12h to register for three and a half days.
Updating Registration Expiry
If you have made a Temporary Registration you may subsequently want to make that registration permanent, or at least to extend the time of the registration expiry. You can do this as follows, using the registration signature provided from the registration -list option:
approov registration -updateExpiry P6nTmI3fhftxUr740ZnUMGKuAyTYjxP5dxKzJGd9yOk=my.app.com-2.0[3]-2974
This method does not require you to have access to the original app package. Note that the -expireAfter option can also be used to extend an existing temporary registration.
Unversioned Registrations
By default an app registration is for a specific version of the app. This means that a new app registration is required each time a new app is released. This gives the flexibility of fine grain control of your registrations, allowing you to remove individual registrations associated with specific versions (perhaps if you no longer wish to issue valid Approov tokens to an older version of your app).
However, it is possible to create an app registration that is not specific to a version. This will match any app issued with the same signing authority and with the same package name. If you use this style, then only one registration is required and any updated app release will also match. Remember that you lose the flexibility of revoking individual versions in the future.
An unversioned registration is performed with the addition of the -unversioned option. Note that this is not supported for Android .apk packages, only for .aab.
approov registration -add your-app.ipa -unversioned
This creates an unversioned registration, denoted by the * in place of the version number.
Listing Registrations
All of the registrations that are active for the account can be listed as follows:
approov registration -list
This provides the registrations such as:
3 app registrations:
Ac15BRFWqxn79dGsjOdVJXVqBQQ64ZWTAuKdrzRC9hc=com.criticalblue.demo-2.0[3]-2974 SDK:Android(2.5.0) registered:2019-05-15 18:03:17
P6nTmI3fhftxUr740ZnUMGKuAyTYjxP5dxKzJGd9yOk=approov.io.client.swift.shapes-client-1.0[1]-4803 SDK:iOS(2.5.0) registered:2019-05-15 18:03:31
Ac15BRFWqxn79dGsjOdVJXVqBQQ64ZWTAuKdrzRC9hc=com.criticalblue.demo-2.0[3]-2974 SDK:Android(2.5.0) registered:2019-05-29 14:49:36 expiry:2019-06-01 14:49:36
Each registration entry provides its overall signature as a single text block at the start of each line. This is the signature that must be copied in order to remove a registration (see next section). It contains a signature hash of aspects of the application, the application package name, application version information, and the ID of the Approov SDK that is integrated within it.
More information is also provided about the type and version number of the Approov SDK used. The registration time of the app is also provided (in local time). This is updated if a new registration of an app is made that happens to have the same signature. Finally, the expiry time of the registration is shown if it was registered with -expireAfter. Once a registration expires it is automatically removed from the list.
Note that if you are looking for a particular registration you are able to find it by simply piping the output through grep, for instance on Linux/MacOS:
approov registration -list | grep iOS
Using this method it is possible to find registrations for specific platforms, SDK versions, app names and versions.
Removing Registrations
Any individual registration can be removed using its overall signature provided from the registration -list option. For instance, to delete a temporary app registration:
approov registration -remove Ac15BRFWqxn79dGsjOdVJXVqBQQ64ZWTAuKdrzRC9hc=com.criticalblue.demo-2.0[3]-2974
If you are using the zsh shell you will need to enclose the -remove parameter with single quotes ('). This is because zsh interprets square brackets as a globbing specifier.
You will be asked for confirmation if the app has a permanent registration, but not for a temporary registration. Note the removal process assigns an expiry time for the registration two minutes into the future, at which point it is actually removed. When removed no further valid Approov tokens will be issued for the app. Note that running apps may already hold a cached Approov token so it may take up to 5 further minutes before all valid token usage by those apps stops.
Permanent app registrations are removed in the same way but users are also asked to provide confirmation before the deletion occurs. An admin role can be used to remove any registration. Registrations that were added with an admin role can only be removed with an admin role (it doesn't need to be the same user). A user's dev role can be used to remove registrations that they added using a dev role. In other words, a developer can remove their own permanent registrations or any temporary registration and an administrator can remove any registration, e.g:
approov registration -remove P6nTmI3fhftxUr740ZnUMGKuAyTYjxP5dxKzJGd9yOk=approov.io.client.swift.shapes-client-1.0[1]-4803
Confirmation will be required however:
WARNING: removing app registration will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
app registration P6nTmI3fhftxUr740ZnUMGKuAyTYjxP5dxKzJGd9yOk=approov.io.client.swift.shapes-client-1.0[1]-4803 has been removed
You can provide just the first part of a signature if it is unique amongst all of the registrations. If you are using the zsh shell then this also means you don't need to use single quotes if you don't include the part of the signature with square brackets.
Removing Multiple Registrations
A facility is provided to remove multiple registrations using a single command. This is useful for maintaining the hygiene of your app registrations. You should actively remove registrations that are no longer in use, either because they are registrations for old testing apps (that have been accidentally permanently registered), or for previously released production apps that no end users are still using.
The command is invoked as follows, for the package com.criticalblue.demo targeted registrations older than 30 days ago:
approov registration -removeMatching com.criticalblue.demo,30d
A list of matching registrations is provided. You should review this carefully before providing confirmation and allowing the operation to complete.
2 matched registrations to be removed:
Ac15BRFWqxn79dGsjOdVJXVqBQQ64ZWTAuKdrzRC9hc=com.criticalblue.demo-2.0[3]-2974 registered:2019-05-05 16:01:46
A4rcdXpfEOg0wse4snbAURnjRZidPvY63EULzUrZeFE=com.criticalblue.demo-3.0[4]-2974 registered:2019-05-15 18:02:08
WARNING: removing app registrations will have an immediate impact on your apps in production
ATTENTION: If you wish to continue then please type YES and return: YES
removing Ac15BRFWqxn79dGsjOdVJXVqBQQ64ZWTAuKdrzRC9hc=com.criticalblue.demo-2.0[3]-2974
removing A4rcdXpfEOg0wse4snbAURnjRZidPvY63EULzUrZeFE=com.criticalblue.demo-3.0[4]-2974
This needs an administration role as this is a risky operation that could cause current production app registrations to be removed if care is not taken. The parameters provide the exact package name of apps to be matched and the minimum age of last registration of the app.
Annotating a Registration
A facility is provided to add an arbitrary string instead of the version name for a particular registration. This allows a particular registration to be annotated to show that it is for some specific purpose (perhaps a special testing version, for instance) and this allows it to be easily located in the list of all app registrations. We advise you not to use this facility on apps which are to be retained for production purposes, so that the real version number of app registration is available.
The annotation is added as follows:
approov registration -add your-app.apk -versionName "special"
This particular registration can then be easily found again as follows:
approov registration -list | grep special