Reporting Using Agent-XML How to Guide

From Swivel Knowledgebase
Revision as of 16:31, 14 March 2014 by Gfield (talk)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


How To Report using Agent-XML

Overview

The Internal Swivel database contains some information that is not available through the Swivel Administration Console. This document outlines some of the information that can be queried.

The Audit Log is where Swivel maintains an activity log for users. This is set on the Swivel Administration console under Policy General Audit Log length (days): default value is 30. The Audit log is present in Swivel versions 3.4 onwards, previous versions will return a value of 0 for the data.

For further information on Agent-XML see: Agent-XML and ReportingAPI. For information reporting through the Swivel Administration console see Reporting How to guide.

Prerequisites

Internal Swivel Database

Audit log requires Swivel 3.4 or higher

Swivel Agent configured to allow XML-Authentication.

Agent-XML requests are made against port 8080 on Swivel virtual or hardware appliances rather than through the proxy port


Performing Agent_XML Queries

The Internal database can be queried using a web browser connected from a system that is configured as an Agent. To configure an XML Agent, on the Swivel Administration console select Server then Agents, enter the following information:

Agents:

  • Name: A descriptive name
  • Hostname/IP: IP or hostname from which the XML queries will be made
  • Shared secret: a value that needs to be the same on the Swivel server and the device from which XML queries will be made
  • Group: default ANY A group of users permitted to make authentication requests
  • Authentication Modes: default ALL whether single or dual channel authentication requests are permitted


Agent-XML Queries

Swivel virtual or hardware Appliance:

https://IP:8080/pinsafe/AdminXML?xml=<AdminRequest secret="secret" version="3.4"><Report repository="local"><query/></Report></AdminRequest>

Software Install:

http://IP:8080/pinsafe/AdminXML?xml=<AdminRequest secret="secret" version="3.4"><Report repository="local"><query/></Report></AdminRequest>

Report Format:

  • Replace IP with the Swivel server name or IP address. Depending on your

configuration, you may also need to change the port number, for Swivel virtual or hardware appliances this is 8080.

  • Replace local with the name of the Swivel repository you wish to query. You can only

query one repository at a time.

  • The machine from which you make the query must be a Swivel
  • Replace secret with the shared secret for that agent.
  • Replace <query/> with the query to be specified, see below
  • Replace version with the required version, usually 3.4 or 3.6


Show Idle user Accounts

<Idle since="dd-mmm-yyyy"/>

  • Replace {dd-mmm-yyyy} with the date to check. This must be in the format (for example) 01-Jul-2009.

This query will show users who have never logged in, this report does not show users that have NEVER logged in:

Example:

http://127.0.0.1:8080/pinsafe/AdminXML?xml=<AdminRequest secret="secret" version="3.4"><Report repository="local"><Idle since="01-jan-2010"/></Report></AdminRequest>

Example output:

   <?xml version="1.0" ?> 
 - <AdminResponse>
 - <Report repository="local">
 - <Idle>
   <User name="qwerty" /> 
   </Idle>
   </Report>
   </AdminResponse>


Show Disabled User Accounts

<Disabled/>

This query will show which user accounts have the status disabled.

Example:

http://127.0.0.1:8080/pinsafe/AdminXML?xml=<AdminRequest secret="secret" version="3.4"><Report repository="local"><Disabled/></Report></AdminRequest>

Example output:

   <?xml version="1.0" ?> 
 - <AdminResponse>
 - <Report repository="local">
 - <Disabled>
   <User name="qwerty" /> 
   </Disabled>
   </Report>
   </AdminResponse>


Show Locked User Accounts

<Locked/>

This query will show which user accounts have the status disabled.

Example:

http://127.0.0.1:8080/pinsafe/AdminXML?xml=<AdminRequest secret="secret" version="3.4"><Report repository="local"><Locked/></Report></AdminRequest>

Example output:

   <?xml version="1.0" ?> 
 - <AdminResponse>
 - <Report repository="local">
 - <Locked>
   <User name="qwerty" /> 
   </Locked>
   </Report>
   </AdminResponse>


Agent-XML Errors

AgentXML request failed, error: The agent is not authorised to access the server.

An Agent-XML request is being made against the Swivel server but is not permitted to do so. If access shoul;d be allowed create an entry on the Swivel Administration Console under Server/Agents. If an entry exists verified the shared secret is the same on Swivel and the access device.