The authenticate method performs the authentication of the session and returns a verdict that determines if SPS permits the connection to continue to the target server.
Example
def authenticate(self,
session_id,
protocol,
connection_name,
client_ip,
client_port,
key_value_pairs):
return {
'verdict': 'ACCEPT',
'additional_metadata': 'my_metadata',
'my_key': 'my_value',
}You must implement the authenticate method in the plugin.
|
|
TIP:
If you do not want to do anything in this method, include an empty method that returns the ACCEPT verdict. |
Example
def authenticate (self):
return {
'verdict': 'ACCEPT',
}In addition, no gateway authentication has been performed by the plugin if the authenticate method returns:
- None.
- The dict {'verdict': 'NONE'}.
Input arguments
The order of the arguments does not make a difference, only their names do. Every argument is optional.
-
session_id
Type: string Description: The unique identifier of the session.
cookie
Type: dictionary Description: The cookie returned by the previous hook in the session. If this is the first call for that session, it is initialized as an empty dictionary, otherwise it has the value returned by one of the previous calls in this particular AA plugin. You can use the cookie to maintain the state for each particular connection or to transfer information between the different methods of the plugin. For an example that transfers information in the cookie between two methods, see Examples.
-
session_cookie
Type: dictionary Description: You can use the session cookie to maintain global state between plugins for each particular connection. If this is the first call for that session, it is initialized as an empty dictionary, otherwise it has the value returned by a previous plugin hook in the session.
-
connection_name
Type: string Description: The name of the Connection policy that handles the client's connection request.
-
client_ip
Type: string Description: A string containing the IP address of the client.
-
client_port
Type: int Description: The port number of the client.
-
gateway_user
Type: string Description: Contains the gateway username of the client if already available (for example, if the user performed inband gateway authentication), otherwise its value is None.
-
key_value_pairs
Type: dictionary Description: A dictionary containing plugin-specific information (for example, it may include a token ID). This dictionary also contains any key-value pairs that the user specified. In the plugin, such fields are already parsed into separate key-value pairs. For details on how the user can provide such data during a connection, see "Integrating external authentication and authorization systems" in the Administration Guide.
-
protocol
Type: string Description: The protocol used in the connection that the plugin is currently processing. Enter one of the following values: rdp, ssh, telnet.
-
target_server
Type: string or None Description: Contains information about the target server if already available (for example, if the user performed inband gateway authentication), otherwise its value is None.
-
target_port
Type: integer or None Description: Contains information about the target port if already available (for example, if the user performed inband gateway authentication), otherwise its value is None.
-
target_username
Type: string or None Description: Contains information about the target username if already available (for example, if the user performed inband gateway authentication), otherwise its value is None.
Returned values
The method must return a dictionary with the following (required or optional) elements.
The required elements are:
-
verdict, which must contain one of the following returned values:
-
ACCEPT, which returns gateway_user and gateway_groups together.
-
NEEDINFO, which returns question.
- DENY
- NONE
-
The optional elements are:
- cookie
- session_cookie
- additional metadata
- gateway_user
- gateway_groups
- question
The elements in more detail:
-
verdict
Type: string Required: yes Description: Must contain one of the following values:
-
ACCEPT:The authentication was successful, the client can continue the connection
If the plugin returns both gateway_users and gateway_groups elements, it means that gateway authentication has been performed.
- DENY: Reject the connection.
- NEEDINFO: The authentication requires more information to be completed.
- NONE: No gateway authentication was performed by the plugin.
For example, the following sample code rejects the connection.
Example
return {'verdict': 'DENY'}-
cookie
Type: dictionary Required: no Description: The cookie returned by the previous hook in the session. If this is the first call for that session, it is initialized as an empty dictionary, otherwise it has the value returned by one of the previous calls in this particular AA plugin. You can use the cookie to maintain the state for each particular connection or to transfer information between the different methods of the plugin. For an example that transfers information in the cookie between two methods, see Examples.
-
session_cookie
Type: dictionary Required: no Description: You can use the session cookie to maintain global state between plugins for each particular connection. If this is the first call for that session, it is initialized as an empty dictionary, otherwise it has the value returned by a previous plugin hook in the session.
-
additional_metadata
Description: The value of this string will be stored in the Additional metadata column of the SPS connection database, and will be available on the SPS search interface.
-
gateway_user
Type: string Required: no -
gateway_groups
Type: list Required: no Description: Optionally, the plugin can return the gateway_user and gateway_groups values. SPS will only update the gateway username and gateway groups fields in the connection database if the plugin returns the gateway_user and gateway_groups values. The returned gateway_user and gateway_groups values override any such attributes already available on SPS about the connection (which means that channel policy evaluations will be affected), so make sure that the plugin uses the original values appropriately.
NOTE: If the plugin returns the gateway_user and gateway_groups values, you may have to configure an appropriate Usermapping Policy in the Connection Policy. If the plugin returns a gateway_user that is different from the remote user, the connection will fail without a Usermapping Policy. For details on Usermapping Policies, see "Configuring usermapping policies" in the Administration Guide.
For example, the following sample code accepts the connection and sets the gateway_user and gateway_groups fields. (Naturally, you should write the plugin code that actually retrieves these data from the third-party system.) For details, see Examples.
Example
return { 'verdict': 'ACCEPT', 'gateway_user': 'username-received-from-third-party', 'gateway_groups': [ 'usergroup1-received-from-third-party', 'usergroup2-received-from-third-party' ] } -
question
Type: tuple Required: no Description: A tuple that contains key-question pairs and optionally a third element to disable echoing. You can use it to request additional information from the client when using the NEEDINFO verdict in RDP, Telnet, and SSH connections. For example, the following sample code displays a prompt (in this case, Enter your token number) to the user. For details, see Examples.
Example
return { 'verdict': 'NEEDINFO', 'question': ('token', 'Enter your token number: ') }If the optional third element is True, the answer will not be echoed to the client.
TIP: Set the third element to True if the answer to the question is sensitive information (for example, a password).
Example
return { 'verdict': 'NEEDINFO', 'question': ('token', 'Enter your token number: ', True) }Note that in SPS version 4.3.0 and 4.3.1, question was a dictionary. Starting with version 4.3.2, it is a tuple.
-
Requesting more information from the client
To request additional information from the client (for example, a one-time password from a token, or a ticket ID), the authenticate method may return the NEEDINFO verdict and the question tuple containing key-question pairs. The questions are asked from the user in a protocol-specific way and the authenticate method is called again with a key_value_pairs argument containing the answers in key-answer pairs, where the key belongs to the corresponding question. Alternatively, you can also use the cookie to supply additional information to the plugin.