API Documentation

API documentation produced for new MetaAccess NAC features will be available at https://docs.cloud.impulse.com/.

Device Enrollment

We support the enrollment of MAC addresses for use in a RADIUS-based-enforcement environment. This supports two use cases:

Configuring the initial role a device is assigned on first entry into the system, even before SafeConnect enforcement applies. This can be used to work around devices that require special set up or do not respond to RADIUS disconnects or VLAN switching.
Setting the RADIUS server to operate in a allowlist mode, where only permitted devices are allowed on. All other devices would be rejected during the RADIUS transaction, before reaching the SafeConnect enforcement system.
- This setting overlaps with RADIUS configuration. Whether an RBE enforcement device uses the MAC address bulk uploading as a allowlist is configurable from the RADIUS configuration page.

This page exposes the bulk-upload API, and the ability to view the uploaded records.

If you need to enable allowlist behavior, you will do so per-agent on the RADIUS configuration page. The relevant field is "Use Authorized Devices as a Allowlist".

RAML

The following is the RAML document representing the current state of the API. This document was used to generate the previous page.

    
#%RAML 1.0title: Device Enrollmentversion: v1baseUri: https://{safeconnect}/camel/enrollment/{version}baseUriParameters:  safeconnect:    description: The URL or IP address of your SafeConnect manager, or the single SafeConnect appliance in a standalone configuration.mediaType: application/jsondescription: |  API documentation for the SafeConnect Device Enrollment system.  Available since SafeConnect version 6.5.0uses:  hal : https://bitbucket.org/impulsepoint/raml-docs/raw/master/raml/hal/hal.ramltypes:  deviceEnrollment:    type: object    properties:      macAddress: string      role: string      description: string  deviceEnrollmentResource:    type: deviceEnrollment    properties:      _links: hal.selfLink  deviceEnrollmentPage:    type: object    description: A HAL deviceEnrollment page representation    properties:      _embedded: deviceEnrollmentResource[]      _links: hal.halPageLinks      page: hal.halPage/device:  get:    description: Retrieve a page of enrollment records    is: [hal.paged]    responses:      200:        body:          application/hal+json:            type: deviceEnrollmentPage            example: |              {                "_embedded": {                  "deviceEnrollments": [                    {                      "macAddress": "aabbccddeeff",                      "role": "SC_Initial_Role",                      "description": "<descriptive text>",                      "_links": {                        "self": {                          "href": "http://127.0.0.1:8096/enrollment/v1/device/aabbccddeeff"                        }                      }                    }                  ]                },                "_links": {                  "self": {                    "href": "http://127.0.0.1:8096/enrollment/v1/device"                  }                },                "page": {                  "size": 20,                  "totalElements": 1,                  "totalPages": 1,                  "number": 0                }              }  post:    description: Save a new enrollment record    body:      application/json:        type: deviceEnrollment        example: |          {            "macAddress": "aabbccddeeff",            "role": "SC_Initial_Role",            "description": "<descriptive text>"          }    responses:      200:        description: New enrollment saved      400:        body:          type: string          description: Describes why the proposed new enrollment isn't valid      409:        body:          type: string          description: Describes the conflict with the proprosed new enrollment      500:        description: An unexpected server error occurred  delete:    description: Delete all enrollments.    responses:      200:        description: All enrollments deleted      500:        description: An unexpected server error occurred  /bulk:    post:      description: Upload a spreadsheet file (csv, xls, xlsx) with enrollment records      body:        multipart/form-data:          properties:            file:              description: The file to be uploaded              type: file              required: true              example: |                mac address,role,description                aabbccddeeff,SC_Initial_Role,<descriptive text>                000000000001,SC_Quarantine_Role,<another enrollment>      responses:        200:          description: New enrollments saved, and existing enrollments updated.        400:          description: Describes why the provided enrollments aren't valid.        500:          description: An unexpected server error occurred  /{macAddress}:    get:      description: Retrieve a specific enrollment record      responses:        200:          body:            application/hal+json:              type: deviceEnrollmentResource              example: |                {                  "macAddress": "aabbccddeeff",                  "role": "SC_Initial_Role",                  "description": "<descriptive text>",                  "_links": {                    "self": {                      "href": "http://127.0.0.1:8096/enrollment/v1/device/aabbccddeeff"                    }                  }                }        400:          description: If the macAddress path parameter isn't a valid MAC address        404:          description: If the macAddress path parameter doesn't have an enrollment record    put:      description: Update an existing enrollment.      body:        application/json:          type: deviceEnrollment          example: |            {              "macAddress": "aabbccddeeff",              "role": "SC_Initial_Role",              "description": "<descriptive text>"            }      responses:        200:          description: Update processed successfully. After the update, the device enrollment record         400:          description: The proposed update isn't valid        404:          description: The macAddress path parameter doesn't have an enrollment record        409:          description: The proposed update conflicts with another enrollment        500:          description: An unexpected server error occurred    delete:      description: Delete an existing enrollment      responses:        200:          description: Enrollment deleted successfully        400:          description: If the macAddress path parameter isn't a valid MAC address        404:          description: If the macAddress path parameter doesn't have an enrollment record        500:          description: An unexpected server error occurred
Copy

Make An Account

