Version 2021

Integrating S2 NetBox® with MicroStrategy Identity

To provide access to locations that are secured with S2 NetBox, integrate your NetBox system with MicroStrategy Identity.

You integrate S2 NetBox through a web service that communicates to the S2 NetBox physical access control system server using Apache Tomcat. The web service that performs this role is called the adapter.

You can also secure the adapter by completing an optional step that ensures that only MicroStrategy Identity Server communicates with the adapter. This process is included in the steps below.

When NetBox successfully connects to MicroStrategy Identity, each physical access point secured by NetBox is loaded into the Identity Server as a digital key. To control which users have permission to unlock each physical access point, you must manage user permissions in S2 NetBox. You can customize how keys are displayed to users. For examples and steps to customize keys, see Managing Physical Access Keys.

After the Identity adapter for S2 is installed, you can perform the following procedures:

  • To create the S2 NetBox adapter, the server that hosts the adapter must meet the following requirements:
    • Red Hat® Linux® (64-bit) operating system with 4GB RAM and 500GB disk space for database
    • MySQL Database 5.6.x
    • Java JRE 1.7.x
    • Apache Tomcat 8.x
    • S2 NetBox 4.9.00 with remote connection enabled
  • Each door that is secured by S2 NetBox must have a portal defined in NetBox, each with an event that has an action that is enabled to open the door each time the event is triggered.
  • You must create a MySQL 5.5 database space with an ANSI DSN pointing to it. The database is used by the adapter to log adapter activity and errors.
  • Gather the following information:
    • The Tomcat directory that will host the S2 NetBox adapter
    • The IP address or name of the machine that will host the S2 NetBox adapter
    • The field in the S2 user repository used to look up S2 NetBox users. This may be person ID, employee ID, email address, or similar. The field must hold a value that is unique for each person.
    • The port number used to access S2 NetBox server
    • A user name and password for an account that has associated administrator access to S2 NetBox. This account is used to create parallel connections between the S2 NetBox server and the S2 adapter, to improve performance.
    • The user, password, and database name for the S2 NetBox database
    • The IP address, user, and password information for the MySQL database space that you created for the adapter log
  • If users were manually added to the Identity Network or by importing a comma-separated values (CSV) file, note the following requirements:
    • You must have a MicroStrategy Cloud implementation.
    • The field in the S2 NetBox system that is used to look up identified S2 NetBox users must correspond to a field in the user's Identity profile. For steps to add users to your network and provide information for Identity user profile fields, see Adding Users Manually or Adding Users from a CSV File.

