Skip to main content

User Management

It is possible to provide access to your Approov account (via the approov CLI) to other members of your team.

Best Practice​

When a new account is created the account holder is issued with dev and admin roles. One the capabilities of the admin role is the ability to add new users, with specific roles.

In a larger organization where multiple personnel need to interact with the Approov service, we expect that there will be some internal control of the access to Approov. We recommend that only a single individual, or small restricted group, should have access to the admin role. We suggest that dev roles are created for each of the individuals that are involved in the development of the apps that use the Approov service. These tokens allow access to all of the facilities required for app development, without more dangerous privileges that might impact apps that are live in production. The dev user roles can be issued to named individuals, preferably for a timescale that represents their likely involvement. Access can be revoked by the administrator at any time.

note

For larger and more complex teams or projects we recommend having multiple Approov accounts to provide enhanced insulation between development and production operations. If this is a requirement then please contact Approov support.

User Roles​

There are five different types of role may be used with the approov command line tool. These are dev, admin, delegate, pentest and automation.

Admin Role​

An admin role has additional privileges that are not available for the dev role as follows:

  • Removing app registrations that do not have an expiry date. Typically, this type of registration should be reserved for apps in production and so the removal of such registrations is protected.
  • Removing multiple app registrations in single command invocation using the -removeMatching option.
  • Modifying the security policy applied to the whole account. If this is changed then it could cause invalid Approov tokens to be sent to a range of different users that might cause a partial outage event.
  • Removing or modifying the set of API domains and pins for the account. If these are changed incorrectly then connection may be denied in production apps via an incorrect pin, or if an active API domain is accidentally removed then it will no longer receive valid tokens. All these actions could result in an outage event. Note that new API domains can be added with a dev role as this does not carry a risk of outage.
  • The creation, revocation and listing of user roles as discussed in this section.
  • Creating long lived Approov tokens for server-to-server communication or testing.
  • The extraction and update of the account secret key. This secret must be considered to be extremely sensitive since its possession allows arbitrary valid Approov tokens to be generated.
  • Removing Android app signing certificates.
  • Adding or removing Apple credentials for DeviceCheck usage.
  • Removing or importing keys in the keyset.
  • Exporting the JWKS for the keyset.

Delegate Role​

The delegate role has a more limited set of rights, and it will only ever be required in special circumstances. It is used when a 3rd party (who also has their own Approov account) is responsible for developing and registering the app that will be used to access endpoints controlled by this account. The privileges of the role are as follows:

  • Being the destination account for registration cloning using the registration command with the -cloneTo, -cloneToAccounts or -cloneToAllDelegateAccounts options.
  • Obtaining the SDK config using the approov sdk -getConfigString or approov sdk -getConfig commands.
  • Managing the app signing certificates with the approov appsigncert commands.
  • Managing any DeviceCheck configuration with the approov devicecheck commands.
  • Managing any AppAttest configuration with the approov appattest commands.
  • Managing any Play Integrity configuration with the approov playintegrity commands.
  • Checking the validity of tokens, and generating example ones, with approov token commands.
  • Viewing metrics for the account, either with a link in the onboarding email, or via approov metrics.

Note that the delegate role provides no rights to get the account secret key, or keyset keys, associated with the account.

Pentest Role​

The pentest role has a very limited set of rights. It is designed to allow an independent pentester of the app to modify the security policy applied to a device. This, for example, allows pinning to be disabled or an Annotation Policy to be set showing the reason for a rejection on a device. The privileges of the role are as follows:

  • Adding and removing custom devices. Note that only the devices added using a pentest role can be seen or removed.
  • Obtain the current security policy using approov policy -get.
  • Generate an example Approov token witrh the approov token -genExample command, for testing the backend API.

Automation Role​

