Ceptor Docs

Page tree
Skip to end of metadata
Go to start of metadata

Configuration

The agent gets its configuration from the configuration server - but it does need to be told how to connect to a config server, and what its own name is - this can be done in a couple of ways.

  • Programmatically
  • System Properties
  • Configuration file

Programmatically

You can set the properties programmatically by constructing a properties object and setting that on the agent before invoking Agent.getInstance() 

Properties p = new Properties();
p.setProperty("server.name", "webserver1");
p.setProperty("server.alias", "Application XYZ");
p.setProperty("config.servers", "loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false");
Agent.setProperties(p);

System Properties

You can set system properties to let the agent know its own name and the address of one or more configuration servers, e.g. by adding these arguments to the java command-line when starting a program 

-Dserver.name=webserver1 -Dconfig.servers=loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false


Configuration File

If properties are not provided programmatically or by system properties, the agent will look for a file called ptserver.properties in the classpath - it will look for it in 3 locations; /config/ptserver.properties, /ptserver.properties and ptserver.properties

The content of this file should look like this:

server.name=webserver1
server.alias=Application XYZ
config.servers=loadbalance:nios://localhost:21233?validateservercert=false;nios://localhost:21234?validateservercert=false


API

The application uses the interface dk.itp.security.passticket.IAgent, which it can obtain an implementation of, by calling dk.itp.security.passticket.Agent.getInstance(). The interface extends IPTServer has the following methods:

package dk.itp.security.passticket;

import java.io.IOException;
import java.io.Serializable;
import java.util.List;
import java.util.Properties;

import dk.itp.managed.service.client.INotificationListener;
import dk.itp.managed.service.client.NotificationReply;
import dk.itp.security.authorization.client.ACLEntry;
import dk.itp.security.authorization.client.GroupEntry;
import dk.itp.security.authorization.client.URLEntry;
import dk.itp.security.authorization.client.UserEntry;
import dk.itp.security.exception.ConfigurationException;
import dk.itp.statistics.Statistics;
import dk.portalprotect.geolocator.LocatorInfo;

/**
 * Interface to the passticket server - this interface is a clients only access to the
 * passticket server / session controller - the implementation is hidden in another class.
 * 
 * <pre>
 * PortalProtect - Security infrastructure
 * Copyright(c) 2001, IT Practice A/S, All rights reserved.
 * 
 * This source code is confidential.
 * </pre>
 */
public interface IPTServer {
	public static final String CHANNEL_UNKNOWN = "00";
	public static final String CHANNEL_HTTP = "01";
	public static final String CHANNEL_SSL = "02";
	public static final String CHANNEL_SCL = "03";
	public static final String CHANNEL_USERDEFINED = "04";

	public static final short PERMISSION_WRONG_CHANNEL_USE_HTTP = 1;
	public static final short PERMISSION_WRONG_CHANNEL_USE_SSL = 2;
	public static final short PERMISSION_WRONG_CHANNEL_USE_SCL = 3;
	public static final short PERMISSION_NOT_FOUND = 4;

	/**
	 * Returns the "current" configuration for the PT server agent.
	 * @return Properties configuration of the PT agent.
	 * @throws ConfigurationException If some error occurs while getting the configuration, this exception is thrown
	 */
	public Properties getConfiguration() throws ConfigurationException;

	/**
	 * Returns the configuration for the specified server.
	 * @param serverName Name of server to retrieve configuration for
	 * @return Properties configuration of the specified server.
	 * @throws ConfigurationException If some error occurs while getting the configuration, this exception is thrown
	 */
	public Properties getConfiguration(String serverName) throws ConfigurationException;

	/**
	 * Adds another listener that will be notified if user logs on or off
	 * @param listener The PTListener Listener
	 */
	public void addPTListener(PTListener listener);

