/ 
Net-Cisco-ISE-0.05
River stage zero No dependents
/ Net::Cisco::ISE

NAME

Net::Cisco::ISE - Access Cisco ISE functionality through REST API

SYNOPSIS

	use Net::Cisco::ISE;
	my $ise = Net::Cisco::ISE->new(hostname => '10.0.0.1', username => 'admin', password => 'testPassword');
	# Options:
	# hostname - IP or hostname of Cisco ISE 5.x server
	# username - Username of Administrator user
	# password - Password of user
	# port - TCP port 9060 by default
	# ssl - SSL enabled (1 - default) or disabled (0)
		
	my %users = $ise->internalusers;
	# Retrieve all users from ISE
	# Returns hash with username / Net::Cisco::ISE::InternalUser pairs
	
	print $ise->internalusers->{"admin"}->toXML;
	# Dump in XML format (used by ISE for API calls)
	
	my $user = $ise->internalusers("name","admin");
	# Faster call to request specific user information by name

	my $user = $ise->internalusers("id","b74a0ef2-b29c-40e3-a0d1-4c0dfb51ace9");
	# Faster call to request specific user information by ID (assigned by ISE, present in Net::Cisco::ISE::InternalUser)

	my %identitygroups = $ise->identitygroups;
	# Retrieve all identitygroups from ISE
	# Returns hash with name / Net::Cisco::ISE::IdentityGroup pairs
	
	print $ise->identitygroups->{"All Groups"}->toXML;
	# Dump in XML format (used by ISE for API calls)
	
	my $identitygroup = $ise->identitygroups("name","All Groups");
	# Faster call to request specific identity group information by name

	my $identitygroup = $ise->identitygroups("id","4fffc260-9b96-11e6-93fb-005056ad1454");
	# Faster call to request specific identity group information by ID (assigned by ISE, present in Net::Cisco::ISE::IdentityGroup)

	my $device = $acs->networkdevices("name","MAIN_Router");
	# Faster call to request specific device information by name

	my $device = $acs->networkdevices("id","250");
	# Faster call to request specific device information by ID (assigned by ISE, present in Net::Cisco::ISE::NetworkDevice)
	
	$user->id(0); # Required for new user!
	my $id = $ise->create($user);
	# Create new user based on Net::Cisco::ISE::InternalUser instance
	# Return value is ID generated by ISE
	print "Record ID is $id" if $id;
	print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure

	my $id = $ise->create(@users); # Still requires nullified ID!
	# Create new users based on Net::Cisco::ISE::InternalUser instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure    
    
	$identitygroup->id(0); # Required for new record!
	my $id = $ise->create($identitygroup);
	# Create new identity group based on Net::Cisco::ISE::IdentityGroup instance
	# Return value is ID generated by ISE
	print "Record ID is $id" if $id;
	print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure

    # Cisco ISE does not support modifying an identity group through the API
	
	my $id = $ise->update($user);
	# Update existing user based on Net::Cisco::ISE::InternalUser instance
	# Return value is ID generated by ISE
	print "Record ID is $id" if $id;
	print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure

	my $id = $ise->update(@users);
	# Update existing users based on Net::Cisco::ISE::InternalUser instances in arguments
	# Return value is not guaranteed in this case!
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure        
        
	$ise->delete($user);
	# Delete existing user based on Net::Cisco::ISE::InternalUser instance

DESCRIPTION

Net::Cisco::ISE is an implementation of the Cisco Identity Services Engine (ISE) REST API. Cisco ISE is a application / appliance that can be used for network access policy control. In short, it allows configuration of access policies for specific users onto specific devices and applications (either using RADIUS or TACACS+ authentication). Net::Cisco::ISE currently supports InternalUser and IdentityGroup.

USAGE

All calls are handled through an instance of the Net::Cisco::ISE class.

use Net::Cisco::ISE;
my $ise = Net::Cisco::ISE->new(hostname => '10.0.0.1', username => 'admin', password => 'testPassword');
new

Class constructor. Returns object of Net::Cisco::ISE on succes. Required fields are:

hostname
username
password

Optional fields are

ssl
ssl_options
hostname

IP or hostname of Cisco ISE 2.x server. This is a required value in the constructor but can be redefined afterwards.

username

Username of Administrator user. This is a required value in the constructor but can be redefined afterwards.

password

Password of user. This is a required value in the constructor but can be redefined afterwards.

ssl

SSL enabled (1 - default) or disabled (0).

ssl_options

Value is passed directly to LWP::UserAGent as ssl_opt. Default value (hash-ref) is

