JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

Custom Hub Authentication Plug-Ins

If you wish to use third-party authentication with your hub, but none of the third-party authentication plug-ins shipped with CodeSonar are suitable, you can write your own custom authentication plug-in.

This page details the steps involved in creating and installing such a plug-in. Tutorial: Add A Custom Hub Authentication Plug-In illustrates these steps with a simple example.

Note that third party authentication service accounts and hub user accounts remain separate entities with separate sets of credentials. Changing hub user account credentials (for example, by changing your password in the Settings: Account tab) has no effect on authentication service account information, and changing authentication service account credentials has no effect on hub user account information.

Note

In this section (and throughout this manual), $CSONAR indicates the CodeSonar installation directory.

Overview

Adding a new CodeSonar hub authentication mechanism involves four steps:

Permissions Required

You will need to be authenticated as a user with the following permissions in order to configure a hub authorization plug-in.

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 Identify required service-specific configuration information

The required service-specific configuration information will depend entirely on the nature and requirements of the third-party authentication service. For example:

Step 2 Create HTML fragments for the authenticator

There are two optional HTML fragments that you can provide for your authenticator. You can provide one, both, or neither.

Step 3 Create the plug-in: a Python wrapper for the authentication service

The Python wrapper must conform to specific file name and location, class implementation, and global assignment requirements.

File Name and Location The Python file must have a name of the form pname_authplugin.py and be located in one of the following directories.
Directory Plug-In Will Be Available To
$CSONAR/codesonar/py/hub/auth/ All hubs running from that CodeSonar installation.
<hubdir>/auth/ The hub whose hub directory is <hubdir>.
Wrapper Class The wrapper must be implemented as a class (referred to here as AuthCl), with requirements as shown in the following table.
Required data members for AuthCl
name A short descriptive name for the authenticator, as a string. This will be used as the Type value for the resulting authentication service. It should uniquely identify the plug-in.
Required method for AuthCl: at least one of the following.
get_user(
  • self,
  • username,
  • password,
  • conf_data )
 Identifies a hub user based on a username and password, in combination with any data obtained through the plug-in's HTML fragment.
username is the username string provided.
password is the password string provided.
conf_data is a tuple containing any information gathered from the form fields of the HTML fragement you designed in Step 2..

get_user(uname, passwd, cdata) returns:

  • a dict with required key 'user' and optional keys 'email', 'roles' if the uname/passwd combination is valid with respect to cdata.
    • 'user' : the "canonical user name" according to the authentication service. It must be a nonempty string. This value will match the Username for the corresponding hub user account.
    • 'email' : [optional] the email address that the authentication service associates with the user. If the hub user account Email has special value NULL, it will be updated to this value. Set to None if there is no such address (or if the author does not want to pass it to CodeSonar).
    • 'roles' : [optional] the names of the roles that should be associated with the user on behalf of this plug-in, as an iterable of str.
      When a user logs in with username and password through the plug-in, these role names are used to update their hub user account Roles as follows.
      • All the named roles that were not already assigned are added.
        • If the user was not already assigned a given role, the hub will also record that the assignment for that role was performed by this plug-in.
        • If there is no role corresponding to a particular name, that name is ignored.
      • Roles that were previously added by this plug-in but do not appear on the list are removed.
  • None if the uname/passwd combination is not valid with respect to cdata.

If a problem occurs, get_user() should raise an AuthException.
get_user_from_cert(
  • self,
  • client_cert,
  • client_cert_dict,
  • conf_data )
 Identifies a hub user based on a TLS certificate, in combination with any data obtained through the plug-in's HTML fragment.
client_cert is the TLS certificate provided, in raw (DER) binary encoding. Note that the hub will already have checked that this certificate is trusted by the hub's client authentication certificate and rejected the authentication attempt if it is not trusted.
client_cert_dict is a dict containing information parsed from client_cert.
conf_data is a tuple containing any information gathered from the form fields of the HTML fragement you designed in Step 2.

