API Documentation

API documentation produced for new SafeConnect 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 whitelist 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 whitelist is configurable from the RADIUS configuration page.

images/download/attachments/7186746/screenshot-2017-06-28-16-23-22.png

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

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

images/download/attachments/7186746/screenshot-2017-06-28-16-24-32.png

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.

images/download/attachments/7186746/screenshot-2017-06-28-14-56-37.png

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

images/download/attachments/7186746/screenshot-2017-06-28-15-01-23.png

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)

images/download/attachments/7186746/screenshot-2017-06-28-15-08-47.png

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.