Tutorial: Add a Custom Hub Authentication Plug-In

• Overview
• Adding A Simple Authenticator
• A More Complex Authenticator

Note

Overview

The requirements for adding a custom hub authentication plug-in are described in Custom Hub-Authentication Plug-ins

Adding A Simple Authenticator walks through the steps for a trivial authenticator.

A More Complex Authenticator provides a more "realistic" example that you can use as a basis for creating your own authentication plug-ins.

Adding A Simple Authenticator

In this example you will add a simple example authenticator that checks user credentials against a hardcoded username/password table.
The following instructions are based on a hub listening at interface:port with hub directory at hubDir.

Permissions Required

The CodeSonar command lines and GUI interactions described in these steps require the following permissions.

• G_HUB_SHUTDOWN (needed for codesonar hub-stop).
• G_MANAGE_USERS (needed to access the Authentication Services page).
• User control over the hub user accounts that you want to use as the template user and authorizing user for your new authentication service.
  • G_ADMINISTER_USERS
    or
  • G_MANAGE_USERS and ROLE_ADMINISTER R for every role R that the user is assigned.
  Note also that the template user must have user control over the authorizing user.
• (Security for codesonar hub-start is managed by controlling file system access to the hub directory, not through RBAC permissions.)

It is sufficient to authenticate as a user with the special Administrator role, which immutably has all the necessary permissions. In particular, it is always sufficient to authenticate as special user Administrator.

[Step 1] Determine required configuration information

The hardcoded table used by the simple example authenticator includes a user called 'Administrator'. This might cause a security problem in some cases:

• The 'Administrator' in the table may not be the same person as the hub Administrator.
• The password in the table is not very secure.

We therefore provide a configuration setting to optionally disable authentication for this user. Note that this setting only applies to authentication with the simple example authenticator: Administrator will still be able to sign in using hub credentials and through any other configured authentication service that permits it.

[Step 2] Create an HTML fragment

We need one piece of service-specific configuration information, so our HTML fragment must include an input field to collect it.

We will use the following fragment: you will see in the next step that we have implemented function get_conf_html() to return this text.

<style>
    #tutorial_auth_table{ width: 800px; }
    #tutorial_auth_table td{vertical-align: top;text-align: left;}
</style>

<table id="tutorial_auth_table" cellpadding="10"> 
    <tr>
        <td><b>Include Administrator?</b>:</td>
        <td><input type="checkbox" name="include_admin"><br>
                The user database for this authentication scheme includes a user<br>
                called 'Administrator'. If this is not the same person as the hub<br>
                Administrator, it is a good idea to exclude them from authentication.</td>
    </tr>
</table>

[Step 3] Create a Python wrapper

The Python wrapper for the authenticator is shown below.

1. Create a new file named $CSONAR/codesonar/py/hub/auth/tutorial_authplugin.py and copy and paste the following code into that file.

# Nontrivial authenticators should raise an AuthException if something
# unexpected happens.  This authenticator does not actually raise any
# exceptions, but the import statement is included as a reminder in
# case you decide to use this file as a basis for implementing a
# 'real' authenticator.

from auth import AuthException 

class TutorialAuthExample(object):
   """A very simple example of writing an authorization mechanism"""

   name = "TutorialAuthExample"                      # Required name data member.
    
   # set of permitted username/password pairs
   user_db = [('Alex','1234'), ('Administrator','5678')]

   def get_user(self,username, password, conf_data):      # Required get_user() method.
      # Never authenticate 'Administrator' if plug-in was configured
      # to exclude this user.
      if username=='Administrator' and not conf_data['Authenticate Administrator?']:
         return None

      # Trivial authentication:  check list membership.
      if (username,password) in self.user_db:
         # On success, return a dict with keys 'user' and 'email'.
         # 'user' must map to a nonempty string. 'email' can be a string
         # or None.
            return { 'user': username, 'email': None }
      else:
         # On failure, return None
            return None

    
   def validate(self, conf_data):                    # Optional validate() method.
      # transform checkbox data into a binary attribute
      new_conf_data = {
            'Authenticate Administrator?': 'include_admin'  in conf_data}
      return new_conf_data
    
        
   def get_conf_html(self, conf_data=None):             # Optional get_conf_html() method.
      # Returns the HTML fragment from step 2.
      return """
<style>
    #tutorial_auth_table{ width: 800px; }
    #tutorial_auth_table td{vertical-align: top;text-align: left;}
</style>

<table id='tutorial_auth_table' cellpadding="10"> 
    <tr>
       <td><b>Include Administrator?</b>:</td>
        <td><input type="checkbox" name="include_admin"><br>
                The user database for this authentication scheme includes a user<br>
                called 'Administrator'. If this is not the same person as the hub<br>
                Administrator, it is a good idea to exclude them from authentication.</td>
    </tr>
</table>"""

# Required assignment to AUTH_PLUGINS
AUTH_PLUGINS = (TutorialAuthExample(),) 

[Step 4] Configure the new plug-in on your hub

