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.