{ 'SSL_verify_mode' => SSL_VERIFY_NONE, 'verify_hostname' => '0' }

From the class instance, call the different methods for retrieving values.

users

Returns hash or single instance, depending on context.

my %users = $ise->internalusers(); # Slow
my $user = $ise->internalusers()->{"admin"};
print $user->name;

The returned hash contains instances of Net::Cisco::ISE::InternalUser, using name (typically the username) as the hash key. Using a call to users with no arguments will retrieve all users and can take quite a few seconds (depending on the size of your database). When you know the username or ID, use the users call with arguments as listed below.

my $user = $ise->internalusers("name","admin"); # Faster
# or
my $user = $ise->internalusers("id","b74a0ef2-b29c-40e3-a0d1-4c0dfb51ace9"); # Faster
print $user->name;

The ID is typically generated by Cisco ISE when the entry is created. It can be retrieved by calling the C<id> method on the object.

print $user->id;
identitygroups

Returns hash or single instance, depending on context.

my %identitygroups = $ise->identitygroups(); # Slow
my $identitygroup = $ise->identitygroups()->{"All Groups"};
print $identitgroup->name;

The returned hash contains instances of Net::Cisco::ISE::IdentityGroup, using name (typically the username) as the hash key. Using a call to identitygroup with no arguments will retrieve all identitygroups and can take quite a few seconds (depending on the size of your database). When you know the group name or ID, use the identitygroups call with arguments as listed below.

my $identitygroup = $ise->identitygroups("name","All Groups"); # Faster
# or
my $identitygroup = $ise->identitygroups("id","4fffc260-9b96-11e6-93fb-005056ad1454"); # Faster
print $identitygroup->name;

The ID is typically generated by Cisco ISE when the entry is created. It can be retrieved by calling the C<id> method on the object.

print $identitygroup->id;
devices

Returns hash or single instance, depending on context.

my %devices = $acs->networkdevices(); # Slow
my $device = $acs->networkdevices()->{"Main_Router"};
print $device->name;

The returned hash contains instances of Net::Cisco::ISE::NetworkDevice, using name (typically the sysname) as the hash key. Using a call to device with no arguments will retrieve all devices and can take quite a few seconds (depending on the size of your database). When you know the hostname or ID, use the devices call with arguments as listed below.

my $device = $acs->device("name","Main_Router"); # Faster
# or
my $device = $acs->device("id","123"); # Faster
print $device->name;

The ID is typically generated by Cisco ISE when the entry is created. It can be retrieved by calling the C<id> method on the object.

print $device->id;
devicegroups

Returns hash or single instance, depending on context.

my %devicegroups = $acs->networkdevicegroups(); # Slow
my $devicegroup = $acs->networkdevicegroups()->{"All Locations:Main Site"};
print $devicegroup->name;

The returned hash contains instances of Net::Cisco::ISE::NetworkDeviceGroup, using name (typically the device group name) as the hash key. Using a call to devicegroups with no arguments will retrieve all device groups and can take quite a few seconds (depending on the size of your database). When you know the device group or ID, use the devicegroups call with arguments as listed below.

my $devicegroup = $acs->networkdevicegroups("name","All Locations::Main Site"); # Faster
# or
my $devicegroup = $acs->networkdevicegroups("id","123"); # Faster
print $devicegroup->name;

The ID is typically generated by Cisco ISE when the entry is created. It can be retrieved by calling the id method on the object.

print $devicegroup->id;
create

This method created a new entry in Cisco ISE, depending on the argument passed. Record type is detected automatically. For all record types, the ID value must be set to 0.

my $user = $ise->internalusers("name","admin");
$user->id(0); # Required for new user!
$user->name("altadmin"); # Required field
$user->password("TopSecret"); # Password policies will be enforced!
$user->description("Alternate Admin"); 
my $id = $ise->create($user); 
# Create new user based on Net::Cisco::ISE::InternalUser instance
# Return value is ID generated by ISE
print "Record ID is $id" if $id;
print $Net::Cisco::ISE::ERROR unless $id;
# $Net::Cisco::ISE::ERROR contains details about failure

my $device = $acs->networkdevices("name","Main_Router");
$device->name("AltRouter"); # Required field
$device->description("Standby Router"); 
$device->ips([{netMask => "32", ipAddress=>"10.0.0.2"}]); # Change IP address! Overlap check is enforced!
$device->id(0); # Required for new device!
my $id = $acs->create($device);
# Create new device based on Net::Cisco::ISE::NetworkDevice instance
# Return value is ID generated by ISE
print "Record ID is $id" if $id;
print $Net::Cisco::ISE::ERROR unless $id;
# $Net::Cisco::ISE::ERROR contains details about failure

