https://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&feed=atom&action=historyAuthenticationAPI - Revision history2024-03-28T15:11:42ZRevision history for this page on the wikiMediaWiki 1.28.0https://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&diff=5426&oldid=prevRWithey: /* Token Challenge-Response */2021-07-06T10:57:20Z<p><span dir="auto"><span class="autocomment">Token Challenge-Response</span></span></p>
<table class="diff diff-contentalign-left" data-mw="interface">
<col class='diff-marker' />
<col class='diff-content' />
<col class='diff-marker' />
<col class='diff-content' />
<tr style='vertical-align: top;' lang='en'>
<td colspan='2' style="background-color: white; color:black; text-align: center;">← Older revision</td>
<td colspan='2' style="background-color: white; color:black; text-align: center;">Revision as of 10:57, 6 July 2021</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l417" >Line 417:</td>
<td colspan="2" class="diff-lineno">Line 417:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OcraChallenge>8765432</OcraChallenge></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OcraChallenge>8765432</OcraChallenge></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OcraResponse>12345678</OcraResponse></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OcraResponse>12345678</OcraResponse></div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>  </<del class="diffchange diffchange-inline">SASRequet</del>></div></td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>  </<ins class="diffchange diffchange-inline">SASRequest</ins>></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr>
</table>RWitheyhttps://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&diff=5425&oldid=prevRWithey: /* Token Synchonisation */2021-07-06T10:57:11Z<p><span dir="auto"><span class="autocomment">Token Synchonisation</span></span></p>
<table class="diff diff-contentalign-left" data-mw="interface">
<col class='diff-marker' />
<col class='diff-content' />
<col class='diff-marker' />
<col class='diff-content' />
<tr style='vertical-align: top;' lang='en'>
<td colspan='2' style="background-color: white; color:black; text-align: center;">← Older revision</td>
<td colspan='2' style="background-color: white; color:black; text-align: center;">Revision as of 10:57, 6 July 2021</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l401" >Line 401:</td>
<td colspan="2" class="diff-lineno">Line 401:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OTP1>481262</OTP1></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OTP1>481262</OTP1></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OTP2>579024</OTP2></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <OTP2>579024</OTP2></div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>  </<del class="diffchange diffchange-inline">SASRequet</del>></div></td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>  </<ins class="diffchange diffchange-inline">SASRequest</ins>></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr>
</table>RWitheyhttps://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&diff=5424&oldid=prevRWithey: /* User Exists By Attribute */2021-07-06T10:57:02Z<p><span dir="auto"><span class="autocomment">User Exists By Attribute</span></span></p>
<table class="diff diff-contentalign-left" data-mw="interface">
<col class='diff-marker' />
<col class='diff-content' />
<col class='diff-marker' />
<col class='diff-content' />
<tr style='vertical-align: top;' lang='en'>
<td colspan='2' style="background-color: white; color:black; text-align: center;">← Older revision</td>
<td colspan='2' style="background-color: white; color:black; text-align: center;">Revision as of 10:57, 6 July 2021</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l381" >Line 381:</td>
<td colspan="2" class="diff-lineno">Line 381:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Action>ExistsByAttribute</Action></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Action>ExistsByAttribute</Action></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Username>firstname.lastname@domain.com</Username></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Username>firstname.lastname@domain.com</Username></div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>  </<del class="diffchange diffchange-inline">SASRequet</del>></div></td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>  </<ins class="diffchange diffchange-inline">SASRequest</ins>></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <?xml version="1.0" ?></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <?xml version="1.0" ?></div></td></tr>
</table>RWitheyhttps://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&diff=5423&oldid=prevRWithey: /* User Exists */2021-07-06T10:56:50Z<p><span dir="auto"><span class="autocomment">User Exists</span></span></p>
<table class="diff diff-contentalign-left" data-mw="interface">
<col class='diff-marker' />
<col class='diff-content' />
<col class='diff-marker' />
<col class='diff-content' />
<tr style='vertical-align: top;' lang='en'>
<td colspan='2' style="background-color: white; color:black; text-align: center;">← Older revision</td>
<td colspan='2' style="background-color: white; color:black; text-align: center;">Revision as of 10:56, 6 July 2021</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l355" >Line 355:</td>
<td colspan="2" class="diff-lineno">Line 355:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Action>exists</Action></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Action>exists</Action></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Username>some_user</Username></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Username>some_user</Username></div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>  </<del class="diffchange diffchange-inline">SASRequet</del>></div></td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>  </<ins class="diffchange diffchange-inline">SASRequest</ins>></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>If the user exists a Pass is returned, if the user does not exist a Fail is sent back.</div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>If the user exists a Pass is returned, if the user does not exist a Fail is sent back.</div></td></tr>
</table>RWitheyhttps://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&diff=5422&oldid=prevRWithey: /* Reset */2021-07-06T10:56:35Z<p><span dir="auto"><span class="autocomment">Reset</span></span></p>
<table class="diff diff-contentalign-left" data-mw="interface">
<col class='diff-marker' />
<col class='diff-content' />
<col class='diff-marker' />
<col class='diff-content' />
<tr style='vertical-align: top;' lang='en'>
<td colspan='2' style="background-color: white; color:black; text-align: center;">← Older revision</td>
<td colspan='2' style="background-color: white; color:black; text-align: center;">Revision as of 10:56, 6 July 2021</td>
</tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l334" >Line 334:</td>
<td colspan="2" class="diff-lineno">Line 334:</td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Username>some_user</Username></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Username>some_user</Username></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Resetcode>87456hfiu7634</Resetcode>  </div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <Resetcode>87456hfiu7634</Resetcode>  </div></td></tr>
<tr><td class='diff-marker'>−</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>  </<del class="diffchange diffchange-inline">SASRequet</del>></div></td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>  </<ins class="diffchange diffchange-inline">SASRequest</ins>></div></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr>
<tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <?xml version="1.0" ?></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>  <?xml version="1.0" ?></div></td></tr>
</table>RWitheyhttps://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&diff=1851&oldid=prevAdmin: 1 revision imported2017-05-11T12:52:07Z<p>1 revision imported</p>
<table class="diff diff-contentalign-left" data-mw="interface">
<tr style='vertical-align: top;' lang='en'>
<td colspan='1' style="background-color: white; color:black; text-align: center;">← Older revision</td>
<td colspan='1' style="background-color: white; color:black; text-align: center;">Revision as of 12:52, 11 May 2017</td>
</tr><tr><td colspan='2' style='text-align: center;' lang='en'><div class="mw-diff-empty">(No difference)</div>
</td></tr></table>Adminhttps://kb.swivelsecure.com/w/index.php?title=AuthenticationAPI&diff=1850&oldid=prevAdmin at 10:10, 3 August 20152015-08-03T10:10:03Z<p></p>
<p><b>New page</b></p><div>{{Template:default}}<br />
{{Template:What}}<br />
<br />
The Swivel Authentication API (Agent-XML) is a means by which external application can make authentication requests to Swivel.<br />
<br />
The API is XML-Based and is a subset of the overall [[Agent-XML]] API.<br />
<br />
<br />
== Background ==<br />
<br />
All [[Agent-XML]] requests include a shared secret (with the exception of ping). In order for an authentication API to be acted upon by Swivel, the IP addressed and shared secret presented within the request must match that configured on the Swivel server.<br />
<br />
All requests also include a version number. This should be set according to the target version of Swivel:<br />
<br />
* 3.1 for all versions of Swivel from 3.1 - 3.3.<br />
* 3.4 for versions 3.4 and 3.5.<br />
* 3.6 for versions 3.6 onwards.<br />
<br />
(NOTE: the value of version is not actually checked, but the element must be present).<br />
<br />
Authentication requests must be sent via an HTTP Post to the Swivel server, to the AgentXML context.<br />
<br />
For example http://<ip address>:8080/pinsafe/AgentXML<br />
<br />
Note that for appliances this will be https by default. Agent XML requests are sent direct to the Swivel application on port 8080 and not via the proxy.<br />
<br />
There is a optional field called requestID. If this is included then it will be echoed back in the corresponding response.<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<RequestID>1000</RequestID><br />
.<br />
.<br />
</SASRequest><br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<RequestID>1000</RequestID><br />
.<br />
.<br />
</SASResponse><br />
<br />
== Starting a Session ==<br />
<br />
Some Swivel authentication modes are session based. <br />
<br />
In this mode an Agent must start a session for a user and then request the security string for that session, either via an Image ([[Single Channel How To Guide Single Channel]], eg [[TURing]]) or a message( [[Dual Channel]], eg [[SMS]] message).<br />
<br />
When an agent starts a session an ID for that session is returned. This session ID can then be used to request the string either via an image<br />
<br />
<nowiki><br />
img src = http://pinsafe:8080/pinsafe/SCImage?sessionid=3bfwuefi37tr<br />
</nowiki><br />
<br />
or via a message<br />
<br />
<nowiki><br />
img src = http://pinsafe:8080/pinsafe/DCMessage?sessionid=3bfwuefi37tr<br />
</nowiki><br />
<br />
The a session start message is as follows<br />
<br />
The Agent gathers the user's username and sends the following XML Request to the Swivel Server:<br />
<br />
<br />
The above XML Request will start a session on the Swivel Server, which will respond with the following XML:<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>sessionstart</Action><br />
<Username>some_user</Username><br />
</SASRequest><br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
<SessionID>c7379ef1b41f90a4900548a75e13f62a</SessionID><br />
</SASResponse><br />
<br />
If for any reason the session start fails a fail message will be return along with the reason for the failure, for example<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>FAIL</Result><br />
<Reason>AGENT_ERROR_NO_USER_FOUND</Reason><br />
</SASResponse><br />
<br />
A list of possible errors is shown a in the Error Messages Section below.<br />
<br />
== Authentication ==<br />
<br />
The following example shows how to perform a login using the Agent XML Interface. The login request is used for both Single Channel and Dual Channel logins. <br />
<br />
The Agent gathers the user's username,optional password, One-Time-Code and sends the following XML Request to the Swivel Server:<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>login</Action><br />
<Username>some_user</Username><br />
<Password>password</Password><br />
<OTC>1234</OTC><br />
</SASRequest><br />
<br />
If the authentication request is successful the server will respond with the following XML:<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
</SASResponse><br />
<br />
If there are any problems the Result element will contain a FAIL and if an error has occurred there will be an Error element, for example:<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>FAIL</Result><br />
<Error> AGENT_ERROR_NO_SECURITY_STRINGS</Error><br />
</SASResponse><br />
<br />
If the Result element’s value is FAIL and there is no Error value the user has simply failed to authenticate successfully, ie supplied incorrect credentials.<br />
<br />
=== Authentication By Attribute===<br />
The standard login request must contain the users Swivel Username.<br />
<br />
However some services may require another atttribute to the used, eg email address. There is a separate API call to handle this case whereby the agent provides the attribute name and attribute value is part of the authentication request.<br />
<br />
""Note that the Swivel Authentication Platfrom will need to be configured to allow other attributes to be used in this way""<br />
<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>login</Action><br />
<Username>some_user@domain.com</Username><br />
<Attribute>email</Attribute><br />
<Password>password</Password><br />
<OTC>1234</OTC><br />
</SASRequest><br />
<br />
<br />
<br />
=== Warnings ===<br />
<br />
A successful authentication request can include warnings, these usually refer to the fact that a PIN needs to be change due to a policy that is set or due to the fact that it will soon expire. These warnings can be used by the agent to re-direct the user to a change-PIN page after authentication.<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
<Warning>AGENT_WARN_CHANGE_PIN</Warning><br />
</SASResponse><br />
<br />
<br />
=== Check Password ===<br />
from Version 3.10<br />
<br />
It is possible to use Agent XML to check a users password. This will either be the user's Swivel password or their repository password depending on the policy set for this agent.<br />
The attempt will be logged but an incorrect password will not be treated as a failed authentication attempt<br />
<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>checkpassword</Action><br />
<Username>some_user</Username><br />
<Password>password</Password><br />
</SASRequest><br />
<br />
Reponse is a simple pass or fail.<br />
<br />
==Change PIN ==<br />
<br />
Change PIN is very similar to a login request with the inclusion of the user’s new password and new PIN, sent has a new One-Time-Code. The Agent gathers the username, existing password, new password, existing One-Time-Code, and new One-Time-Code. To start the change PIN process the following XML is sent to the Swivel Server:<br />
<br />
If no password is being used the <Password> and <NewPassword> elements should be empty.<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>changepin</Action><br />
<Username>some_user</Username><br />
<Password>password</Password><br />
<NewPassword>newpassword</NewPassword><br />
<OTC>1234</OTC><br />
<NewOTC>4321</NewOTC><br />
</SASRequest><br />
<br />
If the request is successful the Swivel Server will change the user's password and PIN, and will respond with a PASS in the Result element:<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
</SASResponse><br />
<br />
The change pin can fail for a number of reasons. If the password and one-time code submitted are incorrect the response will just indicate a failure. If the current credentials were correct, then the pin change may fail because the new PIN does not confirm to PIN composition policies, such as not allowing sequences such as 1234.<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>FAIL</Result><br />
<Error>AGENT_ERROR_PIN_COMPOSITION</Error><br />
</SASResponse><br />
<br />
== Security Strings ==<br />
<br />
This API is also used by a midlet to request a batch of security strings.<br />
<br />
For Versions of Swivel prior to Version 3.8 the format is as follows<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Action>securitystrings</Action><br />
<Username>some_user</Username><br />
</SASRequest><br />
<br />
For Version 3.8 the format is <br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Action>SecurityStrings</Action><br />
<Id>client-id</Id><br />
</SASRequest><br />
<br />
In this version the mobile client needs to provide a unique user-id in order to receive security strings. The mobile client obtains this client-id by completing the provision process described below.<br />
<br />
The response is a set of 99 security strings<br />
<br />
== Mobile Client Provision (Version 3.8) ==<br />
<br />
In order for a mobile client to download security strings it needs to obtain a unique client-id. This is obtained by submitting a provision code to Swivel. This provision code will be sent to the user, usually via a text message.<br />
<br />
There is an API call that will request a provision code to be sent to the user. (Or this can be done via the admin console)<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Action>provisioncode</Action><br />
<Username>some_user</Username><br />
</SASRequest><br />
<br />
<br />
If successful a Pass packet will be returned and a provision code will be sent to the end-user. <br />
<br />
If not successful a FAIL will be returned along with any error.<br />
<br />
The user will then enter the provision code. The provision code will then be presented to Swivel by the client as <br />
<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Action>provision</Action><br />
<ProvisionCode>code</ProvisionCode><br />
<Username>username</Username><br />
</SASRequest><br />
<br />
If the code is correct Swivel will return a PASS along with the clients Unique Client ID (UCID)<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
<Id>id</Id><br />
</SASResponse><br />
<br />
If there is a problem, then an error will be returned<br />
<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>FAIL</Result><br />
<Error>AGENT_NO_SESSION</Error><br />
</SASResponse><br />
<br />
== Ping ==<br />
<br />
You can use a ping command to test that the Swivel application is available. The response is a pass response.<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Action>ping</Action><br />
</SASRequest><br />
<br />
The response being<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
</SASResponse><br />
<br />
== Reset ==<br />
<br />
If it is enabled on the Swivel server, a user can request a reset code to be sent to them, then of they enter that reset code, they are sent a new PIN (Note: the user must have a transport to receive the new PIN).<br />
<br />
Two API commands support this, <Resetcode> that sends the code to the user and then <Reset> that submits the reset code to Swivel.<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>resetcode</Action><br />
<Username>some_user</Username><br />
</SASRequest><br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
</SASResponse><br />
<br />
This sends the reset code to the user. The user enters the code on a form on the agent and submits.<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>reset</Action><br />
<Username>some_user</Username><br />
<Resetcode>87456hfiu7634</Resetcode> <br />
</SASRequet><br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
</SASResponse><br />
<br />
<br />
If the reset code is entered correctly then the user is sent a new set of credentials.<br />
<br />
== User Exists ==<br />
<br />
This method can be used as a pre-authentication check to see if an account exist on Swivel.<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>exists</Action><br />
<Username>some_user</Username><br />
</SASRequet><br />
<br />
If the user exists a Pass is returned, if the user does not exist a Fail is sent back.<br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
</SASResponse><br />
<br />
== User Exists By Attribute==<br />
<br />
A variation of the above method allows the query to pass in an attribute, eg email address.<br />
<br />
The response to the query will be the name of the attribute that matched if the user could be found<br />
<br />
Or fail if not match (or multiple matches) were found<br />
<br />
eg<br />
<br />
<?xml version="1.0" ?><br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Action>ExistsByAttribute</Action><br />
<Username>firstname.lastname@domain.com</Username><br />
</SASRequet><br />
<br />
<?xml version="1.0" ?><br />
<SASResponse><br />
<Version>3.6</Version><br />
<Result>PASS</Result><br />
<AtttributeName>email</AttributeName><br />
</SASResponse><br />
<br />
== Token Synchonisation ==<br />
<br />
This API calls attempts to synchronise a user's token but submitting two consecutive OTPs<br />
<br />
<SASRequest><br />
<Version>3.6</Version><br />
<Secret>shared_secret</Secret><br />
<Username>tokenuser</Username><br />
<Action>OathSync</Action><br />
<OTP1>481262</OTP1><br />
<OTP2>579024</OTP2><br />
</SASRequet><br />
<br />
<br />
If the request is successful a PASS message will be returned. If not the possible failures are SYNC_FAILURE (meaning the OTPs were not valid) or OATH_TOKEN_NOT_FOUND (meaning the user does not have a token.<br />
<br />
== Token Challenge-Response ==<br />
<br />
This API call validates the users response to an OCRA challenge. (Where the user enters the challenge on the OCRA token keypad)<br />
<br />
<SASRequest><br />
<Version>3.1</Version><br />
<Secret>shared_secret</Secret><br />
<Username>tokenuser</Username><br />
<Action>OcraVerify</Action><br />
<OcraChallenge>8765432</OcraChallenge><br />
<OcraResponse>12345678</OcraResponse><br />
</SASRequet><br />
<br />
<br />
If the respinse is verfied a PASS message will be returned. If not an OCRA_RESPONSE_FAILURE error will be returned<br />
<br />
== Command Examples ==<br />
<br />
Below is the example of a ping command<br />
<br />
<nowiki><br />
http://127.0.0.1:8080/pinsafe/AgentXML?xml=<?xml version="1.0"?><SASRequest><Version>3.1</Version><Action>ping</Action></SASRequest><br />
</nowiki><br />
<br />
Expected output<br />
<br />
<?xml version="1.0" ?> <br />
- <SASResponse><br />
<Version>3.6</Version> <br />
<RequestID /> <br />
<Result>PASS</Result> <br />
</SASResponse><br />
<br />
<br />
Below is the example of a session request command<br />
<br />
<nowiki><br />
http://127.0.0.1:8080/pinsafe/AgentXML?xml=<?xml version="1.0" ?><SASRequest><Version>3.6</Version><Secret>secret</Secret><Action>sessionstart</Action><Username>graham</Username></SASRequest><br />
</nowiki><br />
<br />
Expected output<br />
<br />
<?xml version="1.0" ?> <br />
- <SASResponse><br />
<Version>3.6</Version> <br />
<RequestID /> <br />
<Result>PASS</Result> <br />
<SessionID>f853792503f2e83f3ff55f693f631537</SessionID> <br />
</SASResponse><br />
<br />
Swivel log<br />
<br />
local:Session started for user: graham.<br />
<br />
<br />
Below is the example of a login command<br />
<br />
<nowiki><br />
http://127.0.0.1:8080/pinsafe/AgentXML?xml=<?xml version="1.0" ?><SASRequest><Version>3.6</Version><Secret>secret</Secret><Action>login</Action><Username>graham</Username><Password></Password><OTC>8459</OTC></SASRequest><br />
</nowiki><br />
<br />
Expected output<br />
<br />
<?xml version="1.0" ?> <br />
- <SASResponse><br />
<Version>3.6</Version> <br />
<RequestID /> <br />
<Result>PASS</Result> <br />
<Channel>SINGLE</Channel> <br />
</SASResponse><br />
<br />
Swivel log<br />
<br />
local:Login successful for user: graham.<br />
<br />
<br />
Below is the example of a changepin command<br />
<br />
<nowiki><br />
http://127.0.0.1:8080/pinsafe/AgentXML?xml=<?xml version="1.0"?><SASRequest><Version>3.6</Version><Secret>secret</Secret><Action>changepin</Action><Username>graham</Username><Password></Password><NewPassword></NewPassword><OTC>3085</OTC><NewOTC>4967</NewOTC></SASRequest><br />
</nowiki><br />
<br />
Expected output<br />
<br />
<?xml version="1.0" ?> <br />
- <SASResponse><br />
<Version>3.6</Version> <br />
<RequestID /> <br />
<Result>PASS</Result> <br />
<Channel>SINGLE</Channel> <br />
</SASResponse><br />
<br />
Swivel log<br />
<br />
local:Change PIN successful for user: graham.<br />
<br />
<br />
Below is the example of a resetcode (reset PIN) request command<br />
<br />
<nowiki><br />
http://127.0.0.1:8080/pinsafe/AgentXML?xml=<?xml version="1.0"?><SASRequest><Version>3.6</Version><Secret>secret</Secret><Action>resetcode</Action><Username>graham</Username></SASRequest><br />
</nowiki><br />
<br />
Expected output<br />
<br />
<?xml version="1.0" ?> <br />
- <SASResponse><br />
<Version>3.6</Version> <br />
<RequestID /> <br />
<Result>PASS</Result> <br />
</SASResponse><br />
<br />
Swivel log<br />
<br />
local:Self-reset code request successful for user: graham.<br />
<br />
<br />
Below is the example of a reset (reset PIN) command<br />
<br />
<nowiki><br />
http://127.0.0.1:8080/pinsafe/AgentXML?xml=<?xml version="1.0"?><SASRequest><Version>3.6</Version><Secret>secret</Secret><Action>reset</Action><Username>graham</Username><Resetcode>6975012843</Resetcode></SASRequest><br />
</nowiki><br />
<br />
Expected output<br />
<br />
<?xml version="1.0" ?> <br />
- <SASResponse><br />
<Version>3.6</Version> <br />
<RequestID /> <br />
<Result>PASS</Result> <br />
</SASResponse><br />
<br />
Swivel log<br />
<br />
local:Self-reset successful for user: graham.<br />
<br />
== Error and Warning Messages ==<br />
<br />
{| class="prettytable"<br />
| Error<br />
| Meaning<br />
|-<br />
| AGENT_ERROR_AGENT_ACCESS<br />
|The user is not in the correct group to use this agent<br />
|-<br />
| AGENT_ERROR_ACTION_TYPE <br />
|The XML Request sent by the Agent did not contain an unrecognised Action element.<br />
|-<br />
| AGENT_ERROR_GENERAL<br />
| An unspecified error occurred.<br />
|-<br />
| AGENT_ERROR_NO_ACTION<br />
|The XML Request sent by the Agent did not contain an Action element.<br />
|-<br />
| AGENT_ERROR_NO_AUTH<br />
| Swivel does not know how to authenticate this user<br />
|-<br />
| AGENT_CANNOT_CHANGE_REPOSITORY_PASSWORD<br />
| A pin change failed as the two different passwords were submitted but the agent was configured to use repository passwords<br />
|-<br />
| AGENT_ERROR_NO_CHANGE<br />
| A pin change failed as the credentials submitted were the same<br />
|-<br />
| AGENT_ERROR_NO_PIN<br />
| The user has no PIN set<br />
|-<br />
| AGENT_ERROR_AUTH_METHOD_UNSUPPORTED<br />
| This agent cannot authenticate a user using this method, eg attempting a single channel authentication on a dual-channel only agent<br />
|-<br />
|AGENT_ERROR_NO_OTC<br />
AGENT_ERROR_BAD_OTC<br />
| One-time code was missing or malformed<br />
|-<br />
| AGENT_ERROR_SESSION<br />
| A Session could not be created by the Swivel server. Please try again at a later time.<br />
|-<br />
| AGENT_ERROR_UNAUTHORIZED<br />
| The Agent is not authorised to use the Swivel server.<br />
|-<br />
| AGENT_ERROR_USERNAME<br />
| The Username element in the XML Request sent by the Agent contained invalid characters.<br />
|-<br />
| AGENT_ERROR_XML <br />
|The XML Request sent by the Agent to the Swivel server was malformed.<br />
|-<br />
| AGENT_WARN_CHANGE_PIN<br />
| The user is required to change PIN before their next login<br />
|-<br />
| AGENT_WARN_PIN_EXPIRY<br />
| The users PIN will shortly expire, ie within the period sepcified by the change pin warning on the Swivel server.<br />
|-<br />
<br />
|}</div>Admin