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:

1. 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.
2. 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.0

title: Device Enrollment

version: v1

baseUri: 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/json

description: |

  API documentation for the SafeConnect Device Enrollment system.

  Available since SafeConnect version 6.5.0

uses:

  hal : https://bitbucket.org/impulsepoint/raml-docs/raw/master/raml/hal/hal.raml

types:

  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

XML APIs

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

Policy Group Update

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:

<genericPolicyRequest>

    <credentials>

        <username>apiUsername</username>

        <password>apiPassword</password>

    </credentials>

    <groupDefinitionRequest>

        <groupName>Block Access</groupName>

        <action>add</action>

        <ip>169.0.0.1</ip>

        <username/>

        <macAddress/>

        <note>REMARK - DMCA Violation</note>

        <expiresInSeconds/>

        <standardOutput>true</standardOutput>

    </groupDefinitionRequest>

</genericPolicyRequest>

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

<genericPolicyRequest>

    <credentials>

        <username>apiUsername</username>

        <password>apiPassword</password>

    </credentials>

    <groupDefinitionRequest>

        <groupName>Block Access</groupName>

        <action>remove</action>

        <ip>169.0.0.1</ip>

        <username/>

        <macAddress/>

        <note>REMARK - Max test</note>

        <expiresInSeconds/>

        <standardOutput>true</standardOutput>

    </groupDefinitionRequest>

</genericPolicyRequest>

Return Values

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

<groupDefResponse>

    <result>Success</result>

    <action>added</action>

    <extra>169.0.0.1</extra>

</groupDefResponse>

A successful removal from a group will return:

<groupDefResponse>

    <result>Success</result>

    <action>removed</action>

    <extra>169.0.0.1</extra>

</groupDefResponse>

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

<apiResponse>

    <result>Failure</result>

    <action>login</action>

    <extra>invalid credentials</extra>

</apiResponse>

A failure to create a duplicate will return:

<groupDefResponse>

    <result>Failure</result>

    <action>added</action>

    <extra>entry already exists,not added again</extra>

</groupDefResponse>

A failure to remove will return:

<groupDefResponse>

    <result>Failure</result>

    <action>removed</action>

    <extra>entry was not there</extra>

</groupDefResponse>

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

<groupDefResponse>

    <result>Failure</result>

    <action>removed</action>

    <extra>no action</extra>

</groupDefResponse>

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:

<qualifierRequest>

    <credentials>

        <username>testapi</username>

        <password>testapi</password>

    </credentials>

    <qualifierDetails>

        <ip/>

        <principal/>

        <macAddress>00022d85288c</macAddress>

        <standardOutput>true</standardOutput>

    </qualifierDetails>

</qualifierRequest>

Response:

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

<qualifierInquiryResponse>

    <result>Success</result>

    <action>query</action>

    <extra>

        <ipAddress/>

        <macAddress>00022d85288c</macAddress>

        <principal/>

        <groupLabel>Registered Devices With Policy Key</groupLabel>

    </extra>

</qualifierInquiryResponse>

A search result with no matches will return the following:

<qualifierInquiryResponse>

    <result>Failure</result>

    <action>query</action>

    <extra>no information found for the submitted qualifier</extra>

</qualifierInquiryResponse>

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.

curl GET on /apis/guestProfile

> curl -k --digest --user username:password https://portal.myweblogon.com:8443/apis/guestProfile

• 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.

curl PUT on /apis/guestProfiles/\{id\}

# Enabled Guest Profile with ID of 42

> curl -k --digest --user username:password -X PUT https://portal.myweblogon.com:8443/apis/guestProfile/42?enabled=true

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