get_user_from_cert(cert, cert_dict, cdata) returns:

  • a dict with required key 'user' and optional keys 'email', 'roles' if cert is valid with respect to cdata.
    • 'user' : the "canonical user name" according to the authentication service. It must be a nonempty string. This value will match the Username for the corresponding hub user account.
    • 'email' : [optional] the email address that the authentication service associates with the user. If the hub user account Email has special value NULL, it will be updated to this value. Set to None if there is no such address (or if the author does not want to pass it to CodeSonar).
    • 'roles' : [optional] the names of the roles that should be associated with the user on behalf of this plug-in, as an iterable of str.
      When a user logs in with username and password through the plug-in, these role names are used to update their hub user account Roles as follows.
      • All the named roles that were not already assigned are added.
        • If the user was not already assigned a given role, the hub will also record that the assignment for that role was performed by this plug-in.
        • If there is no role corresponding to a particular name, that name is ignored.
      • Roles that were previously added by this plug-in but do not appear on the list are removed.
  • None if cert is not valid with respect to cdata.

If a problem occurs, get_user_from_cert() should raise an AuthException.
get_user_from_request(
  • self,
  • acs_url,
  • post_data,
  • conf_data )
 Identifies a hub user based on the POST request returned by a Single Sign On (SSO) Identity Provider (IdP) to the hub upon successful authentication.
acs_url is the Assertion Consumer Service URL to which the IdP just sent the POST request. This will be a URL on the hub. The acs_url is provided in case it is required to validate or interpret the post_data argument.
post_data is a dict of the data from the POST request issued by the IdP on successful hub authentication.
The IdP will need to be configured to include in this POST request any data expected by your authenticator. In particular, the POST request should include sufficient data to allow your get_user_from_request() implementation to populate the returned dict.
conf_data is a tuple containing any information gathered from the form fields of the HTML fragement you designed in Step 2.

get_user_from_request(rurl, rpostdata, rconfdata) returns:

  • a dict with required key 'user', and optional keys 'email', 'sso_id', 'expiry', 'roles' if the combination of rurl and rpostdata represents successful SSO authentication for the hub.
    • 'user' : a nonempty string that will match the Username for the corresponding hub user account.
    • 'email' : [optional] the email address associated with the user. If the hub user account Email has special value NULL, it will be updated to this value. Set to None if there is no such address (or if you do not want to pass it to CodeSonar).
    • 'sso_id' : [optional] the ID of the SSO request.
    • 'expiry' : [optional] a datetime object representing when the SSO request expires. If this is None, authentication will expire a day after the request was received.
    • 'roles' : [optional] the names of the roles that should be associated with the user on behalf of this plug-in, as an iterable of str.
      When a user logs in with username and password through the plug-in, these role names are used to update their hub user account Roles as follows.
      • All the named roles that were not already assigned are added.
        • If the user was not already assigned a given role, the hub will also record that the assignment for that role was performed by this plug-in.
        • If there is no role corresponding to a particular name, that name is ignored.
      • Roles that were previously added by this plug-in but do not appear on the list are removed.
  • raises AuthException if authentication failed.

If a problem occurs, get_user_from_request() should raise an AuthException.
sso_redirect(
  • self,
  • acs_url,
  • return_state,
  • conf_data )
 [Only for authenticators that implement get_user_from_request()]

Returns the URL to which the hub should redirect for SSO authentication.

acs_url is the Assertion Consumer Service URL to which the IdP should send the POST request after authentication. This will be a URL on the hub.
return_state is a URL-encoded string containing information the hub uses to redirect the user back to the right page after authentication is done.
conf_data is a tuple containing any information gathered from the form fields of the HTML fragement you designed in Step 2.
When the IdP sends its response to the hub, this data must be sent inside a POST field named RelayState.
Optional methods for AuthCl
get_conf_html(
  • self,
  • conf_data )
 Returns the HTML-format configuration fragment you designed in Step 2. This fragment will be displayed as part of the Form for Adding a New Service when this authenticator type is selected.

