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

Hub Authentication

The CodeSonar hub provides functionality for authenticating users, and for controlling user access to various kinds of hub information and functionality.

Authentication and Authorization

All interactions with the hub must be authenticated and authorized.

The following hub interactions take place in sessions, which can be either user sessions or anonymous sessions.

Note: codesonar subcommands do not take place in sessions if they are executed without authentication, or authenticated with a password or certificate.

Authenticated codesonar Subcommands

The following codesonar subcommands require hub authentication and authorization.

When these subcommands are invoked from the command line, authentication and authorization behavior is specified by options

[-auth authtype] [-hubuser username] [-hubpwfile pwfile] [-hubbearerfile bearerfile] [-hubcert certfile] [-hubkey privatekeyfile]

Where:

Behavior and interaction for these options is described in the following table.

-auth Behavior and Interaction with -hubuser
default CodeSonar will first attempt to authorize the operation as Anonymous. If this is not successful, CodeSonar will request hub user account credentials, then attempt to authenticate with these credentials and authorize the operation as the specified user.
  • If -hubuser uname is specified, CodeSonar will request a password for uname.
  • Otherwise, CodeSonar will request both a hub username and a password.
anonymous CodeSonar will only attempt to authorize the operation as Anonymous. If -hubuser uname is specified it will be ignored.
password CodeSonar will request any credentials that haven't already been specified, then attempt to perform password authentication and authorize the operation as the specified user.
  • If -hubuser uname and -hubpwfile pwfile are both specified, CodeSonar will attempt to authenticate uname using the (plaintext) password stored in pwfile.
  • If -hubuser uname is specified without -hubpwfile pwfile, CodeSonar will request a password for uname
  • Otherwise, CodeSonar will request both a hub username and a password.
The codesonar generate_hubpwfile.py subcommand will interactively generate a password file for use with the -hubpwfile option. This is useful if you are deploying CodeSonar in a containerized context and want to use a temporary container to set up credentials and store them to a persistent location.
bearer -hubbearerfile bearerfile must also be specified. CodeSonar will attempt to perform bearer authentication using the contents of bearerfile as a bearer token, and authorize the operation as the Session User of the corresponding session.

If -hubbearerfile bearerfile is specified with no -auth option, CodeSonar will infer -auth bearer.

You can use the codesonar generate_hubbearerfile.py subcommand will to create a session save the session bearer token to a file; the file can then be used with the -hubbearerfile option. This is useful if you are deploying CodeSonar in a containerized context and want to use a temporary container to set up credentials and store them to a persistent location.
certificate CodeSonar will attempt to perform certificate authentication and authorize the operation as the user corresponding to the certificate's Subject Common Name.
  • If -hubuser uname is specified, uname will only be used to construct default locations for the hub certificate and private key, and only if the relevant options (-hubcert, -hubkey) are not directly specified. In particular, it will not be used to determine which hub user is authenticated: that will always be the user whose username matches the Subject Common Name specified in the certificate.
  • If -hubcert certfile is specified, CodeSonar will present the certificate in certfile to the hub, otherwise it will present the certificate in
    <pemdir>/<cert_uname>.<hub_render>.pem
    where
    <pemdir> depends on the operating system:
    • Windows: typically C:\Users\<win_username>\AppData\Roaming\CodeSecure\Codesonar\
    • Otherwise: ~/.csurf/codesonar/ (see .csurf note)
    <cert_uname> is uname if -hubuser uname is specified, otherwise the name of the system user running the command.
    <hub_render> is <host>_<port>, derived by replacing the colon with an underscore in the <host>:<port> specified for the command.
    If there is no such certificate, the operation will fail and report an error.
  • If -hubkey privatekeyfile is specified, CodeSonar will use the private key in privatekeyfile to sign its response to the hub's challenge, otherwise it use the private key in <pemdir>/privkey.pem, where <pemdir> depends on the operating system:
    • Windows: typically C:\Users\<win_username>\AppData\Roaming\CodeSecure\Codesonar\
    • Otherwise: ~/.csurf/codesonar/ (see .csurf note)
    The key itself will not be submitted to the hub.
    If there is no such key, the operation will fail and report an error.
  • .csurf note: if environment variable CS_USER_HOME is specified, the $CS_USER_HOME/.csurf/codesonar/ directory will be used instead of $HOME/.csurf/codesonar/.
(none) Behavior depends on other command line options.
if command line specifies...
(in order of precedence)		 ...then behavior is the same as for...
-hubuser uname -auth password -hubuser uname.
-hubbearerfile bearerfile -auth bearer -hubbearerfile bearerfile
none of the above -auth default with no -hubuser

Authenticated Configuration Tool Operations