In the previous step, you placed the Python wrapper file in the $CSONAR/codesonar/py/hub/auth/ directory. This means that it will be available for configuration on your hub (and any other hubs running from the same CodeSonar installation).

1. Shut down the hub if it is running.
   codesonar hub-stop interface:port
2. Restart the hub.
   codesonar hub-start hubDir interface:port
   Restarting the hub allows it to recognize the availability of your new authentication plug-in.
3. Sign in as Administrator (or another hub user with the required permissions).
   1. Click the Sign In link (at the top right of the page).
      CodeSonar will open a page for you to enter credentials.
   2. Enter Administrator in the Username field.
   3. Enter the Administrator password in the Password field.
      (If you have just started a new hub, you will have set a password for Administrator as part of that process.)
   4. Click Sign In.
4. Click the Settings icon in the page header to view the Settings page.
5. Change to the User Administration tab.
6. Click the Authentication Services link in the tab.
   The Authentication Services page will open.
7. Scroll down to the Add Service form.
8. Select "TutorialAuthExample" from the Type menu.
   The Configuration section of the Add Service form will update to render the HTML fragment returned by the plug-in's get_conf_html() method.
9. Deselect the Include Administrator? checkbox (it is probably already deselected).
10. Enter a suitable name, such as My Tutorial Auth, in the Service Name field.
11. Set Priority to 1.
12. For Usage, select Global.
13. Make sure the Create new user accounts automatically checkbox is selected.
14. Choose a suitable Template User for any accounts automatically created by the authentication service.
    • You must have user control over this user account.
15. Choose a suitable Authorizing User. The authentiocation service will only be able to perform operations that this user can perform.
    • You must have user control over this user account.
    • The Authorizing User must have user control over the Template User.
16. Click Add Service.
    Your new authentication service will be installed. When installation has finished, the table of current services will update to show an entry for the new service.
17. Try out the new service.
    1. Sign out of your user session.
    2. Sign in with the Alex credentials from the table used by the new authentication service.
       • Username: Alex
       • Password: 1234
       If everything is working correctly, the hub will sign you into the Alex hub user account. If an account for Alex did not already exist, the hub will create one automatically and prompt you for an email address for the account before signing you in.
    3. Sign out of the Alex account.
    4. Try to sign in with the Administrator credentials from the table used by the new authentication service.
       • Username: Administrator
       • Password: 5678
       Authentication will fail (unless someone has changed the hub user account password for Administrator to 5678), because you configured this service to not authenticate Administrator.
18. If you don't want to keep the example authentication service on your hub, remove it now.
    1. Sign in as Administrator (or another user with the required permissions).
    2. Navigate back to the Authentication Services page.
    3. Click the Remove Services button (under the table of current services).
    4. Select the checkbox on the table row for the example authentication service.
    5. Click Remove Selected Services.
    Your new authentication service will be removed. When removal has finished, the table of current services will update to account for the removal.

A More Complex Example Authenticator

We have provided the following source files for a more complex example authenticator: one based on SSH login authentication.

This example is provided for illustration only: we do not provide build instructions for the C++ component, although you can certainly try it for yourself if you wish. The following steps represent a guided inspection of the plug-in files.

1. [Step 1] An authenticator based on ssh login authentication requires information about the SSH hostname, so this piece of information will need to be be collected at the configuration stage.
2. [Step 2] File auth_ssh_nix.html contains the HTML fragment created for the authenticator. Note the following features of the code.
   • There is an <input> element for collecting the SSH hostname at configuration time.
   • The name attribute of the <input> element has value ssh_target_name, chosen by the plug-in author.
3. [Step 3] File ssh_nix_authplugin.py contains the Python wrapper code for the authenticator. Note the following features of the file and code.
   • The file name conforms to the required pname_authplugin.py form.
   • The file implements the wrapper in a class called Auth_ssh_nix.
   • name is set to a short descriptive string.
   • validate() checks the collected configuration data - here, the value of the ssh_target_name input collected from the form in auth_ssh_nix.html - and returns a validated version.
   • get_user() ...
     • ... raises an AuthException on non-Posix operating systems.
     • ... invokes authentication functionality defined in gtauth_ssh.cpp.
     • ... returns a dict with keys 'user' and 'email'.
   • get_conf_html() returns the contents of auth_ssh_nix.html, or raises an AuthException if the HTML file is not present.
   • AUTH_PLUGINS is set to a tuple containing an instance of Auth_ssh_nix on Posix operating systems; an empty tuple otherwise.
4. [Step 4] Installing this authenticator on a hub will involve the following steps.
   1. Compile gtauth_ssh.cpp into a binary.
   2. Save auth_ssh_nix.html and ssh_nix_authplugin.py to $CSONAR/codesonar/py/hub/auth/.
   3. In ssh_nix_authplugin.py, adjust the setting of install_gtauth_ssh_path to be the full path to the binary you compiled from gtauth_ssh.cpp.
   4. Restart the hub.
   5. Install the authenticator from the hub Authentication Services page.