The automation role has a very limited set of rights. It is intended to support automated scripted use of the approov CLI, especially for Continuous Integration (CI) build systems (see Automated Approov CLI Usage.

  • Downloading the SDK itself using the approov sdk -getLibrary command.
  • Obtaining the SDK config using the approov sdk -getConfigString or approov sdk -getConfig commands.
  • Creating new app registrations with approov registration -add.
  • Getting the current set of APIs and their pins with approov apis -getAll, and associated api and pin commands that only read the API and pinning state. This also includes approov api -check.

Note if there are any other operations you would like to perform from your build and other automation scripts using an automation role, then please contact Approov support.

Adding New User Roles​

Additional user roles may only be issued if you have access to an admin role. Here is an example of issuing Approov access to a new user with dev role privileges:

approov users -add bob@your.domain

This will require confirmation:

WARNING: you are adding dev role access to account your-account for bob@your.domain (bob)
ATTENTION: If you wish to continue then please type YES and return: YES
onboarding email has been sent to bob@your.domain

The -add option has a parameter of the user email. By default the new user role will have the same duration as the admin role used to create it. Moreover the new user role will be password protected (unless overridden with the -noPassword option). The user will receive an Approov Onboarding email with instructions of how to initialize access and they will be invited to set their password.

By default a dev user role will be created. This has limited privileges as discussed in the previous section. A new admin role may be created as follows, in this case with a shortened validity period of one week.

approov users -add boss@your.domain -admin -expireAfter 7d

This will require confirmation:

WARNING: you are adding admin role access to account your-account for boss@your.domain (boss)
ATTENTION: If you wish to continue then please type YES and return: YES
onboarding email has been sent to boss@your.domain

The -expireAfter parameter will normally be specified in terms of the number of days that access will be available for, but years (y) or hours (h) may also be used. Note that it is not possible to generate a user role that has an expiry time after that of the admin role used to create it.

A user name can also be associated with the role. By default this is derived from the part of the email address before the @. You can override this using the -userName option. Quotes must be used around the parameter if you wish to use spaces in the user name.

A new delegate user role may be created as follows:

approov users -add appdev@theirdomain.com -delegate

The delegate role can be provided to an independent app developer, who will then be able to use it to clone registrations from their own Approov account.

A new pentest user role may be created as follows:

approov users -add pentester@theirdomain.com -pentest

The pentest role can be provided to an independent pentester, which will enable them to control security policies for specific devices only, and to generate example Approov tokens for testing.

info

Note that there is currently a maximum limit of 25 user roles that may be live for any individual Approov account. If this limit is reached then old unused user roles should be revoked to allow the creation of new ones. Please contact Approov support if you need this limit to be increased. See Enabled Features and Limits for how to view the limit configured in your account.

Access Expiry Reminders​

Approov will send access expiry reminder emails to the holder of the user role. These are sent soon after midnight UTC daily for the few days prior to the expiry to remind the user that their access is about to expire. No further messages are sent if access is revoked or reaches its expiration.

Note that you will also receive expiration reminders about your primary user roles provided when you first initialized access to your Approov account. If you have a paid plan then you should receive a new onboarding email from Approov shortly after the reminder emails are issued.

Listing User Roles​

The available user roles can be listed as follows:

approov users -list

This command output provides the information about the active user roles with a unique ID for each:

3 user roles:
  admin-5794 you@your.domain, A N Other, expires 2029-05-08 15:01:05
  dev-0639   you@your.domain, A N Other, expires 2029-05-08 15:01:05
  dev-1234   bob@your.domain, bob, expires 2029-05-08 15:01:05, password protected

The first part of the ID is the role, which may be dev, admin or delegate. Other information includes the email addresses, user name, expiry date and if password protection is enabled.

Revoking User Access​

In some cases it is desirable to be able to revoke the use of a specific user role before its expiry time. This may be necessary if there is a concern that the access has been compromised or the individual that was provided access has left the project. A user role can be revoked as follows:

approov users -revoke dev-1234

This will require confirmation:

WARNING: you are revoking dev-1234 for bob@your.domain, bob, expires 2029-05-08 15:01:05
ATTENTION: If you wish to continue then please type YES and return: YES
user access dev-1234 revoked

The user role ID provided as the parameter can be obtained using the -list option. Revocation can take up to 30s. After revocation completes, attempts to use the role will result in an authorization error, e.g.

approov registration -list

Will produce an output such as:

ERROR: access is revoked
error: Forbidden, while getting management token status
info

Note that it is not possible to revoke the user roles issued by Approov when you first signed up. If you feel that your access may have been compromised, then please contact Approov support who are able to revoke these roles and then provide new ones.

Resending Onboarding Emails​

It is possible to send another onboarding email to an existing user. This is may be desirable if the user is has lost access to Approov for whatever reason, or they wish to access Approov from a different machine and their original onboarding email has expired. You must select an email address that is associated with one or more roles, and use the following command:

approov users -sendOnboardingTo bob@your.domain

An onboarding email is sent to the user which will give them 24 hours to install access to Approov on to the machine(s) of their choosing.