The CodeSonar configuration tool provides an alternative interface for codesonar subcommands hub-info and hub-stop, so must authenticate and authorize these operations. It must also authenticate and authorize the hub-start subcommand when it is used to start a satellite hub (but not otherwise).

In both cases, authentication and authorization behavior is the same as that for command line invocation with -auth default. CodeSonar will first attempt to authorize the operation as Anonymous. If this is not successful, CodeSonar will request hub user account credentials, then attempt to authenticate with these credentials and authorize the operation as the specified user.

Authentication in the Windows Build Wizard

The Windows build wizard provides an alternative interface for codesonar subcommands build and analyze, so must authenticate and authorize these operations.

Build wizard users specify the authentication and authorization behavior for a build/analysis using the Auth field on screen 1, which is equivalent to the command line -auth option. The Windows build wizard does not provide an equivalent for the command line -hubuser option.

Behavior and interaction for these options is described in the following table.

Auth selection Behavior
(triggered when the user clicks Record on screen 2)
Anonymous; Password CodeSonar will first attempt to authorize the operation as Anonymous. If this is not successful, CodeSonar will open a dialog requesting hub user account credentials, then attempt to authenticate with these credentials and authorize the operation as the specified user.
(Corresponds to command line -auth default.)
Anonymous CodeSonar will only attempt to authorize the build/analysis as Anonymous.
(Corresponds to command line -auth anonymous.)
Password CodeSonar will open a dialog requesting hub user account credentials, then attempt to authenticate with these credentials and authorize the operation as the specified user.
(Corresponds to command line -auth password.)
Certificate CodeSonar will open two dialogs for you to select a user certificate and private key to use for certificate-based authentication. Once these are selected, CodeSonar will attempt to use them to authenticate and authorize the operation as the user named in the user certificate.
(Corresponds to command line -auth certificate.)

Authentication in the Eclipse and Visual Studio Integrations

The CodeSonar Eclipse integration and Visual Studio integration provide an alternative interface for codesonar subcommands build and analyze, as well as for viewing and annotating analysis results, so must authenticate and authorize these operations.

In both integrations, authentication type and credentials are specified on a per-project basis.

The options provided are the same in both cases.

Selection Behavior
Anonymous only CodeSonar will only attempt to authorize the build/analysis as Anonymous.
(Corresponds to command line -auth anonymous.)
Password CodeSonar will attempt to authenticate and authorize the build/analysis using a hub user account username and password.
(Corresponds to command line -auth default if Try Anonymous first is selected; -auth password otherwise.)

The following fields are associated with this option.

  • Try Anonymous first: When selected, CodeSonar will first attempt to authorize the operation as Anonymous. If this is not successful, CodeSonar will attempt password-based authentication.
  • Username: The hub account username to use for authentication
  • Password: The corresponding password.
Certificate CodeSonar will attempt to authenticate and authorize the operation using a user certificate.
(Corresponds to command line -auth certificate.)

The following fields are associated with this option.

  • Certificate location: The user certificate file.
  • Private key location: The corresponding private key file.
  • Private key password: [Eclipse integration only] If the private key is password-protected, the corresponding password.

Successful Authentication

By default, the hub will check the sign-in credentials against user account information stored in the hub database. If this fails, and the hub Administrator has configured the hub to use one or more third-party authentication services, the hub will then attempt to perform third party authentication with each of these services in order of priority.

The requirements for each authentication scenario are detailed in the following table.

Credentials Direct Hub Authentication Requirements Third Party Authentication Requirements
Username and Password Given a username uname and password passwd:
  • uname and passwd match the username and password for a hub user account,
    and
  • that account has G_SIGN_IN and G_SIGN_IN_PASSWORD permissions.
Note that if the hub user account password is NULL, a supplied username and password will never match the hub user account information and so the user will only be able to sign in with a certificate or through a third party authentication service. 		Given a username uname and password passwd:
Bearer Token Given a bearer token tok: n/a
TLS Certificate Given a TLS certificate cert: Given a TLS certificate cert:

Third-party Authentication Services

If your organization already has infrastructure for authenticating users, you can use a hub authentication plug-in to configure the CodeSonar hub to use the same infrastructure for hub authentication. The GUI Authentication Services page provides functionality for viewing, modifying, adding, and removing authentication services.

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.

Every authentication service configured for the hub has the following properties.

Priority For Single Sign-On (SSO) authentication services, this controls the order in which the tab for signing on with the service will appear on the CodeSonar Sign In page. Tabs for SSO services with lower Priority values are ordered before those for services with higher values; the tab with the lowest Priority is displayed by default.

For all other services, it controls the priority with which the service will be invoked to check user credentials, relative to the other installed (non-SSO) service.

  • Hub user account credentials always have first priority.
  • A service with a lower Priority value will be checked before a service with a higher Priority value.
