Password Exit

DLL Interface

1. The Connect:Direct’s Password Exit logic will call the ‘GetPassword’ method of the user supplied Password Exit DLL to obtain the password for the user. Following is the Typedef for GetPassword Function call:

   typedef int (*PFNGETPASSWORD)(GET_PASSWORD_REQUEST_T*, GET_PASSWORD_REPLY_T*);

2. Connect:Direct calls the Windows API ‘LoadLibrary’ to load the user supplied Password Exit DLL and Windows API ‘GetProcAddress’ to obtain the GetPassword function’s pointer in the user supplied Password Exit DLL. The request and reply structure are as follows:
   Get Password Request version 1- The request structure "GET_PASSWORD_REQUEST_T" contains :

   typedef struct get_password_request
   		{
   			Int64 version;				
   			char  applicationID[MAX_APPL_NAME];	
   			char  policyID[MAX_POLICY_NAME];		
   			char  userID[MAX_USER_NAME];		
   		} GET_PASSWORD_REQUEST_T;
   

   Get Password Request version 2- The request structure "GET_PASSWORD_REQUEST_T" contains :

   typedef struct get_password_request
   		{
   			int   version;
   			char  applicationID[MAX_APPL_NAME];
   			char  policyID[MAX_POLICY_NAME];
   			char  userID[MAX_USER_NAME];
   			char  url[MAX_NODE_NAME];
   			ISPSocket* spSocket;
   		} GET_PASSWORD_REQUEST_T;
   
   	  typedef int (*PFNRESETCACHE)();
   	  typedef int (*PFNGETEXITVERSION)();
   

   In a V2 DLL interface, the DLL is loaded one time into memory.  The change supports using a cache to improve performance.  The GetExitVersion export function is called by each SMGR prior to calling the GetPassword API.  If the password exit is V2 or later, the URL and SPSocket parameters are passed in the password request structure.  If the ResetCache export functions exists, it is called to clear the cache when a logon fails.
   
   Request structure fields contain :

   Parameter Name	Description	Valid Values
   Version	64bit number	If the Password Exit DLL does not export a GetExitVersion API, the version is set to ‘1’ to indicate a version 1 password exit. If the Password Exit DLL exports a GetExitVersion API, the version is set to ‘2’ to indicate a version 2 password exit.  In this case, ISPSocket and URL are valid.
   applicationID	Character string null terminated (Any valid ascii characters).	128 bytes in length maximum (127 bytes of data + null terminator). This is the password.exit.appl.id field in initparms.
   policyID	Character string null terminated (Any valid ascii characters).	128 bytes in length maximum (127 bytes of data + null terminator). This is the password.exit.policy.id field in initparms.
   userID	Character string null terminated (Any valid ascii characters).	128 bytes in length maximum (127 bytes of data + null terminator). This is the User Id for which we need the password.
   url	Character string null terminated. Standard URL format.	256 bytes in length maximum. This is an URL for the password exit to use with external services. This is the password.exit.url field in initparms. Note: The parameter is not passed to V1 Password Exits.
   ISPSocket	An interface providing secure socket access.	Before calling GetPassword, the SMGR creates an SPSocket instance. This feature provides a minimal secure socket configured using Secure+. A new Secure+ record named PswdExit specifies the security configuration for all SPSocket connections. See ISPSocket.h for details, located in the Server Samples Shared folder. Note: The parameter is not passed to V1 Password Exits

   Get Password Reply- The request structure GET_PASSWORD_REPLY_T contains:
   

   typedef struct get_password_reply
   		{
   			Int64 version;				
   			Int64 status;					
   			char  text_status[MAX_TXT_LEN];		
   			char  userID[MAX_USER_NAME];		
   			char  password[MAX_PASSWORD_LEN];		
   		} GET_PASSWORD_REPLY_T;
   

   Reply structure fields contain:

   Parameter Name	Description	Valid Values
   Version	64bit number	Value is always ‘1’. (Will increment if the request structure changes)
   status	64bit number (Any valid numeric value) used as the return code returned by the Password Exit DLL.	A value of 0 (zero) indicates the Password Exit successfully supplied the password for the requested user.
   text_status	Character string null terminated (Any valid ascii characters) 256 bytes in length maximum (255 bytes of data + null terminator) This is string which contains the result of the GetPassword request. It is intended to be a verbose success or error message returned by the Password Exit DLL.
   userID	Character string null terminated (Any valid ascii characters) 256 bytes in length maximum (255 bytes of data + null terminator) This is the User Id for which the password request is received.
   password	Character string null terminated (Any valid ascii characters) 256 bytes in length maximum (255 bytes of data + null terminator) This is the requested password for the User Id returned by the Password Exit DLL.

Sample Password Exit DLL

Sample CyberArk Password Exit DLL

A sample CyberArk Password Exit DLL is provided in the Server/Samples/CyberarkExit directory. This exit can be used to retrieve passwords from a CyberArk password vault using the CyberArk Central Credential Provider (CCP) service.

Central Credential Provider (CCP): A Webservice hosted on a Windows IIS server that can be queried via a REST API.

The CyberArk Exit project is provided in the Server/Samples/CyberArkExit directory and can be used to enhance or create your own.

CyberArkExit.sln: Visual Studio Solution file. Open this file in Visual Studio 2019 to build the CyberArkExit DLL.

PswdExit.h/cpp: Source file for the sample Password Exit DLL.

CyberArk Configuration Steps

Step 1: Configure Initialization parameters/miscellaneous parameters.

Troubleshooting:

The CyberArk Exit logs messages to the Connect:Direct SMGR trace file.

04/08 17:46:50.309270 00009C24 SM   | | | | | | PswdExit: URL target:
 /AIMWebService/api/Accounts?Safe=Cyberark_Accounts&Object=ari48013&AppID=applid&PolicyID=polid

04/08 17:46:50.345270 00009C24 SM   | | | | | | PswdExit:send_request. 
HTTP request: GET /AIMWebService/api/Accounts?Safe=Cyberark_Accounts&Object=ari48013&AppID=applid&PolicyID=polid HTTP/1.0
User-Agent: Boost.Beast/322
Host: 127.0.0.1

Secure+ requires a root ca certificate to authenticate the CyberArk server. It also needs an identity certificate containing both a public key certificate and a private key. The identify certificate authenticates the Connect:Direct node to the CyberArk server. These certificates must be imported to the Secure+ keystore. The identity certificate label to use with CyberArk must be selected in the Secure+ PswdExit or Local node record.