.. _apiserver: REST API Server ================ Genian NAC can use REST API Server as a source of user and organization information. REST API Server synchronization allows user accounts to be created locally and used for administration or policy. REST API Server requests are called using the HTTP GET method, and the response data format must be in JSON Object format. The following example describes how to synchronize user information with REST API, from the application Slack. User information in slack can be fetched through the users.list API, from URL https://slack.com/api/users.list which supports GET and POST requests. Info on how to use can be found at https://api.slack.com/methods/users.list In NAC, REST API information is provided through ``Swagger``. Select REST API Server as the DB type and enter https://slack.com as the server address. Enter ``/api/users.list?token=`` for the user information source. For column name, enter the path to extract values ​​from JSON Object. See the content below, or the previous users.list help link for more examples. Pre-Requisites (In Slack) ---------------------------- - Create a Slack app with a properly privileged Slack Workspace account. Use ** Add features and functionality > Permissions ** - Obtain an access token and give it a ``user:read`` OAuth Scope. In our example we will use a **Bot User OAuth Access Token** - Once these steps are completed, install the app to your Workspace. The app must be reinstalled after every configuration. Test the connection ---------------------- In order to perform a connection test, default values ​​must be entered for: +-----------------+-----------------------------+----------------------------------------------------+ | ITEM | set value | Description | +=================+=============================+====================================================+ | REST API Server | Server Address | Enter the server IP to call the REST API. | +-----------------+-----------------------------+----------------------------------------------------+ | | page parameter name | Page parameter name to process multiple outputs set| +-----------------+-----------------------------+----------------------------------------------------+ | | Page start number | Set the page start number. | +-----------------+-----------------------------+----------------------------------------------------+ | | Page Size Parameter Name | Enter the parameter name that specifies the number | +-----------------+-----------------------------+----------------------------------------------------+ | | | of prints on one page set. | +-----------------+-----------------------------+----------------------------------------------------+ | | page size | Set the number of prints per page. | +-----------------+-----------------------------+----------------------------------------------------+ | | datasource cutoff | Set when using multiple synchronization servers. | +-----------------+-----------------------------+----------------------------------------------------+ .. note:: If the connection test does not work properly, first check whether the communication between **Policy Server** and **Synchronization Server** is normal. Create sync settings -------------------- #. Go to **Preferences** In the top menu Bar #. Go to **User Authentication > Data Synchronization** in the left side panel. #. Select **Tasks > Create** and fill out the following forms. General ''''''' #. **ID** : Select a Name for the synchronization #. **Update Interval** : Configure when to synchronize the information. #. **Policy Apply** : Enable to reflect changes after synchronization. Data Source ''''''''''' * For DB type, select REST API Server and enter the server address being used. * Ex) ``https://slack.com`` for slack, ``https://(policy server IP):8443`` for NAC #. **DB Type** : ``REST API Server`` #. **Server Address** : Enter the URL of the server. #. **Parameter Name for Page Number** : Set the page number parameter name to be sent to the server during paging processing. #. **Start Number for Page Number** : Set the page start number during paging processing. #. **Parameter Name for Records Size Per Page** : Set the page size parameter name to be sent to the server during paging processing. #. **Records Size Per Page** : Set number of records to fetch per page. #. **Data Source Name** : Set a DSN to protect against accidental data deletion during synchs. .. note:: Steps 3-6 can be left at their default values when synching from Slack User Info ''''''''' When entering user information sources, enter ``/api/users.list?token=`` if using API Key for mutual authentication or ``/api/users.list`` if using API service account. * Column name enters the path to extract values ​​from JSON Object. path is separated by ``.`` * Ex) ID in case of JSON Response [ { "id": "..", "name": ".." }, { "id": "..", "name": ".." } ] Enter ``id`` for the column ID and ``name`` for the column name. * Ex) JSON Response { "users": { "members" : [ { "id": "..", "name": ".." }, { "id": "..", "name": In case of ".." } ] } }, enter ``users.members.id`` for the ID column name and ``users.members.name`` for the name column name. #. **Data Source** : Enter the path to query. In our case we will add our access token to the path where the user list is stored at slack.com. ``/api/users.list?token=xoxb-xxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx`` #. **Where Clause for User** : Leave blank. #. **Column Name for Username** : Enter the path of the desired user value in JSON Object. In this example we will use ``members.name`` to use the first name of the Slack user. #. **Column Name for Full Name** : Enter the path of the desired user value in JSON Object. In this example we will use ``members.real_name`` to use the display name of the Slack user. #. **Department ID column name** : Enter the path of the desired user value in JSON Object. In this example we will use ``members.team_id`` to use the team id of the Slack user. .. note:: - You may synch any variable returned with any info field that Genian NAC supports. Example: Email addresses as Usernames (may require different permissions in data source). - You can repeat the process show under the **User Info** section for Department, Job Title, Node, and Device information.