Add a device to an Access group

Overview

Access groups help synchronize Access policies across multiple devices. The devices that need a common set of Access policies must be added to an Access group in order to provide a synchronized configuration.  This document describes the necessary APIs and steps needed to add a device to an Access group.

Prerequisites

To add the device to an Access group, the following prerequisites must be met.

  • The BIG-IQ system is operational, has completed the setup, and has all the system level configurations in place.
  • An Access group is created with zero or more devices.
  • To add devices to an Access group, users need the necessary RBAC permissions for the “Trust Discovery and Import” role.

Required Information

In addition to the prerequisites, the user must provide the following in order to add the device to an Access group.

  • An Access group name.
  • The BIG-IP device IP addresses.
  • The BIG-IP device user name.
  • The BIG-IP device user password.
  • The BIG-IP device reference for the existing discovered device in the BIG-IQ system.

Actions

Using the BIG-IQ API, users can complete the following actions to collect necessary information and add one or more devices to an Access group.

  • Retrieve an Access group name used for importing by listing existing Access groups.
  • Add new devices to an Access group by initiating and monitoring the “Discovery and Import Controller” task.

List existing Access groups

To list an existing Access group, users must use the “Device Groups” API. This API lists all device groups in the system.  Use the $filter='properties/cm:access:access_group' eq 'true' filter parameters to get a list of Access groups.

GET  https://<management_ip>/mgmt/shared/resolver/device-groups?$filter='properties/cm:access:access_group' eq 'true'

Response

{
    "totalItems": 1,
    "items": [
        {
            "devicesReference": {
                "link": "https://localhost/mgmt/shared/resolver/device-groups/<access_group_name>/devices"
            },
            "displayName": “<access_group_name>",
            "groupName": “<access_group_name>",
            "infrastructure": false,
            "isViewGroup": false,
            "kind": "shared:resolver:device-groups:devicegroupstate",
            "properties": {
                "cm:access:swg-provisioned": true,
                "cm:gui:module": [
                    "Access"
                ],
                "cm:access:access_group": true,
                "importedDateTime": "2018-02-08T04:12:29.244Z",
                "cm:access:access-group-version": "13.1.0"
            },
            "selfLink": "https://localhost/mgmt/shared/resolver/device-groups/<access_group_name>"
        }
    ],
    "selfLink": "https://localhost/mgmt/shared/resolver/device-groups",
    "kind": "shared:resolver:device-groups:devicegroupcollectionstate",
}

Initiate and Monitor the “Device Discovery and Import Controller” task to add new devices to an Access group

To add one or more new devices to an Access group, users must complete the“Device Discovery and Import Controller” task.  An Access group name obtained from “Get an Access group”, list of new device details, add_core, and LTM modules must be imported to complete this step.

POST https://<management_ip>/mgmt/cm/global/tasks/device-discovery-import-controller
{
        "name" : "add_new_device_1_to_access_group",
        "operationalMode": "NEW_DEVICE",
        "deviceDetails": [{
                "newDevice": {
                        "address": “<device_ip_address>",
                        "httpsPort": <device_https_port_range>,
                        "userName": "admin",
                        "password": “password",
                        "clusterName": "cluster_1",
                        "useBigiqSync": false,
                        "deployWhenDscChangesPending": false
                },
                "moduleList": [{
                                "module": "adc_core"
                        },
                        {
                                "module": “access"
                        }
                ]
        }],
        "conflictPolicy": "USE_BIGIP",
        "deviceConflictPolicy": "USE_BIGIP",
        "snapshotWorkingConfig": true,
        "accessGroupName": “<access_group_name>"
}

Poll for the status of the task until the task ‘status’ changes to FINISHED or FAILED state. When the task completes, device import status can be obtained from the deviceStatus field for each device.

GET  https://<management_ip>/mgmt/cm/global/tasks/device-discovery-import-controller/<task_id>

Response:

{
        "accessGroupName": “<access_group_name>",
        "conflictPolicy": "USE_BIGIP",
        "currentStep": "DISCOVER_DEVICES",
        "deviceConflictPolicy": "USE_BIGIP",
        "deviceDetails": [
                {
                        "deviceReference": {
                                "link": "https://localhost/mgmt/cm/system/machineid-resolver/3b556a3e-0ef8-4805-9c9c-b403e673dff2"
                        },
                        "newDevice": {
                                "address": “<device_ip>",
                                "httpsPort": <device_https_port_default_443>,
                                "userName": "admin",
                                "password": "3q771weLjq4oM/5KE1NHYeEH2PmUVx+7ffvWOuIJYxA=",
                                "clusterName": "cluster_1",
                                "useBigiqSync": false,
                                "deployWhenDscChangesPending": false
                        },
                        "moduleList": [
                                {
                                        "module": "adc_core"
                                },
                                {
                                        "module": "access",
                                        "properties": {
                                                "cm:access:conflict-resolution": "accept",
                                                "cm:access:access-group-name": “<access_group_name>",
                                                "cm:access:import-shared": "false"
                                        }
                                }
                        ],
                        "deviceStatus": "DISCOVERY_STAGE",
                        "trustTaskReference": {
                                "link": "https://localhost/mgmt/cm/global/tasks/device-trust/e3e461b5-0fc4-4f5f-a83e-8388f0603b93"
                        }
                }
        ],
        "id": “<task_id>",
        "identityReferences": [
                {
                        "link": "https://localhost/mgmt/shared/authz/users/admin"
                }
        ],
        "kind": "cm:global:tasks:device-discovery-import-controller:discoveryandimportcontrollertaskitemstate",
        "name": "add_new_device_1_to_access_group",
        "operationalMode": "NEW_DEVICE",
        "ownerMachineId": "30f43266-b545-4ac8-b64e-d524d2e13730",
        "selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/<task_id>",
        "snapshotWorkingConfig": true,
        "startDateTime": "2018-02-08T04:29:07.710-0800",
        "status": "STARTED",
        "userReference": {
                "link": "https://localhost/mgmt/shared/authz/users/admin"
        },
        "username": "admin"
}
GET  https://<management_ip>/mgmt/cm/global/tasks/device-discovery-import-controller/<task_id>

Response

{
        "accessGroupName": “<access_group_name>",
        "conflictPolicy": "USE_BIGIP",
        "currentStep": "DONE",
        "deviceConflictPolicy": "USE_BIGIP",
        "deviceDetails": [
                {
                        "deviceReference": {
                                "link": "https://localhost/mgmt/cm/system/machineid-resolver/3b556a3e-0ef8-4805-9c9c-b403e673dff2"
                        },
                        "newDevice": {
                                "address": “<device_ip_address>",
                                "httpsPort": <device_https_port_default_443>,
                                "userName": "admin",
                                "password": "3q771weLjq4oM/5KE1NHYeEH2PmUVx+7ffvWOuIJYxA=",
                                "clusterName": "cluster_1",
                                "useBigiqSync": false,
                                "deployWhenDscChangesPending": false
                        },
                        "moduleList": [
                                {
                                        "module": "adc_core"
                                },
                                {
                                        "module": "access",
                                        "properties": {
                                                "cm:access:conflict-resolution": "accept",
                                                "cm:access:access-group-name": “<access_group_name",
                                                "cm:access:import-shared": "false"
                                        }
                                }
                        ],
                        "deviceStatus": "FINISHED",
                        "trustTaskReference": {
                                "link": "https://localhost/mgmt/cm/global/tasks/device-trust/e3e461b5-0fc4-4f5f-a83e-8388f0603b93"
                        },
                        "superDiscoveryTaskReference": {
                                "link": "https://localhost/mgmt/cm/global/tasks/device-discovery/e5b9c1ec-2c87-450d-b3a7-cc5c453adf1b"
                        },
                        "superImportTaskReference": {
                                "link": "https://localhost/mgmt/cm/global/tasks/device-import/3fd301f2-c972-4f58-92ab-8622934fe6fa"
                        }
                }
        ],
        "endDateTime": "2018-02-08T04:31:08.309-0800",
        "generation": 9,
        "id": "78870ca9-8ef5-49d9-a95a-33c14dccb281",
        "identityReferences": [
                {
                        "link": "https://localhost/mgmt/shared/authz/users/admin"
                }
        ],
        "kind": "cm:global:tasks:device-discovery-import-controller:discoveryandimportcontrollertaskitemstate",
        "name": "add_device_1_to_access_group",
        "operationalMode": "NEW_DEVICE",
        "ownerMachineId": "30f43266-b545-4ac8-b64e-d524d2e13730",
        "selfLink": "https://localhost/mgmt/cm/global/tasks/device-discovery-import-controller/<task_id>,
        "snapshotWorkingConfig": true,
        "startDateTime": "2018-02-08T04:29:07.710-0800",
        "status": "FINISHED",
        "userReference": {
                "link": "https://localhost/mgmt/shared/authz/users/admin"
        },
        "username": "admin"
}

Result

By using the BIG-IQ API to perform the above tasks, users can write a script to add new devices to an Access group.