If this method is not defined, no HTML fragment will be associated with the authenticator.

conf_data is a dictionary containing the most recently obtained configuration data for the service. You can use this to highlight submitted data elements that have failed validation.
  • If the data obtained for service configuration/reconfiguration has failed validation, conf_data is the same dictionary that was passed to the failed validate() call.
  • Otherwise, if this is a new service, conf_data is None.
  • Otherwise (that is, an existing service is being edited), conf_data contains the saved configuration data for the service.
(CodeSonar will automatically populate form fields with the current configuration data: get_conf_html() does not need to provide this functionality.)
get_notes(
  • self,
  • hub_url,
  • acs_url,
  • conf_data )
 Returns the HTML-format installed authenticator fragment you designed in Step 2. This fragment will be displayed in the corresponding row of the table of current services for each authentication service of this type.

If this method is not defined, no HTML fragment will be displayed.

hub_url The base URL for the hub.
For SSO-based authenticators, the SSO IdP will generally need to be configured to recognize this as the Entity ID for a permissible source of requests. In this case, include the value of hub_url in the returned HTML fragment, perhaps with some IdP configuration instructions.
acs_url The hub Assertion Consumer Service URL associated with this service.
For SSO-based authenticators, the SSO IdP will generally need to be configured to use this URL to POST information to the hub. In this case, include the value of acs_url in the returned HTML fragment, perhaps with some IdP configuration instructions.
validate(
  • self,
  • conf_data )
 Verifies that the data obtained through the plug-in's HTML fragment is valid with respect to the needs of the authentication mechanism.
conf_data is a dictionary containing any information gathered from the form fields of the HTML fragment you designed in Step 2.

On successful validation, validate(cdata)may return either a dictionary or nothing. If a dictionary is returned, it will replace the original information tuple in any subsequent call to get_user().

validate(cdata)should raise an AuthException if the contents of cdata are not valid data with respect to the needs of the authentication mechanism.
Setting AUTH_PLUGINS The Python file must also contain an assignment to AUTH_PLUGINS: 
AUTH_PLUGINS = tup

where tup is a tuple containing instances of all plug-in classes in the file. The assignment must follow the class definition: the end of the Python file is usually the most convenient location.

Example 1: the My_global_auth plug-in is suitable for all systems.

AUTH_PLUGINS = (My_global_auth(),)

Example 2: the My_ix_auth plug-in is only suitable for Posix-based systems.

if re.search('posix', os.name) == None:
    AUTH_PLUGINS = ()         
else:
    AUTH_PLUGINS = (My_ix_auth(),)

Step 4 Configure the plug-in on your hub.

Configure the plug-in for a hub listening at interface:port with hub directory at hubDir as follows.
A more detailed version of these instructions is provided in Tutorial: Add a Custom Hub Authentication Plug-In.

  1. Shut down and restart the hub (or just start, if it is not already running).
    codesonar hub-stop interface:port
    codesonar hub-start hubDir interface:port
    (You may be prompted for hub user account credentials to authenticate and authorize the hub-stop command.)
  2. Sign in as Administrator (or another user with the required permissions).
  3. Navigate to the Authentication Services page.
  4. Scroll down to the Add Service form.
  5. Select your new plug-in from the Type menu (as specified by the plug-in's name data member).
    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.
  6. Fill in the remainder of the Add Service form fields (including all required Configuration information).
  7. 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.
  8. Try out the newly configured authentication service: try to sign in to the hub with your credentials from that service.
    If everything is working correctly, the hub will sign you into a corresponding hub user account.
    (Unless one did not already exist and you disabled automatic account creation when you were configuring the service.)
  9. If you need to modify the configuration for the service, click the corresponding entry in the table of current services and use the functionality on the Edit Authentication Service page that opens.

Links

 

To report problems with this documentation, please visit https://support.codesecure.com/.