Multiple instances can be passed as an argument. Objects will be created in bulk (one transaction). The returned ID is not guaranteed to be the IDs of the created objects.

	my $user = $ise->internalusers("name","admin");
	$user->id(0); # Required for new user!
	$user->name("altadmin"); # Required field
	$user->password("TopSecret"); # Password policies will be enforced!
	$user->description("Alternate Admin"); 

	my $user2 = $ise->internalusers("name","admin");
	$user2->id(0); # Required for new user!
	$user2->name("altadmin"); # Required field
	$user2->password("TopSecret"); # Password policies will be enforced!
	$user2->description("Alternate Admin"); 

	my $id = $ise->create($user,$user2); 
	# Create new users based on Net::Cisco::ISE::InternalUser instances in argument.
	# Return value is ID generated by ISE but not guaranteed.
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure
update

This method updates an existing entry in Cisco ISE, depending on the argument passed. Record type is detected automatically.

my $user = $ise->internalusers("name","admin");
$user->password("TopSecret"); # Change password. Password policies will be enforced!
my $id = $ise->update($user);
# Update user based on Net::Cisco::ISE::InternalUser instance
# Return value is ID generated by ISE
print "Record ID is $id" if $id;
print $Net::Cisco::ISE::ERROR unless $id;
# $Net::Cisco::ISE::ERROR contains details about failure

my $device = $acs->networkdevices("name","Main_Router");
$user->description("To be ceased"); # Change description
$device->ips([{netMask => "32", ipAddress=>"10.0.0.2"}]); # or Change IP address. Overlap check is enforced!
my $id = $acs->update($device);
# Create new device based on Net::Cisco::ISE::NetworkDevice instance
# Return value is ID generated by ISE
print "Record ID is $id" if $id;
print $Net::Cisco::ISE::ERROR unless $id;
# $Net::Cisco::ISE::ERROR contains details about failure

Multiple instances can be passed as an argument. Objects will be updated in bulk (one transaction). The returned ID is not guaranteed to be the IDs of the created objects.

	my $user = $ise->internalusers("name","admin");
	$user->id(0); # Required for new user!
	$user->password("TopSecret"); # Password policies will be enforced!

	my $user2 = $ise->internalusers("name","admin2");
	$user2->password("TopSecret"); # Password policies will be enforced!

	my $id = $ise->update($user,$user2); 
	# Update users based on Net::Cisco::ISE::InternalUser instances in arguments
	# Return value is ID generated by ISE but not guaranteed.
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure

	my $device = $acs->networkdevices("name","Main_Router");
	$device->description("Main Router"); 
	$device->ips([{netMask => "32", ipAddress=>"10.0.0.1"}]); # Change IP address! Overlap check is enforced!

	my $device2 = $acs->networkdevices("name","Alt_Router");
	$device2->description("Standby Router"); 
	$device2->ips([{netMask => "32", ipAddress=>"10.0.0.2"}]); # Change IP address! Overlap check is enforced!
	
    my $id = $acs->create($device,$device2);
	# Update devices based on Net::Cisco::ISE::NetworkDevice instances in arguments
	# Return value is ID generated by ISE but not guaranteed.
	# print "Record ID is $id" if $id;
	# print $Net::Cisco::ISE::ERROR unless $id;
	# $Net::Cisco::ISE::ERROR contains details about failure
delete

This method deletes an existing entry in Cisco ISE, depending on the argument passed. Record type is detected automatically.

my $user = $ise->internalusers("name","admin");
$ise->delete($user);
$ERROR

This variable will contain detailed error information, based on the REST API answer. This value is reset during every call to internalusers and identitygroups.

REQUIREMENTS

For this library to work, you need an instance with Cisco ISE (obviously) or a simulator like Net::Cisco::ISE::Mock.

Instructions on enabling Cisco ISE for API access will be added later.

You will also need

Moose
IO::Socket::SSL
LWP::UserAgent
XML::Simple
MIME::Base64
URI::Escape

BUGS

None so far

SUPPORT

None so far :)

AUTHOR

Hendrik Van Belleghem
CPAN ID: BEATNIK
hendrik.vanbelleghem@gmail.com

COPYRIGHT

This program is free software licensed under the...

The General Public License (GPL)
Version 2, June 1991

The full text of the license can be found in the LICENSE file included with this module.

COMPATIBILITY

Certain API calls are not support from Cisco ISE 5.0 onwards. The current supported versions of Cisco ISE (by Cisco) are 5.6, 5.7 and 5.8 (Active).

SEE ALSO