Set up customized authentication modules

In addition to the authentication methods supported out-of-the-box, you can configure PVWA to work with any authentication method by implementing a custom plugin (in C#).

Perform the following procedures in the order they appear.

Implement the plugin

The first step is to create a new class library project and implement the methods that will be used for authentication.

To implement the plugin: 

1. Create a new class library project, and add a reference to the CyberArk.Authentication.BaseModule.dll assembly located in the \Inetpub\wwwroot\PasswordVault\bin folder.

2. In the new project, create a new class that extends the abstract CyberArk.Authentication.BaseModule.BaseAuthentication class.

   This class is defined in the CyberArk.Authentication.BaseModule.dll assembly:

   public class 3rdPartyAuthentication : CyberArk.Authentication.BaseModule.BaseAuthentication

3. Implement the following methods:

   In classic UI

   method	Description
   GetModuleId	This method returns the unique identifier of the authentication module. Typically, this is the name of the authentication method. This is the same identifier that is defined in the Configuration section in PVWA in Configure the custom authentication in the PVWA.   /// <summary> /// Implement to return a unique identifier for the authentication /// module </summary> /// <returns>A unique identifier to be used for this authentication /// module</returns> protected abstract string GetModuleId();
   GetUserName	This method returns the name of the user that was authenticated by the third party authentication method.   /// <summary> /// Implement to return a user name according to the authentication /// method </summary> /// <returns>The identifier of the user to authenticate with /// </returns> protected abstract string GetUserName(); How to implement this method: Retrieve the authenticated user token from the HTTP request and validate it and extract the user name. Until the authenticated user is retrieved, return an empty value.   You can use the PVWA web.config to store additional configurations. For example: In the web.config file (in <appSettings>): <add key="CustomAuthRedirectURL" value="https://idp-auth-url.com" /> In custom auth dll code: System.Configuration.ConfigurationManager.AppSettings["CustomAuthRedirectURL"];

   In v10

   method	Description
   GetModuleId	This method returns the unique identifier of the authentication module. Typically, this is the name of the authentication method. This is the same identifier that is defined in the Configuration section in PVWA in Configure the custom authentication in the PVWA.   /// <summary> /// Implement to return a unique identifier for the authentication /// module </summary> /// <returns>A unique identifier to be used for this authentication /// module</returns> protected abstract string GetModuleId();
   GetUserName	This method returns the name of the user that was authenticated by the third party authentication method.   /// <summary> /// Implement to return a user name according to the authentication /// method </summary> /// <returns>The identifier of the user to authenticate with /// </returns> protected abstract string GetUserName(); How to implement this method: Retrieve the authenticated user token from the HTTP request and validate it and extract the user name. Until the authenticated user is retrieved, return an empty value.   You can use the PVWA web.config to store additional configurations. For example: In the web.config file (in <appSettings>): <add key="CustomAuthRedirectURL" value="https://idp-auth-url.com" /> In custom auth dll code: System.Configuration.ConfigurationManager.AppSettings["CustomAuthRedirectURL"];
   GetRedirectUrl	This method returns the logon page of the auth module that authenticates the user.   /// <summary> /// Implement to return the logon page of the auth module that authenticates the user /// </summary> /// <returns> /// The logon page URL to authenticate the user /// </returns> protected virtual string GetRedirectUrl()

4. Test the module.

5. Copy the authentication module into the PVWA bin folder.

   This causes the PVWA to restart.

   Only in v10: In the PasswordVault folder, create a new subfolder called CustomAuthenticationDlls and copy the custom authentication module into it.

Configure the custom authentication in the PVWA

After you implemented the plugin, you can configure the custom authentication in the PVWA.

To configure the web.config file:

In the Web.config file, in the httpModules section, above the CyberArkGatewayModule, add the new authentication module class:

<httpModules>
    <add name="3rdPartyAuthenticationModule" 
type="full class name, assembly name" />
</httpModules>

In the name parameter, specify a meaningful name of your choice. This will cause the PVWA to restart.

To add the custom authentication method:

1. In the PVWA, click Administration > Configuration Options, and then, on the System Configuration page, click Options.
2. In the Options pane, right-click Authentication Methods, and then click Add AuthMethod.

3. On the Properties page, enter the following information:

   Property	Description
   Id	The ID of the new third party authentication method. This is the same ID that you return in your implementation of GetModuleId(). The ID is case-sensitive, so make sure that you specify it exactly as is appears in the specified module.
   DisplayName	A meaningful display name for the authentication method.
   Enabled	Set to Yes.
   LogoffUrl	Specify the logoff page of the 3rd party server. If you leave it empty, users will remain authenticated to the PVWA as long as they are authenticated to the 3rd party server.

   

   For details on the various parameters, see Authentication Methods.

Enable the authentication type

To enable the authentication type:

1. Open the PasswordVault\auth folder, and create a new subfolder. Use the ID of the authentication method.

   This is the same ID that you return in your implementation of GetModuleId().

   The ID is case-sensitive, so make sure that you specify it exactly as is appears in the specified module.

2. Copy the default.aspx file from any of the other authentication folders under PasswordVault/auth, to the new folder.

   This file is a placeholder that is required to run the new authentication type.

3. By default, the PVWA folders cannot be modified. To change this, open the PrecompiledApp.config file in the PasswordVault folder and set the updatable parameter to true, as follows:

   updatable="true"