Agent-XML
From Swivel Knowledgebase Wiki
Contents |
Agent-XML Overview
PINsafe can authenticate users with 2 different protocols.
- RADIUS is a standards-based protocol, for further information see RADIUS How To Guide
- AgentXML is a proprietary PINsafe standard. Agent-XML allows greater control as it also allows Reporting, Admin and Helpdesk functionality.
PINsafe requirements
Configuring PINsafe to use Agent-XML Requests
PINsafe must be configured to allow an agent to communicate, details on how to permit an agent to communicate with the PINsafe server are here: Agents How to Guide
Repository and Agent configuration
AdminRequest only works with users in the repository with the same name as the corresponding Agent. The work around is to give the Repository exactly the same name as the Agent (or vice versa).
If you use HelpdeskRequest instead, you can specify a repository attribute on the Read element, but AdminRequest doesn't support this.
The reason for the distinction is that the AdminXML API was designed to support creation and manipulation of users from outside PINsafe. The ability to access users from other repositories was an added feature, hence the use of HelpdeskRequest, where the commands are largely read-only.
Agent-XML
The Agent-XML API is an XML based API used for integrating PINsafe with other applications.
There are 4 subsets of the API, that cover the following areas
Authentication, Change PIN, PIN Reset, Start Authentication Session, Request security Strings etc
Add new users, set user details (eg mobile phone number), synchronise a repository, delete users
Unlock user, send user new credentials, set user policies etc
Retrieving lists of idle users etc
All these APIs follow the structure described in this article.
Principles
The APIs are based around XML documents for both request and reply.
The basic idea is to build a document containing details of operation(s) to be performed and the user(s) on which they are to be performed, submit it to PINsafe via HTTP and PINsafe will reply with a document detailing which operations succeeded and which, if any, failed. All operations via the API will be logged in the standard PINsafe log.
Only authorised PINsafe Agents will be able to submit requests. This is in line with Agents used for authorisation. The API is case sensitive, the correct case shown in the included examples.
Requests are sent to PINsafe via an HTTP POST using http or https depending on the configuration of the PINsafe server. For appliances the default will be https over port 8080.
The requests are posted to the pinsafe context followed by AgentXML for the authentication API and AdminXML for the Admin, Helpdesk and reporting API.
For example http://<ip address>:8080/pinsafe/AgentXML?xml=<?xml version="1.0"?>
or
https://<ip address>:8080/pinsafe/AdminXML?xml=<?xml version="1.0"?>
Structure
The structure of a request that all API requests are contained within a request element. This request element specifies the type of request and also includes the shared secret for agent authentication.
e.g. an authentication request would be contained within an SASRequest tag
<?xml version="1.0" ?>
<SASRequest secret="MyAdminAgent" version="3.4">
.
.
</SASRequest>
Whereas an admin API request would be contained within an AdminRequest element.
<?xml version="1.0" ?>
<AdminRequest secret="MyAdminAgent" version="3.4">
.
.
</AdminRequest>
The responses from the PINsafe server are similarly contained within response tags eg
<?xml version="1.0" ?>
<SASResponse secret="MyAdminAgent" version="3.4">
.
.
</SASResponse>
and
<?xml version="1.0" ?>
<AdminResponse secret="MyAdminAgent" version="3.4">
.
.
</AdminResponse>
Within these elements for elements that specify the particular request. For details of these elements refer to the article relating to that part of the API.
Commands
Authentication for more information see: Authentication
<changePIN> : Change Users Credentials
<exists> : Does a user have an account.
<login> : Perfrom PINsafe authentication
<ping> : Ping PINsafe application
<reset> : Perform a PIN reset
<resetcode> : Request a PIN Reset code
<startsession> : Start an authentication session
<securitystrings> : Request a set of security strings
Helpdesk for more information see: Helpdesk functions
<reset> : Send user new credentials
<strings> : send dual channel security string(s) to user
<update> : Change user policies or credentials
Admin for more information see: Admin functions
<create> : create a new user and optionally set user details.
<delete> : delete a user.
<read> : read the details of a given user.
<reset> : Send user new credentials
<sync> : Synchronise with a repository
<update> : Change user policies, credentials, transports etc
Reporting for more information see: Reporting functions and Reporting Using Agent-XML How to Guide
<disabled> : Report on disabled users
<idle> : Report on idle users
<locked> : Report on locked users
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 PINsafe server but is not permitted to do so. If access should be allowed create an entry on the PINsafe Administration Console under Server/Agents. If an entry exists verified the shared secret is the same on PINsafe and the access device. See also Agents How to Guide
AgentXML request failed, error: The XML request sent from the agent was malformed.
The Agent XML request contains an error check the format. Spaces may also cause errors.
ADMIN_ERROR_UNSUPPORTED_VERSION
The agent version is incorrect.
https://127.0.0.1:8080/pinsafe/AdminXML?xml=<AdminRequest%20secret="secret"%20version="3.7"><Report%20repository="local"><Idle%20since="01-jul-2010"/></Report></AdminRequest>
PINsafe 3.7 should use 3.6 for the version.
https://127.0.0.1:8080/pinsafe/AdminXML?xml=<AdminRequest%20secret="secret"%20version="3.4"><Report%20repository="local"><Idle%20since="01-jul-2010"/></Report></AdminRequest>
| PINsafe Version | Agent-XML Version |
| 3.7 | 3.6 |
| 3.6 | 3.6 |
| 3.5 | 3.4 |
| 3.4 | 3.4 |
