Difference between revisions of "SwivelAuthClient Documentation"
From Swivel Knowledgebase
(→Overview) |
m (1 revision imported) |
(No difference)
| |
Latest revision as of 12:52, 11 May 2017
Contents
Overview
Class name: SwivelAuthClient
Namespace: swivelsecure.client
This class provides convenient access to the authentication service of a Swivel server. It is essentially a wrapper around the XML-based AgentXML API.
Typically, when using this class within an ASP.Net application, you can use the default constructor to create a new instance of this class. This will read settings from web.config, which should have been previously configured as described in the overview document.
Constructors
SwivelAuthClient()
Constructor which reads settings from web.config
SwivelAuthClient(SwivelSettings settings)
Constructor with pre-defined settings settings: The settings for this client
Methods
bool Ping()
Tests basic PINsafe functionality. Doesn't check if the caller is a valid PINsafe Agent. Returns True if PINsafe is available and working.
bool UserExists(string username)
Check whether a user exists or not. username: The username to check Returns True if the user exists in the Swivel database
string StartSession(string username)
Starts a new single channel session with the PINsafe server. The returned session ID can subsequently be used to generate a TURing image within a limited time period. Depending on the Swivel server settings, it is possible to request a TURing image for the user directly, without starting a session explicitly. username: The username for the user. Returns Session ID for the started session, or an empty string if an error occurred or the user does not exist.
bool Login(string username, string password, string OTC)
Perform an authentication with the Swivel server. username: The username of the user. password: The Swivel password of the user. This will typically be an empty string (not null), unless you have explicitly set a Swivel password. OTC: The user's one-time code. Returns True if authentication succeeded.
bool ChangePin(string username, string password, string newPassword, string OTC, string newOTC)
Perform a PIN or password change with the Swivel server.
username: The username of the user.
password: The current Swivel password of the user.
This will typically be an empty string (not null), unless you have explicitly set a Swivel password.
newPassword: The new password. Empty string if the password is not required.
OTC: The user's one-time code, based on the current PIN.
Note that this is the OTC according to the PINsafe protocol, NOT the PIN.
newOTC: The one-time code, based on the new PIN. This should use the same security string as the old one-time code.
string SendRequestXml(string xml)
Send an arbitrary AgentXML request to the Swivel server. This is provided to allow for future expansion. Typically, you will not need to use this method directly. xml: The XML request, according to the AgentXML protocol. Returns The XML response from the server, or an empty string if an error occurred
Image GetImage(string sessionID, string username, out int status)
Request a TURing image from PINsafe. The image can be requested using a previously-requested session ID or a username. Using session ID is more secure, since session IDs can only be requested by valid Agents. However, if image request by username is enabled in PINsafe, direct request by username is quicker, as only one request is required. sessionID: A session ID previously requested from the Swivel server (can be null) username: The username for which the image is to be generated (ignored if sessionID is not null or empty) status: Returns the HTTP status code returned by the Swivel server Returns A TURing image for the specified session ID or username as a System.Drawing.Image object. Typically, this method must be called from a dedicated aspx file, which is specified as the src attribute of an img object. The example client gives an example of this in Image.aspx and Image.aspx.cs.
Image GetMessage(string sessionID, string username, out int status)
Request an on-demand security string from PINsafe. The message can be requested using a previously-requested session ID or a username. Request by session ID is only valid if on-demand authentication is enabled in PINsafe. In this case, the security string is only valid for a limited time. If on-demand delivery is enabled, the security string is valid indefinitely, but must be requested by username. Using session ID is more secure, since session IDs can only be requested by valid Agents. However, if image request by username is enabled in PINsafe, direct request by username is quicker, as only one request is required. sessionID: A session ID previously requested from the Swivel server (can be null) username: The username for which the image is to be generated (ignored if sessionID is not null or empty) status: Returns the HTTP status code returned by the Swivel server Returns An image with the word "CONFIRMED" (the message can be altered). As for GetImage, this method is typically called from a dedicated aspx file. An example of this is not given, but the GetImage example can easily be altered to use GetMessage.
Properties
Most of the properties here are read-only, and they simply return the value found in the loaded settings. Exceptions to this are noted.
bool SSL
True if HTTPS should be used to communicate with Swivel Server, false if HTTP should be used. (Note that the naming is inconsistent with the corresponding SwivelSettings property).
string Server
The host name or IP address of the Swivel Server.
int Port
The port used by the Swivel Server.
string Context
The Swivel server context.
string Secret
The shared secret used when communicating with the Swivel Server.
bool AcceptSelfSigned
True if SSL certificate errors should be ignored when communicating with the Swivel Server.
bool AllowNonPINsafeUsers
True if usernames not recognised by Swivel server should be authenticated automatically. If false, unknown users will be rejected.
string Address
The URL of the servlet used to access the Swivel server for AgentXML calls. This is build on-the-fly from the settings, with "/AgentXML" appended.
string Error
The error message returned by the last request to the Swivel server. Can be set manually.
string[] Warnings
An array of warnings returned by the last request to the Swivel server. Typically this indicates whether a PIN change is required soon.
string Request
The last XML request sent to the Swivel server.
string Response
The last XML response received from the Swivel server.