	/**
	 * Changes the users password
	 * @param sessionID
	 * @param oldPassword
	 * @param newPassword
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void changePassword(String sessionID, String oldPassword, String newPassword) throws PTException;

	/**
	 * Checks a given acl (Access Control List)
	 * @param sessionID Session ID
	 * @param aclName ACL name to check
	 * @return true if check was ok, false if access was denied
	 * @throws AclNotFoundException This is thrown if no ACL was found with the specified name.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean checkPermission(String sessionID, String aclName) throws PTException;

	/**
	 * Checks a given acl (Access Control List)
	 * @param sessionID Session ID
	 * @param aclName ACL Name
	 * @param additionalData Additional data that might be required to do the permission check, such as data-based authorization
	 * @return true if check was ok, false if access was denied
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean checkPermission(String sessionID, String aclName, Object additionalData) throws PTException;

	/**
	 * Checks a given acl (Access Control List)
	 * @param sessionID Session ID
	 * @param identifier Identifier of the ACL - used to separate ACLs e.g. between applications, use null for default.
	 * @param aclName ACL Name
	 * @param additionalData Additional data that might be required to do the permission check, such as data-based authorization
	 * @return true if check was ok, false if access was denied
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean checkPermission(String sessionID, String identifier, String aclName, Object additionalData) throws PTException;

	/**
	 * Deletes a state variable from the session
	 * @param sessionID Session ID
	 * @param key Key to delete
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void deleteStateVariable(String sessionID, String key) throws PTException;

	/**
	 * Returns a specific ACL entry for the given identifier.
	 * @param aclName The name of the ACL to retrieve
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @throws PTException This is thrown if some error occurs.
	 */
	public ACLEntry getACL(String aclName, String identifier) throws PTException;

	/**
	 * Returns a specific Group entry for the given identifier.
	 *
	 * @param groupName The name of the group to retrieve
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @throws PTException This is thrown if some error occurs.
	 */
	public GroupEntry getGroup(String groupName, String identifier) throws PTException;

	/**
	 * Returns all known ACLs for the given identifier.
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @return ACLEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public ACLEntry[] getAvailableACLs(String identifier) throws PTException;

	/**
	 * Returns all known groups for the given identifier.
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @return GroupEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public GroupEntry[] getAvailableGroups(String identifier) throws PTException;

	/**
	 * Returns known users for the given criterias.<br>
	 * Note that this method is most suited for exposing known users to an administration interface, like weblogics portal administration.
	 * @param wildcard The wildcard to match, could be * or part of the username/id
	 * @param groupName If not null, searches for users within the specified group
	 * @param searchSpec Additional search parameters, can be used for limiting searches if not null
	 * @param maxReturns Maximum number of user entries to return
	 * @param identifier Either identifies the server name, or null for non-server specific
	 * @param authorizationType Type of authorization plugin, or 0 to use default
	 * @return UserEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public UserEntry[] getAvailableUsers(String wildcard, String groupName, String searchSpec, int maxReturns, String identifier, int authorizationType) throws PTException;

	/**
	 * Returns the type of this channel - see the CHANNEL_* constants
	 * @param sessionID Session ID
	 * @return String channel type behind session id (transaction)
	 */
	public String getChannelType(String sessionID);

	/**
	 * Returns the CICS password to use for a particular session ID
	 * @param sessionID Session ID
	 * @return String CICS password, behind user behind sessionid
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getCICSPassword(String sessionID) throws PTException;

	/**
	 * Returns the CICS userid to use for this session
	 * @param sessionID Session ID
	 * @return CICS user behind user behind session id 
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getCICSUser(String sessionID) throws PTException;

	/**
	 * Return the customer number, if this user is logged on
	 * @param sessionID Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getCustomerID(String sessionID) throws PTException;

	/**
	 * Return the agreement number, if this user is logged on
	 * @param sessionID Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getAgreementID(String sessionID) throws PTException;

	/**
	 * Returns the password (or null) for the user if he is logged on
	 * @param sessionID Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getPassword(String sessionID) throws PTException;

	/**
	 * Get a state variable from the session
	 * @param sessionID Session ID
	 * @param key Key to retrieve value for
	 * @return StateVariable
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getStateVariable(String sessionID, String key) throws PTException;

	/**
	 * Gets the list of state variable keys from the session
	 * @param sessionID Session ID
	 * @return Array of state variable keys
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String[] getStateVariableKeys(String sessionID) throws PTException;
	
	/**
	 * Returns the id of the user associated with the given session id
	 * @param sessionID Session ID
	 * @return user behind session id
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getUser(String sessionID) throws PTException;

	/**
	 * Returns the IP address that the user is believed to have.<br><b>Note:</b> This IP is the one that was used when the
	 * session was created, and if IP checking in the dispatcher is disabled the current request might or might not
	 * have another IP address. In this case, configure the dispatcher to forward the Users IP address in an HTTP
	 * header, and rely on this instead for every current request.
	 * 
	 * @param sessionID Session ID
	 * @return user IP address behind session id
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getUserIP(String sessionID) throws PTException;

	/**
	 * Returns the name of the user associated with the session, or null if the name is not available.
	 * @param sessionID Session ID
	 * @return user name behind sessionid
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getUserName(String sessionID) throws PTException;

	/**
	 * Returns true if this is an "internal" or intranet user, false if it is an internet user
	 * @param sessionID Session ID
	 * @return true is user behind sessionid is an 'internal' user, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isInternalUser(String sessionID) throws PTException;

	/**
	 * Checks to see if a user is logged or, or if he is anonymous
	 * @param sessionID Session ID
	 * @return true is user behind sessionid is logged on, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isLoggedOn(String sessionID) throws PTException;

	/**
	 * Gets the authentication level for a user
	 * @param sessionID Session ID
	 * @return The authentication level of the user, which is 0 if he is not logged in
	 * @throws PTException This is thrown if some error occurs.
	 */
	public int getAuthenticationLevel(String sessionID) throws PTException;

