How to use the User-defined Authentication

The user defined authentication allows you to use other non Windows authentication systems such as LDAP. To use this authentication method it is necessary to implement a specific interface by implementing the OaAuthMethodUserdefined class. How to implement the user-defined class and what methods to call as well as what else to consider in order to use the user-defined authentication is described in the following.

  1. Below you can find all the listed methods below in the OaAuthMethodUserdefined class. Save the class in thescripts\libs\classes\auth directory of your project. Implement the [OaAuthMethodUserdefined] class by using and implementing the following methods in your class. Most of the methods do not need to be changed. You can find the whole class at the end of this chapter.
  • OaAuthMethodUserdefined(): DO NOT REMOVE THE EXISTING CODE IN THIS METHOD! See the class description at the end of this page for the constructor.
  • isEnabled(): Change the return value to TRUE.
  • checkUserPassword(): The method checkUserPassword() must implement the password check.
  • create(): The method instances an object of the OaAuthMethodUserdefined class. DO NOT CHANGE THE METHOD! For the create() method, see the class description at the end of this chapter. The method is not documented since it must not be changed.
  • getName(): The method returns the name of the authentication method. THE FUNCTION SHOULD NOT BE CHANGED.
  • getAuthType(): Returns the authentication type of the class. THE FUNCTION SHOULD NOT BE CHANGED.
  • getMustCreateUser(): Implement this method if a user should be created in the WinCC_OA after a successful login.

Methods that need to be implemented by the user for the server-side authentication for UI managers:

  1. In order to use the user-defined authentication, open the user management panel via System Management -> Permission -> User Administration. Under User Administration, select the [Userdefined] from the "User Administration" combo box. Note that if the Userdefined option is not available, check that you have implemented the isEnabled() method or restart the UI manager. The user-defined authentication is activated.
  2. Open the user-defined login panel via the WinCC OA console: -p vision/loginUserdefined.pnl The user-defined authentication is being used.
CAUTION:

You have to call the function initHosts() in the start panel of your project if you do not start with the login or system management panel and your project is redundant. The initHosts() function defines necessary global variables and initializes the hosts.

Note that you may not use the reserved words Standard and Windows in the user-defined class as the class name.

Note: When using the user-defined authentication, the message for the user administration combo box of the user administration must be added to the message catalog file "userMan" under wincc_oa_path\msg\[language]. Therefore, add the suretoswitchext2 entry to the file and use a message such as "All WinCC OA defined users are deleted and the Windows defined users are taken over, do you really want to switch?" if the OaAuthMethodUserdefined class also deletes all users. If the users are not deleted, adapt the message accordingly.
/** OaAuthMethod is a base class for all authentication functions. */
#uses "classes/auth/OaAuthMethod"
class OaAuthMethodUserdefined: OaAuthMethod
{
  /**
  ATTENTION: Don't remove existing code in this function (this.authType = OaAuthenticationType::Userdefined;)
  This is the constructor of the OaAuthMethodUserdefined class. Add the functionality
  that should be done in the OaAuthMethodUserdefined
  constructor to the constructor of the class.
  */
  public OaAuthMethodUserdefined()
  {
    this.authType = OaAuthenticationType::Userdefined;
  }
  /**
  ATTENTION: The isEnabled() function must be changed for the Userdefined class.
  The class implements an authentication method.
  This function returns FALSE by default. Therefore, the Userdefined class cannot
  be loaded from the user administration panel ud_main.pnl
  if the Userdefined class should be used, this function must return TRUE.
  @return bool
  */
  public static bool isEnabled()
  {
    return FALSE;
  }
  /**
  ATTENTION: The function checkUserPassword() must be changed for the Userdefined
  class to implement the authentication method via the
  Userdefined class.
  The checkUserPassword function must implement a password check for the user.
  If the check is successful, a unique sessionId has to be returned via the sessionID
  parameter and the return value must be OaAuthenticationError::None.
  In case of failure the sessionID parameter must be an empty string and the return
  value must be of type OaAuthenticationError Enum.
  For creating a sessionID use the inherited function: createSessionId(string username)
  @param user ... must be of type OaAuthUser
  @param password ... contains the entered password as a string
  @param sessionID ... return parameter
  @return
  */
  public OaAuthenticationError checkUserPassword(anytype user/*must be of type OaAuthUser*/,
  string password, string &sessionID)
  {
    return OaAuthenticationError::None;
  }
  /**
  ATTENTION: The function getHttpPermissions() needs to be changed for the Userdefined
  class to work with ServerSideAuth (server-side authentication).
  See base class OaAuthMethod for an implementation example.
  @param bAllowUnknownUsers ... return value that defines if unknown users are
  allowed
  @param bCheckPassword ... return value that defines if password should be checked
  @param bAllowDisabledUsers ... return value that defines if disabled users are
  allowed
  */
  public void getHttpPermissions(bool &bAllowUnknownUsers, bool &bCheckPassword,
  bool &bAllowDisabledUsers)
  {
    return;
  }
  /**
  If the functionality of the base class OaAuthMethod is sufficient, this class
  must be deleted. If another way to enabled ServerSideAuth needs to be implemented,
  implement it here.
  @return bool
  */
  public bool isServerSideAuthEnabled()
  {
    //     bool httpAuth = FALSE;
    //     httpAuth = (1 == paCfgReadValueDflt(getPath(CONFIG_REL_PATH)+"config",
    "webClient", "serverSideAuth", 0));
    //     return httpAuth; // Deactivated by default
  }
  /**
  ATTENTION: Function must not be changed
  The function isServerSideAuthEnabled() is used by the factory class to instantiate
  an object of the
  OaAuthMethodUserdefined class.
  @return an object of the OaAuthMethodUserdefined class
  */
  public static OaAuthMethod create()
  {
    OaAuthMethodUserdefined auth;
    return auth;
  }
  /**
  ATTENTION: Function should not be changed. Change the name of the authentication
  method in the OaLogin.cat catalog file in the msg directory. The function returns
  the name of the authentication method. The name displayed in the user administration panel.
  @return "Userdefined"
  */
  public static string getName()
  {
    return "Userdefined";
  }
  /**
  ATTENTION: Function should not be changed.
  Returns the authentication type of the class
  @return OaAuthenticationType::Userdefined
  */
  public OaAuthenticationType getAuthType()
  {
    return OaAuthenticationType::Userdefined;
  }
  /**
  Additional Functions of the base class that can be implemented in this class
  are:
  * externalUserExists(string username);
  * getAllGroups();
  * getDomain();
  * getExternalId(string &externalId, string username = "");
  * getGroupsForExternalId(string externalId, dyn_string &groups);
  * getTimeout();
  * logout();
  * setAllGroups();
  * ssoEnabled();
  * passwordResetEnabled();
  * deleteUsersOnActivate();
  * mustCreateUser();
  For further information on the functions, see the function documentation in the
  OaAuthMethod base class.
  */
};