Password Exit
- If Connect:Direct for Microsoft
Windows service is configured to run using the ‘Local System’ account (which is the Connect:Direct for Microsoft
Windows
installation default):
- Add the group ‘SYSTEM’ to the folder’s security.
- Set the folder Permissions for ‘SYSTEM’ to allow ‘Read & execute’.
- If the Connect:Direct for Microsoft
Windows service is configured to run using a user account:
- Add the user to the folder’s security.
- Set the folder Permissions for the user to allow ‘Read & execute’.
DLL Interface
Connect:Direct will load and unload DLL dynamically.- 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*);
- 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 ExitsGet Password Reply- The request structureGET_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
PasswordExit
directory are :-
Visual Studio Files
- PasswordExitDLL.sln– Visual Studio Solution file. Open this file in Visual Studio 2019 to build the Sample Password Exit DLL.
- PasswordExitDLL.vcproj*– Visual Studio project files referenced by the Visual Studio Solution file.
- Sample Password Exit DLL source files
- Pswdexitlibrary.cpp– Source file for the sample Password Exit DLL.
- Pswdexlibrary.h– Header file for the sample Password Exit DLL.
- Dllmain.cpp– dll entrypoint.
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
- CyberArkExit.vcxproj
- CyberArkExit.vcxproj.filters
- framework.h
- pch.cpp
- pch.h
- PaswdCache.cpp
- PswdCache.h
- PswdExit.cpp
- PswdExit.h
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.
- In the Project Explorer, right click on the Project and click Properties.
- Click .
- In the VC++ Directories tab, include the path of boost and boost.url in External Include Directories
CyberArk Configuration Steps
Step 1: Configure Initialization parameters/miscellaneous parameters.
- Set password.exit.appl.id: CDW-MFT…
- Set password.exit.dll: C:\...\IBM\Connect Direct v6.2.0\Server\CyberArkExit.dll
- Set password.exit.hash: 289DDB87027B2AE8A………….
- Set password.exit.url: https://servicesexample.com//AIMWebService/api/Accounts?Safe=Cyberark_Accounts
- Password.exit.policy.id is optional.
- https://cyberark-server.company.com/AIMWebService/api/Accounts?safe=cdw_account
URL Component Description https:// The URL is expected to begin with the https:// scheme name. Only secure connections are supported. The scheme name of the URL is ignored. The hostname should specify your company’s CyberArk server DNS address. The default port is 443 but can be overridden in the URL. /AIMWebService/api/Accounts The URL path component identifies the CyberArk service. ?safe=cdw_account Specifies the CyberArk account/safe to use with this GetPassword request.
URL Query Component | Description |
---|---|
&Object= cd_userid | Identifies the Windows OS user logon. Set by the exit. |
&AppID= | Mandatory: The CyberArk application ID assigned to Connect:Direct. Configured using Initparms > miscellaneous commands > password.exit.appl.id. If an application ID is specified in the Functional User Authority, it will override the existing setting. |
&PolicyID= | Optional: The Cyberark Policy ID assigned to Connect:Direct. Configured using Initparms ->miscellaneous commands -> password.exit.policy.id. If a policy ID is specified in the Functional User Authority, it will override the existing setting. |
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
- In the Main tab, select the User Password Exit
checkbox.If Password Exit details are defined in the Password Exit tab, the Application ID and Policy ID overrides the default values for the user.
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.