Log into the configuration interface with a username/password that has privileges to create user accounts.

Make sure a profile exists with both the "Read" and "Write" versions of the "Legacy API Access" privilege. Here we are creating a profile called "legacy".

Make a new user that uses a profile that contains the legacy API privilege. Here we have created a user with the following properties:

Username: apiuser
Password: A@p!i12#3
Profile: legacy (which we just created)

At this point, this new user may make requests against the XML APIs. Requests are sent as an HTTP POST to: https://portal.myweblogon.com:8443/impulse.api

This API should be used to add or remove qualifiers to policy groups in the system. This may be used to (temporarily) block or allow access to individual clients. For example, another system may make automated requests to block a client for a violation of security practices.

XML Structure

Credentials
- <username>[username]</username>
  - The username for the user created in the previous step. Do not include the [].
- <password>[password]</password>
  - The password for the user created in the previous step. Do not include the [].
<groupName>[Group Name]</groupName>
- The target group you want the user added to or removed from
  - Valid groups include
    - Block Access
    - Open Access
Define only one of the following blocking criteria (leave the other criteria defined, with blank values):
- <ip>[IP address]</ip>
  - Enter the IP address of the desired target host
- <username>[Username]</username>
  - Enter the username of the desired target host
- <macAddress>[MAC Address]</macAddress>
  - Enter the MAC address of the desired target host
Optional
- <note>[Enter user note]</note>
  - The REMARK keyword followed by any text int he Block Access list will display whatever text is after the REMARK keyword to the user
    - REMARK DMCA Violation #123
      - Will show "DMCA Violation #123" to the client
- <expiresInSeconds>[Expiration time]</expiresInSeconds>
  - Enter the time a user will remain in the respective group. When the time is reached, the user is automatically removed from the group, and returned to their normal policy group.
    - Enter "86400" to expire in one day.
  - If no time is entered, the user will be in the desired group until removed manually.
- <automaticallyManage>[true|false]</automaticallyManage>
  - If omitted, defaults to false.
  - Only used when adding qualifiers.
    - true
      - Any IP or MAC address qualifiers will be updated as network interfaces change. For example, if a device gets a new IP address through DHCP the qualifier will update to match. This only applies to the groups “Block Access” and “Open Access”. If another group is used, this behaves the same as “false”.
    - false
      - Any IP or MAC address qualifiers will be constant, and will not change to reflect new host data. This is the default if the automaticallyManage tag is omitted.
Deprecated
- <standardOutput>true</standardOutput>
  - If present, should be set to "true".
  - If false, formats the output for use in the XML API user interface. This user interface is deprecated.

Examples

To add a user with IP address 169.0.0.1 to the Block Access group:

To remove a user with IP address 169.0.0.1 from the Block Access group:

Return Values

Successful submissions return the "Success" keyword in the "result" tag. A successful addition to a group will return:

A successful removal from a group will return:

Errors return the "Failure" keyword in the "result" tag. A failure due to bad credentials will return:

A failure to create a duplicate will return:

A failure to remove will return:

Any other kind of failure (usually providing a bad group name):

Qualifier Inquiry

Starting with the 6.1 release, we have a new API to query. If a specific IP or username or MAC address is setup in one of the Policy groups in the system, this API will return the group it belongs in. This may be used for allowing some other system to determine which group a client is in.

Define only one of the following inquiry criteria (leave the other criteria defined, with blank values):
- <ip>[IP address]</ip>
  - Enter the IP address of the desired target host
- <username>[Username]</username>
  - Enter the username of the desired target host
- <macAddress>[MAC Address]</macAddress>
  - Enter the MAC Address of the desired target host

Request:

Response:

A search result matching the input will return the following fields:

A search result with no matches will return the following:

Guest Profile API

The Guest Profile API in version 6.5.16 provides access to retrieve a list of all guest profiles and the ability to enable/disable guest profiles by ID. This functionality allows guest profiles to be temporarily disabled and enabled again later. For example, a SafeConnect admin might disable guest profiles over a weekend and then enable them again on weekdays. Note that as of version 6.5.16, there is no means to disable all guest profiles with a single call. To disable multiple guest profiles, the SafeConnect admin needs to make separate calls for each profile.

Enabling and disabling Guest Profiles

The two following cURL commands allow admins with read/write privileges to enable and disable guest profiles by ID:

Get a list of all guest profiles using endpoint "https://portal.myweblogon.com:8443/apis/guestProfile". Use the following command to obtain the guest profile ID necessary to disable and enable a guest profile. Replace "username" and "password" with the administrative user's information in the corresponding fields. “portal.myweblogon.com” can be replaced with the IP address of the SafeConnect appliance or the custom hostname of the appliance, if applicable.

Enable or disable a guest profile by ID with the following cURL command. To disable as opposed to enable, change the portion of the URL that reads "true" to "false". Replace the guest ID in the code block with the ID obtained from the cURL command to be disabled or enabled. Replace "username" and "password" with the SafeConnect admin's information in the corresponding fields. “portal.myweblogon.com” can be replaced with the IP address of the SafeConnect appliance or the custom hostname of the appliance, if applicable.

To enable or disable additional guest profiles, repeat this process until all guest IDs statuses are in their desired states.

Last updated on

Was this page helpful?