@amazon-devices/security-manager-lib

The Security Manager API provides functionality that allows your app to request run-time privileges. Run-time privileges are used to restrict access to privacy-sensitive resources provided by the system. Users must provide explicit consent before an app can access resources guarded by run-time privileges. Examples of such restricted resources include microphones and cameras.

Get started

Setup

Add the following library dependency to the dependencies section of your package.json file.

  "@amazon-devices/security-manager-lib: "~1.0.1767254401",

Usage

Request run-time privileges

Use the following method to request authorization to access resources such as the camera or microphone. For the full set of permissions available, see PERMISSIONS in PermissionsKepler.

`getPrivilegeState()` for calling package

There are two versions of the getPrivilegeState() method. The version that apps are expected to use is defined as follows:

static async getPrivilegeState(
    privilege: string
): Promise<SecurityManagerTypes.PrivilegeState>

This method allows an app to determine if it is allowed to use methods that are gated by a run-time privilege. This method is asynchronous and returns a object on which the can wait on by using an await or then() construct. On success, the payload of the Promise is the current state of the privilege which is one of the following:

SecurityManagerTypes.PrivilegeState.ALLOW - This indicates that the user has already consented to giving this app the requested privilege. There is no need to request the privilege from the user.
SecurityManagerTypes.PrivilegeState.DENY - This indicates that the user has either already been asked for privilege and denied it, or that consent has never been requested. Use the requestPrivilege() method to prompt the user for consent.

On error, the Promise is rejected with an error message.

`requestPrivilege()`

Apps use the requestPrivilege() method when they need access to a privilege. The OS responds by launching a Privilege Request Handler, which is a system component responsible for asking the user for consent and storing the result.

static async requestPrivilege(
    privilege: string
): Promise<SecurityManagerTypes.PrivilegeState>

On success, the payload of the Promise is the new state of the privilege which is one of the following:

SecurityManagerTypes.PrivilegeState.ALLOW - The user has consented to giving the privilege to the app. The app should continue to access the privileged resources it needs.
SecurityManagerTypes.PrivilegeState.DENY - The user rejected the privilege request. The app should degrade functionality gracefully. The app shouldn’t continuously prompt the user to allow access. This method should only be called again after the user has performed another action which indicates that they want the app to access a protected resource.

On error, the Promise is rejected with an error message.

Example usage

The following example demonstrates how to implement microphone access permissions in your app using the Security Manager. This code shows a complete flow for checking and requesting microphone privileges when a user attempts to access recording functionality, including proper error handling and navigation to appropriate screens based on the user’s permission choice. If permission is granted, the user is directed to the recording screen; if denied, they are shown an access denied screen.

  const handleRecordButtonPress = () => {
    // wrapping index through array above
    SecurityManager.getPrivilegeState('com.amazon.audio.privilege.microphone.access').then(
      function(state: PrivilegeState) {
        if (state == PrivilegeState.ALLOW) {
          navigation.navigate('RecordScreen');
        } else {
          SecurityManager.requestPrivilege('com.amazon.audio.privilege.microphone.access').then(
            function(state: PrivilegeState) {
              if (state == PrivilegeState.ALLOW) {
                navigation.navigate('RecordScreen');
              } else {
                navigation.navigate('MicrophoneAccessDeniedScreen');
              }
            },
            function(error: Object) { KPLOG().error("Failed to request privilege: {}", error["message"]); }
          )
        }
      },
      function(error: Object) { KPLOG().error("Failed to get privilege state: {}", error["message"]); }
    )
  };

Privilege request handlers and the privacy dashboard

The privilege request handler is the system component responsible for getting consent to access a privilege from the user and storing the result. The privacy dashboard is a centralized place in the settings app where users can view and change their privacy settings.

`getPrivilegeState()` for privilege request handlers

The version of the getPrivilegeState() method that privileged components use is defined as follows.

static async getPrivilegeState(
    packageId: string,
    privilege: string
): Promise<SecurityManagerTypes.PrivilegeState>

This differs from the other variant in that the package ID of the package of interest must be specified. This method is asynchronous and returns a object on which the app can wait by using an await or then() construct. On success, the payload of the Promise is the current state of the privilege which is one of the following:

SecurityManagerTypes.PrivilegeState.ALLOW - This indicates that the user has already consented to giving this app the requested privilege.
SecurityManagerTypes.PrivilegeState.DENY - This indicates that the user has either already been asked for privilege and denied it, or that consent has never been requested.

On error, the Promise is rejected with an error message.

Sample Usage

   SecurityManager.getPrivilegeState(
    'com.amazon.keplersampleapp',
    'com.amazon.audio.privilege.microphone.access'
    ).then(
      function(state: PrivilegeState) {
       // Privilege state:  state
      },
      function(error: Object) {
        // Failed to get privilege state: error["message"]
      }
    );

Access Control

This method requires the com.amazon.privilege.package.queryrun-time privilege due to the fact that it allows the caller to determine what apps a user has installed, which is a privacy concern. This privilege requires the calling app to have a platform signature. To prevent privilege fatigue and annoyance, Kepler only shows this modal dialog the first time an app requests a privilege. The user makes a choice using the dialog, and that setting is recorded. The user is free to change that choice at any time through the Settings app.

Privilege errors

If your app uses a service that you didn’t declare on your manifest, you will receive an error when starting your app. The following example log message means the app has not properly declared the WiFi service-dependency in the app manifest.

Apr 24 13:39:59.613429 firestick-c93bfe9ecdeea42f local0.err netsvc[985]: 1317 E securitymgr:[SecurityManager.cpp:124] Privilege 'com.amazon.wifi.privilege.read-wifi-credential' not granted

Request Run-time Privileges

Vega Target Navigator Provider

@amazon-devices/security-manager-lib

Get started

Setup

Usage

Request run-time privileges

`getPrivilegeState()` for calling package

`requestPrivilege()`

Example usage

Privilege request handlers and the privacy dashboard

`getPrivilegeState()` for privilege request handlers

Sample Usage

Access Control

Privilege errors

Modules

​Get started

​Setup

​Usage

​Request run-time privileges

​getPrivilegeState() for calling package

​requestPrivilege()

​Example usage

​Privilege request handlers and the privacy dashboard

​getPrivilegeState() for privilege request handlers

​Sample Usage

​Access Control

​Privilege errors

​Related topics

​Modules

Get started

Setup

Usage

Request run-time privileges

`getPrivilegeState()` for calling package

`requestPrivilege()`

Example usage

Privilege request handlers and the privacy dashboard

`getPrivilegeState()` for privilege request handlers

Sample Usage

Access Control

Privilege errors

Related topics

Modules