Name An unique identifying name for the service, assigned by the Administrator.
ID An unique numerical identifier for the service, assigned by the hub.
Type The type of authentication service: the underlying protocol or third party software. For example, 'LDAP'.
Usage This controls how the authentication service will interact with primary-satellite hub relationships.
  • On a stand-alone hub (that is, a primary hub that has no satellite hubs), this setting has no effect.
  • Otherwise, this setting controls where the authentication service will run, and which hubs will be covered by it.
    Usage Runs on Add/Configure (Edit) from Authenticates users for
    Global Primary hub P.
    		 P. P or any satellite hub attached to P.
    Local Only the single hub H for which it was configured.
    • If H is a primary hub, the service does not apply to H's satellites.
    • If H is a satellite hub, the service does not apply to the primary hub to which H is attached or to any other satellites of that primary hub.
Service-Specific Configuration Any other configuration information for the service. This varies depending on the service Type.
Automatically Create Accounts? If "true", automatic account creation is enabled. Otherwise, it is disabled.
Template User When automatic account creation is enabled, the template user for any new accounts created on behalf of the service.
Has no effect if automatic account creation is disabled.
Authorizing User The hub user account from which the service will derive its authority.
  • This account must have user control over the designated Template User.
  • The authentication service will only be able to perform hub operations that this account has permission to perform.
In general, we recommend setting the Authorizing User as follows.
  • CodeSonar SaaS: the user account that is configuring the authentication service.
  • otherwise: special user Administrator.
Created The date and time at which the service was first configured for the hub (from the Authentication Services page).
Modified The date and time at which the service configuration was last modified (from the Edit Authentication Service page or Authentication Services page).
File The basename of the authentication plug-in that implements the service. See Custom Hub Authentication Plug-Ins: File Name and Location for more information.

Automatic Account Creation

Automatic account creation is managed on a per-authentication-service basis, and affects the way authentication proceeds when a user's sign-in credentials are accepted by the service but there is no hub user account with the same username.

Automatic Account Creation Enabled? Behavior when credentials accepted by the service but no hub user account exists
Yes A new hub user account is automatically created and the user is signed into it. The initial account property values are set as follows.
Default Role, Email Alerts?, Visibility Defaults Copied from the authentication service's specified template user at account creation time.
Email The email address provided by the authentication service, or NULL if none is provided.
Password NULL
Roles Copied from the authentication service's specified template user at account creation time, then Enabled also assigned.
Username The canonical name as provided by the authentication service.
No The service fails to authenticate the user.

More Information

The following manual sections provide further information about various aspects of hub authentication and access control.

GUI Pages
Authentication Services View and configure third-party authentication services for the hub.
Bulk Add Users Create multiple hub user accounts at once.
Configure HTTPS Specify an SSL/TLS certificate for the hub; enable/disable HTTPS.
Create Account Create a single hub user account; will permit you to specify the template user if you have G_ADMINISTER_USERS permission. Does not sign you into the new account.
Edit Authentication Service Edit the configuration for a third-party authentication service (including specifying whether automatic account creation will be enabled).
Global Role-Permissions View and edit the global role-permission assignments for each role on the hub.
Resource Role-Permissions View and edit the role-permission assignments for each role on the hub with respect to a single securable resource: a project tree, project, analysis, launchd group, launch daemon, named search, saved chart, warning processor, report template, or role.
Role Ancestors View the set of ancestor roles for a role; edit the set of parent roles; edit the role name and description.
Role Users View the set of directly and indirectly assigned users for a role; edit direct user assignments; edit the role name and description.
Roles View all roles on the hub; delete roles; add new roles.
Security Dashboard View security suggestions for the hub; link to security functionality.
Sign In: Sign In tab Sign in to a hub user account using a password or certificate.
Sign In: Create Account tab Create a single hub user account based on the default template user. Signs you into the new account if it has G_SIGN_IN and G_SIGN_IN_PASSWORD permissions. Only available for anonymous sessions.
User Certificates Manage the TLS certificates for a single hub user account.
User Roles View the set of directly and indirectly assigned roles for a user; edit direct assignments.
User Sessions View the set of current sessions for a user; add and delete sessions.
Users List all user accounts on the hub; navigate to their account editor pages; set the default template user.
Tasks and Tutorials
Tutorial: Add a custom hub authentication plug-in
Task: Add a new user account for another user
Task: Add a new user account for yourself
Task: Activate or deactivate a user account
Task: Configure 'Windows Login' hub authentication
Task: Grant select users access to a project
Task: Lock down a hub
Task: Modify a role's permissions
Task: Modify a user's roles (and therefore their permissions)
Other Manual Sections
Custom Hub Authentication Plug-Ins
Hub User Accounts
TLS Certificates
 

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