In this article I want to share with you my experience of use of Cisco ACS API. Due to lack of examples and documentation, I had a bad times when was trying to get it working with PowerShell. So I hope this will be helpful for you if you have need to utilize API for some tasks. My work is related to Cisco ACS version 5.8.x.

Preface

First of all, I want to point out this github repository of Python implementation of scripts that uses ACS API. If you're trying with Python, it will help alot, cause repository has almost everything set and only that you need is to figure out how it works and adjust it for your requirements. But in this repository I have not found the use of filters, which is sad, because filters gives you lot of abilities.

You can get info about REST API from Cisco site - https://www.cisco.com/c/en/us/td/docs/net_mgmt/cisco_secure_access_control_system/5-8/sdk/acs_sdk/rest.pdf. There you will find REST API endpoints, their descriptions and so on. It also contains examples in Java. More examples for Java can be downloaded from Cisco ACS interface, in REST API section under settings menu.

How to use

Lets start from one feature that you will probably want to use - save your ACS credentials in encrypted format localy. This will save your time when you will adopt script for your needs. Also keep in mind, that saved credentials are accessible only under your username and only on PC on which you saved them.

$credential = Get-Credential
$credential | Export-CliXml -Path 'C:\My\Path\cred.xml'

Result XML file will look like this:

<Objs Version="1.1.0.1" xmlns="http://schemas.microsoft.com/powershell/2004/04">
  <Obj RefId="0">
    <TN RefId="0">
      <T>System.Management.Automation.PSCredential</T>
      <T>System.Object</T>
    </TN>
    <ToString>System.Management.Automation.PSCredential</ToString>
    <Props>
      <S N="UserName">test</S>
      <SS N="Password">01000000d08c9ddf0115d1118c7a00c04fc297eb010000006c5c1acd25ff394db4e123c036ae783c0000000002000000000010660000000100002000000098ef09e890d770a7ed52d011990425901bd56220714ebee634e1aa213ee9c386000000000e80000000020000200000005ed591e71f0ddb895d8c97dc0aa6c72e8fb3b43bb9d0115845141dd479f2407b10000000f0c22026f48fd997008840ce3ab4309d4000000086beb22b08493dcdabed84a7112a1543cac4b87d907905b23787903b0b02089c7748d3251c7306571a27f2c39fe2d776cfc9f48238787f16cc9adb1ec13be6fa</SS>
    </Props>
  </Obj>
</Objs>

My sample code can be taken here - https://git.vacc-ua.org/prox/Cisco-REST-API-PowerShell. Before using example script, make sure that REST API is enabled in ACS settings.

Little info about how to use it. First of all, you need to fill required fields, which is ACS server address and credentials. Scroll down file ACSRest.ps1 and find block

# Load ACS auth credentials
$credential = Import-Clixml -Path ACScreds.xml
$u = $credential.UserName
$p = $credential.Password

This block requires you to have ACS credentials stored in ACScreds.xml as I told previously. Or you can comment these and simply put your user in password in cleartext directy in script, by typing them in variables below ($u and $p).

Next one required is

$ACSHost = "https://1.2.3.4"

Type here your ACS server address/hostname.

Function description

Before you can use any of functions, you need to execute script to obtain session cookie. If your credentials and server address are correct, you will be able to execute functions and get results.
Every function will require minimum two parameters: $acs and $session. After executing main script, these variables will be available in your PS session. Example of use: Command-Name -acs $ACSHost -session $rest_result['session']

Get-ACSUserByName

Find user specified by $username variable and return its data as XML.

Get-FilterDevicesByName

Get devices that matches filter. Example of device filter can be found in repo (device_filter.xml).

Get-AllLocations

Return locations (as XML) that matching $filter or all locations if $filter is not set or $null.

Get-DevicesByLocation

Get device list for specified location. $location is String (ex. All_locations:Location1:Sublocation2). $path variable should contain path where device XML's will be saved. This function also uses tpl_location_filter.xml.

Get-DevicesByLocationTXT

Same as previous, but will print out devices to console.

Get-LocationIDByName

Return location XML data by location name (ex. All_locations:Location1:Sublocation2).
IDK why it's called Get-LocationIDByName... if it's not returning only ID... Probably historical stuff :D

Get-DeviceByName

Return device XML data by device name.

Del-LocationByID

Deletes location specified by location ID in $loc_id variable.

Upd-DeviceLocation

Changes device location. Device is passed by $device variable. Device XML can be retrieved by Get-DeviceByName function.

Upd-DeviceType

Changes device type. Device is passed by $device variable. Device XML can be retrieved by Get-DeviceByName function. $newtype is a string (ex. Devices:Cisco:Router3925).

Upd-UserIdentityGroup

Updates user IdentityGroup to $newig. User should be passed as XML. $newig format: All_groups:Group1:Subgroup2.

If you have any questions, feel free to ask them in a comments section.