	/**
	 * Gets the authentication method for a user. The methods are in the <code>AuthTypes</code> interface.
	 * @param sessionID Session ID
	 * @return The authentication method of the user, which is 0 if he is not logged in.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public int getAuthenticationMethod(String sessionID) throws PTException;

	/**
	 * Returns true/false depending on wether a given session is valid
	 * @param sessionID Session ID
	 * @return boolean true if session id is valid, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isValid(String sessionID);

	/**
	 * The user associated with this session will be logged off, note that the session itself is not removed until removeSession is called.
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logoff(String sessionId) throws PTException;

	/**
	 * The user associated with this session will be logged off after a certain delay (specified on the server)
	 * If the session is still active within the delay timeout, the logoff will be cancelled, and the session will
	 * continue. It is meant to be used when switching between multiple domains, and in situations where automatic
	 * logoff will cause problems, like refreshing pages or resizing in netscape.
	 * 
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void delayedLogoff(String sessionId) throws PTException;

	/**
	 * Cancels a pending delayed logoff.
	 * 
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void cancelDelayedLogoff(String sessionId) throws PTException;

	/**
	 * Checks if this session is waiting for a delayed logoff
	 * 
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 * @return True if this session is about to be the victim of a delayed logoff, false otherwise
	 */
	public boolean isDelayedLogoff(String sessionId) throws PTException;

    /**
     * Issue new cryptograpic token for SSO to other systems. This request will be delegated to the specificed AuthenticationPlugin.
     * @param sessionId Session ID
     * @param authType
     * @throws PTException
     */
    public String newToken(String sessionId, int authType) throws PTException;