To Enable Physical Access with MicroStrategy Identity to Locations Secured by S2 NetBox

  1. Log into MicroStrategy Identity Manager:
  2. Click Physical Gateways.
  3. Under Building Access, click the S2 Security icon . The Configure S2 Physical Access System page opens.
  4. Click Download Identity Adapter for S2. The UsherAdapterforS2.zip file is downloaded.
  5. Unzip the .zip file. The file contains the shell file for creating the adapter.
  6. Use a MySQL client to connect to the log database space you prepared, as described in the Integrating S2 NetBox® with MicroStrategy Identity, and execute the SQL script that is included below. The script creates the log database.
    /**
    * S2 log table schema
    */
    CREATE TABLE 'log' (
    'id' int(10) unsigned NOT NULL AUTO_INCREMENT,
    'webserver_addr' varchar(128) DEFAULT NULL,
    'remote_addr' varchar(128) DEFAULT NULL,
    'level' varchar(8) DEFAULT NULL,
    'content' mediumtext,
    'class' varchar(128) DEFAULT NULL,
    'uri' varchar(256) DEFAULT NULL,
    'thread_id' varchar(64) DEFAULT NULL,
    'date_utc' datetime DEFAULT NULL,
    PRIMARY KEY ('id')
    ) ENGINE=InnoDB DEFAULT CHARSET=utf8;
  7. From the WEB-INF folder in Tomcat, use a text editor to open the log4j.properties file. Locate the lines in the file that are duplicated below, then customize the items in italics to enable the adapter to connect to the log database.
    log4j.appender.mysql.URL=jdbc:mysql://IPAddress:portNumber/S2?
    useUnicode=true&characterEncoding=UTF-8
    log4j.appender.mysql.user=username
    log4j.appender.mysql.password=password
    Where:
    • IPAddress is the IP address of the machine hosting the log database
    • portNumber is the port number of the machine hosting the log database (the default is 3306)
    • username is the user name for the log database
    • password is the password for the log database
  8. To install the adapter, on the machine hosting the S2 NetBox adapter, open the wizard folder and run the setup.sh shell script.
  9. Review the information on the Welcome screen, then click Next.
  10. Review the license. To continue, click Agree, then click Next.
  11. In the Tomcat location field, type the folder within the Tomcat directory where the adapter will be installed (/MSTR by default).
  12. Click Next. The S2 Adapter configuration page opens.
  13. To create a server node, do the following:
    1. In the Tomcat directory field, type the path where the adapter will be installed, as described in the Integrating S2 NetBox® with MicroStrategy Identity.
    2. In the S2 Web Server IP field, type the IP address of the machine hosting the S2 adapter, as described in the Integrating S2 NetBox® with MicroStrategy Identity.
    3. In the Field for IDM field, type the field to use to look up identified NetBox users, as described in the Integrating S2 NetBox® with MicroStrategy Identity. This field can be email, person ID (default), or similar.
    4. In the Web Server Port field, type the port number used to access the S2 NetBox server (80 by default).
    5. In the User Name and Password fields, type a user account name and password for a user that has administrator access to the S2 NetBox server, as described in the Integrating S2 NetBox® with MicroStrategy Identity.
    6. In the Event Action field, type ACTIVATE.
    7. In the Database Password field, type the password for the S2 NetBox database (report by default).

      In the wizard, you can change the database password for connecting to the S2 NetBox database, but you cannot change the user and database name. You can do this after finishing the wizard by editing the s2config.json configuration file.

  14. To add more server nodes, repeat the steps above for each server node that you want to add.
  15. Click Next. The Installation Summary page opens.
  16. To begin the installation, click Start. The adapter is installed.
  17. Click Finish to close the wizard.
    The adapter settings are saved in the s2config.json configuration file, in the /MSTR folder in the Tomcat directory.
  18. In the /MSTR folder in the Tomcat directory, use a text editor to open the s2config.json configuration file. Locate the db_params section, and change the values for the db_user and db_name for connecting to the S2 NetBox database.
  19. Return to MicroStrategy Identity Manager, then click Next.
  20. Enter the following information:
    • Configuration Name (required): A descriptive name for this connection to the S2 NetBox system. This is the name that you see in MicroStrategy Identity Manager.
    • Adapter Server URL (required): URL of the S2 NetBox adapter server, such as http://IPaddress:port, http://hostname:port, or https://hostname:port.
    • Adapter Service Path (required): Path of the S2 NetBox adapter.
    • User ID Mapping (required): The field to use to look up identified S2 NetBox users.
      If the users in your network are added manually or by importing a comma-separated values (CSV) file, type the Identity profile field that contains information used to look up identified S2 NetBox users, as described in Integrating S2 NetBox® with MicroStrategy Identity. Select from the following fields:
      • If S2 NetBox users are identified by their first name, type first_name.
      • If S2 NetBox users are identified by their last name, type last_name.
      • If S2 NetBox users are identified by their email address, type email.
      • If S2 NetBox users are identified by their title, type title.
      • If S2 NetBox users are identified by an alternate value that you provided when you added users to your Identity Network, type user_name.
    • SSL Bypass: By default, communication is encrypted with secure sockets layer (SSL). To use plain, unencrypted communication between the adapter and Identity, type true. MicroStrategy recommends that you leave this as the default; do not bypass SSL unless you are testing.
  21. Click Refresh. When Identity successfully connects to the adapter, a green check mark is displayed.
  22. Click Next. The keys in your S2 NetBox system are loaded into Identity.
  23. To secure the adapter by verifying that the adapter communicates with the MicroStrategy Identity Server, you can create a certificate for MicroStrategy Identity Server. To do this, click Support to contact MicroStrategy and request help creating a certificate.

    To customize how keys are displayed to users in the MicroStrategy Badge app, see Managing Physical Access Keys.

Related Topics

Verifying that the S2 Adapter Installation is Correct

Creating a MicroStrategy Identity Network and Issuing an Administrator Badge

Distributing Badges to Users in Your MicroStrategy Identity Network

Categorizing MicroStrategy Badge Resources