    /**
     * Issue new cryptograpic token for SSO to other systems. This request will be delegated to the specificed AuthenticationPlugin.
     * @param sessionid Session ID
     * @param authType
     * @param inputToken
     * @throws PTException
     */
    public String newToken(String sessionid, int authType, String inputToken) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType Authentication plugin type - @see AuthTypes
	 * @param user
	 * @param credentials
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, String user, Object credentials) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param credentials it is assumed that crendetials object contains userid and plugin knows how to 
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, Object credentials) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param user
	 * @param password
	 * @param newPassword
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, String user, Object password, Object newPassword) throws PTException;

	/**
	 * Logs a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param user
	 * @param password
	 * @param newPassword
	 * @param timeout Timeout in milliseconds for login to complete - set to 0 or -1 for default.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, int authType, String user, Object password, Object newPassword, long timeout) throws PTException;

	/**
	 * Logs a user on with the specified userid and password - the session must be created first
	 * @param sessionId Session ID
	 * @param user
	 * @param password
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, String user, String password) throws PTException;

	/**
	 * Logs a user on with the specified userid, password and new password - the session must be created first
	 * @param sessionId Session ID
	 * @param password
	 * @param newPassword
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, String user, String password, String newPassword) throws PTException;

	/**
	 * Logs a user on with the specified userid, password and new password - the session must be created first
	 * @param sessionId Session ID
	 * @param password
	 * @param newPassword
	 * @param timeout Timeout in milliseconds for login to complete - set to 0 or -1 for default.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void logon(String sessionId, String user, String password, String newPassword, long timeout) throws PTException;

	/**
	 * Provides support for confirmations (which usually means digital signatures) - a confirmation can just be
	 * a reauthentication, but usually it will be a digital signed request, which is then checked.
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param signtext
	 * @param credentials
	 * @return true if the confirmation succeeds, which means that either the digital signature was correct, or the reauthentication succeeded.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean confirm(String sessionId, int authType, String signtext, Object credentials) throws PTException;

	/**
	 * Provides support for confirmations (which usually means digital signatures) - a confirmation can just be
	 * a reauthentication, but usually it will be a digital signed request, which is then checked.
	 * @param sessionId
	 * @param authType @see AuthTypes
	 * @param credentials it is assumed that credentials object contains signtext and plugin knows how to get it.
	 * @return true if the confirmation succeeds, which means that either the digital signature was correct, or the reauthentication succeeded.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean confirm(String sessionId, int authType, Object credentials) throws PTException;

	/**
	 * This method measures the amount of time an operation took.
	 * The statistics is sent to the statistics/config server, which then creates nice graphics and
	 * creates summaries.
	 *
	 * @param name The name of the operation
	 * @param time The number of miliseconds it took
	 */
	public void measureStatistics(String name, long time);

	/**
	 * Creates a new session
	 * @param clientIP Client IP Address
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String newSession(String clientIP) throws PTException;

	/**
	 * Creates a new session, and lets the system know what session ID the user previously had
	 * @param clientIP Client IP Address
	 * @param oldSessionID Old session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String newSession(String clientIP, String oldSessionID) throws PTException;

	/**
	 * Creates a new session, with the specified session ID, and lets the system know what session ID the user previously had
	 * @param clientIP Client IP Address
	 * @param requestedSessionID The session ID this session should have. 
	 * @param oldSessionID Old session ID, if changing sessions e.g. between http and https
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String newSession(String clientIP, String requestedSessionID, String oldSessionID) throws PTException;

    /**
     * Creates a new session, with the specified session ID, and lets the system know what session ID the user previously had
     * @param clientIP Client IP Address
     * @param requestedSessionID The session ID this session should have. 
     * @param oldSessionID Old session ID, if changing sessions e.g. between http and https
     * @param segmentId Segment ID between 0 and 255 - the session will be created with the specified segment ID
     * @throws PTException This is thrown if some error occurs.
     */
    public String newSession(String clientIP, String requestedSessionID, String oldSessionID, short segmentId) throws PTException;
    
    /**
     * Creates a new session, with the specified session ID, and lets the system know what session ID the user previously had
     * @param clientIP Client IP Address
     * @param requestedSessionID The session ID this session should have. 
     * @param oldSessionID Old session ID, if changing sessions e.g. between http and https
     * @param segmentId Segment ID between 0 and 255 - the session will be created with the specified segment ID
     * @param clusterID Cluster ID of the session controller cluster to create the session in.
     * @throws PTException This is thrown if some error occurs.
     */
    public String newSession(String clientIP, String requestedSessionID, String oldSessionID, short segmentId, int clusterID) throws PTException;
    
	/**
	 * Removes a previously defined listener
	 * @param listener PTListener Listener
	 */
	public void removePTListener(PTListener listener);

	/**
	 * Removes a session from the list of active sessions
	 * @param sessionID The session ID to remove
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void removeSession(String sessionID) throws PTException;

	/**
	 * Sets a state variable that is kept in the session
	 * @param sessionID The session ID to lookup
	 * @param key The name of the state variable
	 * @param value The value of the state variable
	 * @param persistent True if the state variable should be considered persistent (saved to user-repository via authentication plugin, if possible)
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void setStateVariable(String sessionID, String key, String value, boolean persistent) throws PTException;

	/**
	 * Sets multiple state variables that is kept in the session
	 * @param sessionID The session ID to lookup
	 * @param keyValues A map of String keys with String values that are to be stored (or removed if the value is null)
	 * @param persistent True if the state variable should be considered persistent (saved to user-repository via authentication plugin, if possible)
	 * @throws PTException This is thrown if some error occurs.
	 * @since 6.0.1
	 */
	public void setStateVariable(String sessionID, Map<String,String> keyValues, boolean persistent) throws PTException;

	/**
	 * Check if the session/user is member of a group
	 * @param sessionID The session ID to lookup
	 * @param group The name of the group to check if the session or user belongs to
	 * @return True if the user is member og this group.
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isMemberOfGroup(String sessionID, String group) throws PTException;

	/**
	 * Checks if access to the specified URL is allowed for this session
	 * @param sessionID The session ID to lookup
	 * @param identifier The identifier of the server the user is trying to access
	 * @param url The URL to check
	 * @return boolean true if URL is allowed, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isURLAllowed(String sessionID, String identifier, String url) throws PTException;

	/**
	 * Checks if access to the specified URL is allowed for this session
	 * @param sessionID The session ID to lookup
	 * @param identifier The identifier of the server the user is trying to access
	 * @param url The URL to check
	 * @param method HTTP Method
	 * @return boolean true if URL is allowed, false if not
	 * @throws PTException This is thrown if some error occurs.
	 */
	public boolean isURLAllowed(String sessionID, String identifier, String method, String url) throws PTException;
	
	/**
	 * Retrieves the list of URL protection entries
	 * @param identifier
	 * @return URLEntry[]
	 * @throws PTException This is thrown if some error occurs.
	 */
	public URLEntry[] getProtectedURLs(String identifier) throws PTException;

	/**
	 * Returns an encrypted session cookie, which safely is sent to the target partner server, even
	 * in unencrypted form, since it is encrypted with the servers private key, and the target
	 * servers public key.
	 * 
	 * @param sessionID The session ID to convert to an encrypted cookie
	 * @param url The URL to redirect to at the server, once the cookie has arrived
	 * @param sourceName The name of the source (this server), the name is used to find the proper private key
	 * @param targetName The name of the target server this request is sent to, the name is used to find the correct public key
	 * @return The encrypted cookie contents
	 * @throws PTException This is thrown if some error occurs.
	 */
	public String getEncryptedSessionCookie(String sessionID, String url, String sourceName, String targetName) throws PTException;

	/**
	 * Decrypts a received encrypted session cookie
	 * 
	 * @param cookie The data to decrypt
	 * @param sourceName The name of the source (this server), the name is used to find the proper private key
	 * @param targetName The name of the target server this request is sent to, the name is used to find the correct public key
	 * @return The decrypted contents
	 * @throws PTException This is thrown if some error occurs.
	 */
	public DataExchangeCookie decryptEncryptedSessionCookie(String cookie, String sourceName, String targetName) throws PTException;

	/**
	 * Logs an event to the transaction log.<br>
	 * Note that this is only relevant when the user is logged on, and if the authentication plugin on the server supports
	 * transaction logs.
	 * 
	 * @param sessionID The session ID to lookup
	 * @param context The context this is logged in, which is a text identifying the business area that originated this.
	 * @param text The text to log
	 * @param signed If true, the request was probably signed, which means that it should also exist in a non-repudiation log.
	 * @throws PTException if the session cannot be found, or if no user is logged on.
	 */
	public void logToTransactionLog(String sessionID, String context, String text, boolean signed) throws PTException;

	/**
	 * Return the server name of this instance (found in PTServer.properties or in environment variable server.name
	 * 
	 * @return String server name, found in ptserver.properties
	 */
	public String getName();
	
	/**
	 * Adds a configuration listener that will be called if the configuration is set or changed.
	 *  
	 * @param listener The listener to add
	 */	
	public void addConfigListener(IConfigListener listener);
	
	/**
	 * Removes a previously added configuration listener
	 *  
	 * @param listener The listener to remove
	 */	
	public void removeConfigListener(IConfigListener listener);

	/**
	 * Adds a status text provider, which can provide an html formatted text snippet of status text that will be shown in PP's status
	 * for this server
	 * @param provider The IStatusTextProvider to add
	 */	
	public void addStatusTextProvider(IStatusTextProvider provider);
	
	/**
	 * Removes a previously added status text provider
	 * @param provider The provider to remove
	 */
	public void removeStatusTextProvider(IStatusTextProvider provider);
	
	/**
	 * Sets the specific status text provider for the specified action
	 * @param name Action name
	 * @param provider Status text provider
	 */
	public void addSpecificStatusTextProvider(String name, IStatusTextProvider provider);
		
	/**
	 * Can be used to obtain the statistics element used by this server
	 */
	public Statistics getStatistics();
	
	/**
	 * Return a list of ACL names that the specified user currently has
	 *  
	 * @param sessionID Session ID
	 * @return array of acl names
	 * @throws PTException
	 */
	public String[] getUserACLs(String sessionID) throws PTException;

	/**
	 * Return a list of group names that the specified user currently has
	 *  
	 * @param sessionID Session ID
	 * @return array of group names
	 * @throws PTException
	 */
	public String[] getUserGroups(String sessionID) throws PTException;

	/**
	 * Validates a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @param credentials it is assumed that crendentials object contains userid and plugin knows how to 
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void validate(String sessionId, int authType, Object credentials) throws PTException;

	/**
	 * Validates a user on with the specified authentication type userid and credentials - the session must be created first
	 * @param sessionId Session ID
	 * @param authType @see AuthTypes
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void validate(String sessionId, int authType, String user, Object password ) throws PTException;

	/**
	 * Validates a user on with the specified userid and password - the session must be created first
	 * @param sessionId Session ID
	 * @throws PTException This is thrown if some error occurs.
	 */
	public void validate(String sessionId, String user, String password) throws PTException;

	/**
	 * Generates a cross domain session object that can be transferred 
	 * @param sessionID
	 * @param fromDomain
	 * @param toDomain
	 * @return The cross domain session controller string
	 * @throws PTException
	 */
    public String getCrossDomainSession( String sessionID, String fromDomain, String toDomain ) throws PTException;
    
    /**
     * Asks the authentication plugin to execute an arbitrary command, on the authentication plugin that the user
     * within the session is currently logged into.
     * 
     * @param sessionID Session ID
     * @param name Name of command to execute, depends on the specific plugin.
     * @param input Input object (must be serializable)
     * @return Output object (must be serializable)
     * @throws PTException If an error occurs
     */
    public Object executeAuthpluginCommand(String sessionID, String name, Object input) throws PTException;

    /**
     * Asks the authentication plugin to execute an arbitrary command.
     * 
     * @param sessionID Session ID
     * @param name Name of command to execute, depends on the specific plugin.
     * @param authType Authentication plugin to send this to
     * @param input Input object (must be serializable)
     * @return Output object (must be serializable)
     * @throws PTException If an error occurs
     */
    public Object executeAuthpluginCommand(String sessionID, int authType, String name, Object input) throws PTException;

    /**
     * Returns the name of the agent which created the session, or null if not available.
     * 
     * @param sessionID Session ID
     * @return Name of agent which created the session, or null if not available.
     * @throws PTException If an error occurs
     */
    public String getNameOfCreatingAgent(String sessionID) throws PTException;
    
    /**
     * Persist the content of a session to a string which can be saved for later, and passed to restorePersistedSession
     * to restore the session contents to memory.
     * 
     * @param sessionID Session ID of the user requesting the persisting to be done
     * @param sessionIDToPersist Session ID to persist
     * 
     * @return The session ID of the persisted session.
     * @throws PTException If an error occurs
     */
    public String persistSession(String sessionID, String sessionIDToPersist) throws PTException;
    
    /**
     * Restores a previously persisted session to memory, from the persisted
     * @param sessionID Session ID of user restoring the session - restoring a session might require special permissions
     * @param persistedSessionData Session Data previously persisted
     * 
     * @return The session ID of the restored session.
     * @throws PTException If an error occurs
     */
    public String restorePersistedSession(String sessionID, String persistedSessionData) throws PTException;
    
    /**
     * Can be used to change the alias name of this agent - The alias is shown next to the server name in the Admin
     * GUI.
     * @param alias The new alias to use
     */
    public void setAlias(String alias);
    
    /**
     * Sends an async notification to one or more servers.
     * 
     * @param serverNamePattern Pattern matching one or more servers (e.g. *session*) or null to match any server.
     * @param serverTypePattern Pattern matching one or more server types, e.g. *agent) or null for any server
     * @param notificationName Notification name - a name for this notification event.
     * @param notificationObject Notification object, data sent along with the notification name
     */
    public void sendNotification(String serverNamePattern, String serverTypePattern, String notificationName, Serializable notificationObject) throws IOException;
    
    /**
     * Sends a synchronous notification to one or more servers, and expect a reply to it
     * 
     * @param serverNamePattern Pattern matching one or more servers (e.g. *session*) or null to match any server.
     * @param serverTypePattern Pattern matching one or more server types, e.g. *agent) or null for any server
     * @param notificationName Notification name - a name for this notification event.
     * @param notificationObject Notification object, data sent along with the notification name
     */
    public NotificationReply sendNotificationWithReply(String serverNamePattern, String serverTypePattern, String notificationName, Serializable notificationObject) throws IOException;
    
    /**
     * Adds a notification listener which will be called whenever a notification has arrived.
     * 
     * @param listener Listener to add
     */
    public void addNotificationListener(INotificationListener listener);
    
    /**
     * Removes a previously added notification listener.
     * 
     * @param listener Listener to remove
     */
    public void removeNotificationListener(INotificationListener listener);
    
    /**
     * Looks up GeoIP information based on an IP address. Note that the accuracy of the information depends on the
     * libraries purchased from MaxMind.
     * 
     * @param ip IP address to lookup
     * @return LocatorInfo Locator information
     * @throws PTException If an error occurs
     */
    public LocatorInfo lookupGeoIP(String ip) throws PTException;
    
    /**
     * Obtain a Session based upon a ticket, the ticket could be a previously issued OAuth ticket, or something
     * entirely different depending on your authentication plugin.
     * The ticket must be unique across authentication plugins, and the agent caches sessions based upon the ticket
     * so there are no penalties for repeated calls to this method with the same ticket id.
     * 
     * @param ticket Earlier issued ticket
	 * @param authType @see AuthTypes
	 * @param segmentId Segment ID of dispatcher, or 0
	 * @param clusterId Cluster ID, or 0 for default
	 * @param clientIP The client IP address
     * @return Session ID
     * @throws PTException If an error occurs
     */
    public String getSessionFromTicket(int authType, String ticket, short segmentId, short clusterId, String clientIP) throws PTException;
    
    /**
     * Obtain a Session based upon a ticket, the ticket could be a previously issued OAuth ticket, or something
     * entirely different depending on your authentication plugin.
     * The ticket must be unique across authentication plugins, and the agent caches sessions based upon the ticket
     * so there are no penalties for repeated calls to this method with the same ticket id, unless no session exists - in that case, every call will be a remote call to the sessioncontroller.
     * If the a session does not exist already, null will be returned - if a session exists, the ID of it will be returned.
     * 
     * @param ticket Earlier issued ticket for which a session exists, created using getSessionFromTicket(authType, ticket, segmentId, clusterId, clientIP)
	 * @param clusterId Cluster ID, or 0 for default
     * @return Session ID or null if no session for this ticket currently exists
     * @throws PTException If an error occurs
     */
    public String getSessionFromTicket(String ticket, int clusterId) throws PTException;
    
    /**
     * Get the ticket, e.g. OAuth Bearer token stored within the session, or null if no ticket exists.
     * 
     * @param sessionid Session ID
     * @throws PTException If an error occurs
     * @return Ticket or null if no ticket exists for the session
     */
    public String getTicketFromSession(String sessionid) throws PTException;
    
    /**
     * Returns a list of session IDs for which the supplied user is authenticated within. This can be used to find
     * active sessions for a given user and perform some action upon them. 
     * 
     * @param userid Userid to look for in list of authenticated sessions
     * @return List of session IDs where this user is authenticated
     * @throws PTException If an error occurs
     */
    public List<String> getSessionsWhereUserIsAuthenticated(String userid) throws PTException;


    /**
     * Updates the ticket within a session, changing the ticket to the new value
     * 
     * @param sessionid Session ID
     * @param ticket New ticket
     * @throws PTException If an error occurs
     */
    public void updateTicketInSession(String sessionid, String ticket) throws PTException;
}

  • No labels