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

Authentication Plug-Ins Shipped With CodeSonar

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.

CodeSonar ships with several plug-ins for common authentication schemes. This section described the shipped plug-ins.

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

CodeSonar ships with several authentication plug-ins, summarized in the following table. Plug-in availability depends on the operating system under which the hub is running. For example, a hub running on a Windows machine can be configured to use Microsoft Windows Login authentication. Once it is configured, users will be able to sign into the hub with their Windows username/password combinations (provided they have any), regardless of the operating systems they are using.

Authentication Type Hub Machine OS
LDAP all OSes
SSO SAML all OSes
OIDC all OSes
Linux/Unix Login all OSes except Windows
Windows Login Windows

All hub authentication plug-ins are located in directory $CSONAR/codesonar/py/hub/auth/, and are available for configuration on all hubs running from that CodeSonar installation.

LDAP (Lightweight Directory Access Protocol)

Availability All supported hub OSes.
Requirements An LDAP server must already be set up. We strongly recommend that the person configuring the authentication service be highly familiar with the local LDAP system.
Service Type LDAP
Service-Specific Configuration
Server Hostname  The hostname of the LDAP server to be used for authentication.
Server Port  The port on which the LDAP server is running.
Encryption Method <method> The encryption method that the hub's LDAP client will use to connect to the LDAP server specified by Server Hostname and Server Port.
  • No Encryption
  • Use SSL (ldaps://)
  • Use StartTLS
Reject certificates with wrong hostname [Only applicable if Encryption Method is "Use SSL" or "Use StartTLS"]
Specifies whether the specified Server Hostname must match the hostname in the LDAP server's certificate.
  • Selected: the hub's LDAP client will only accept the LDAP server's certificate if the hostnames match.
  • Deselected: the hub's LDAP client will always accept the LDAP server's certificate.
If the LDAP server's certificate is not already trusted by the hub, Submitting the configuration form will cause the page to display error message "LDAP Error: Untrusted SSL certificate in the certificate chain" above the heading. To resolve this:
  1. Scroll down to the Encryption Method field of the configuration form.
  2. Inspect the certificate contents.
  3. If you are satisfied that the certificate is trustworthy, select "Add an exception for the following certificate" and click Submit.
Referrals Specifies whether or not the hub's LDAP client should follow LDAP referrals when performing the authentication.
  • Selected: the hub's LDAP client will follow LDAP referrals. User authentication will cover objects stored directly at or below the search base specified by Base DN, plus objects defined in any partitions identified by (transitive) referrals within that search base.
  • Deselected: the hub's LDAP client will not follow LDAP referrals. User authentication will only cover objects stored directly at or below the search base specified by Base DN.
Bind DN User DN An LDAP bind DN with sufficient permissions to perform the LDAP operations involved in hub user authentication.
Can be left blank if your LDAP server permits anoymous binding.
Password The password corresponding to User DN (will not be displayed).
Base DN The LDAP base DN for performing hub user authentication. UID Attribute values under this DN should be unique.
UID Attribute The LDAP attribute that uniquely identifies a user. If LDAP authentication is successful, the user will be signed into the hub user account with this username.
Email Attribute The LDAP attribute that corresponds to a user's email address. This will be used as the hub user account email for any accounts automatically created by the plug-in (when automatic account creation is enabled). For existing users, behavior depends on account settings.
Leave blank if you do not want the LDAP authentication service to provide the hub with user email addresses.
Filter An optional LDAP search filter to be used to restrict hub authentication to a subset of the users in the LDAP database. Some example filters:
  • (|(manager=Steve)(englevel=2))
    Only authenticate users with at least one of manager=Steve, englevel=2.
  • (&(manager=Steve)(englevel=2))
     Only authenticate users with both manager=Steve and englevel=2.
  • (!(uid=Administrator))
    Don't authenticate the LDAP user with uid=Administrator (for example, because it is not the same person as the hub Administrator).
Leave blank if you do not want to specify a filter.
Enable Automatic Role Mapping? Specifies whether or not the role mappings specified in Role Mapping List should be applied.
This feature is only supported in Microsoft Active Directory.
Role Mapping Base DN The LDAP base DN for performing role mapping. All role mapping groups should be under this base DN.
Role Mapping List Optional mappings from LDAP groups to CodeSonar role assignments. The mappings are specified as a list of mapping entries:
  • One entry per line.
  • The form of each entry is one of the following.
    ldap_dn : codesonar_rbac_role where
    • ldap_dn is a group DN (distinguished name) on your LDAP server, and
    • codesonar_rbac_role is a CodeSonar role that you want to assign to all hub user accounts whose corresponding LDAP user DN includes ldap_dn.

    For example:

    CN=Engineer,CN=Users,DC=ad1,DC=mycompany : User
    specifies that all hub user accounts whose corresponding LDAP user DN includes CN=Engineer,CN=Users,DC=ad1,DC=mycompany should be assigned the built-in User role.
    ldap_dn where
    • ldap_dn is a group DN (distinguished name) on your LDAP server, and
    • the first RDN in ldap_dn is a pair att=val, and
    • val is a CodeSonar role that you want to assign to all hub user accounts whose corresponding LDAP user DN includes ldap_dn.

    For example:

    CN=Engineer,CN=Users,DC=ad1,DC=mycompany
    specifies that all hub user accounts whose corresponding LDAP user DN includes CN=Engineer,CN=Users,DC=ad1,DC=mycompany should be assigned the Engineer role, if it exists.
  • If you want to map an LDAP role to multiple CodeSonar roles, make a separate entry for each.
  • If a mapping entry specifies a CodeSonar role that does not exist on the hub, that entry has no effect.
  • Only group DNs can be specified in mappings. If an entry specifies a DN for a user or organizational unit, it will have no effect.

In combination with Enable Automatic Role Mapping?, these mappings specify how to adjust the set of Roles for a hub user account when the user logs into the hub with the LDAP authentication plug-in.

  • If Enable Automatic Role Mapping? is not selected, the set of Roles is not updated.
  • If Enable Automatic Role Mapping? is selected, the set of Roles is updated as follows.
    • If the hub user account has any roles that were assigned by this plug-in at a previous login but now are not mapped to any LDAP group containing the user, those roles are removed from the hub user account.
    • All CodeSonar roles that are mapped to any LDAP group containing the user are added to the hub user account.
Example Configuration Note that LDAP configurations vary widely: the values in this example may differ markedly from those you will use.
Server Hostname ldap.example.com
Server Port 389
Encryption Method <method> No Encryption
Reject untrusted certificates n/a
Bind DN User DN cn=Admin, cn=IT, cn=Employees, dc=example, dc=com
Password mymothersbirthday
Base DN cn=Engineering, cn=Employees, dc=example, dc=com
UID attribute name
Email attribute email
Filter empty
Further Information Refer to your local LDAP documentation for information specific to your installation and configuration. For general LDAP information, a good starting point is the General LDAP FAQ.

This plug-in will not be applied if users enter an empty password when signing in.

SSO SAML

The SSO SAML plug-in allows you to use a existing Single Sign-On (SSO) service for hub authentication.

There are two steps to configuring SSO authentication for your hub. First, use the Authentication Services page to configure the SSO SAML plug-in. Second, use the information provided by the hub to configure your SSO identity provider (IdP) to work with your hub.

Availability All supported hub OSes.
Requirements An SSO identity provider that supports SAML must already be set up. We strongly recommend that the person configuring the authentication service be highly familiar with the local SSO system.
Service Type SSO SAML
Service-Specific Configuration The plug-in requires several pieces of information to configure an authentication service for a CodeSonar hub.
IdP Metadata Information about the SSO Identity Provider (IdP). There are two options for providing this information.
Option 1: Provide IdP Metadata URL
Metadata URL The metadata URL for the IdP.
This option is more convenient, but requires that your hub be able to make requests to the IdP server. In particular, you will not be able to use this option if your system is configured so that the hub cannot make outgoing connections.
Option 2: Manually Enter IdP Metadata
Entity ID The entity ID for the IdP. This is typically some variation of the hostname.
Single Sign On URL The IdP URL to which the hub should redirect users for SSO authentication.
IdP Signing Certificate The certificate that the IdP uses to sign responses. If there are multiple such certificates, you will need to provide the IdP metadata URL instead of manually entering metadata.
Requests Whether or not the hub should sign requests sent to the IdP.
  • Do not select unless the hub is configured with a SSL/TLS hub server certificate and HTTPS is enabled.
  • The IdP must be configured to accept signed requests from the hub. This includes providing it with the hub server certificate (but not its private key).
    The following table describes how to do this in some common IdPs.
    Okta On the Configure SAML tab for your CodeSonar App Integration, click Show Advanced Settings and populate the following fields.
    • Signature Certificate: the hub server certificate.
    • Signed Requests: selected.
    Keycloak do not select
    Azure AD Note: You will need to convert the hub server certificate to .cer format for importing.

    In Single sign-on, scroll to the SAML Certificates section, click Edit next to the Verification certificates heading, then make the following changes.

    • Select Require verification certificates.
    • Click Upload certificate and import the hub server certificate.
Signed Responses Whether or not the hub should require that responses from the IdP be signed. The IdP must be configured to send signed responses to the hub. The following table describes how to do this in some common IdPs.
Okta On the Configure SAML tab for your CodeSonar App Integration, click Show Advanced Settings and populate the following field.
  • Response: Signed.
Keycloak In the Settings tab of Client details, populate the following fields.
  • Sign documents: On
  • Sign assertions : Off
Azure AD In Single sign-on, scroll to the SAML Certificates section, click Edit next to the Token signing certificate heading, then populate the following field.
  • Signing Option: Sign SAML Response
Encrypted Responses Whether or not the hub should require that responses from the IdP be encrypted.
  • Do not select unless the hub is configured with a SSL/TLS hub server certificate and HTTPS is enabled.
  • The IdP must be configured to send encrypted responses to the hub. This includes providing it with the hub server certificate (but not its private key).
    The following table describes how to do this in some common IdPs.
    Okta On the Configure SAML tab for your CodeSonar App Integration, click Show Advanced Settings and populate the following fields.
    • Assertion Encryption : Encrypted.
    • Encryption Certificate: the hub server certificate.
    Keycloak do not select
    Azure AD Note: You will need to convert the hub server certificate to .cer format for importing.

    On the Token encryption page, do the following.

    • Select Import Certificate and import the hub server certificate.
    • Once the certificate is imported, click ... next to the certificate thumbprint status, then select Activate token encryption from the menu that opens.

When you click Add Service, CodeSonar will configure the plug-in according to your specifications and then provide you with the data you will need for the next step: IdP-side configuration.
IdP-Side Configuration Once you have configured the SSO SAML plug-in, you will need to perform some configuration on your IdP.
When a user elects to performs hub authentication with a configured SSO SAML plug-in, they are redirected to the IdP to enter their credentials. The IdP then sends a POST request to the hub to confirm that authentication was successful.
  • SP Entity ID: identifies your hub as the authentication client.
  • Assertion Consumer Service URL: specifies where the SSO service should send the POST request.
  • Information that the POST request must contain ("attribute bindings").
    • user: the hub user account username
    • email: the hub user account email address
  • Information that the POST request may contain ("attribute bindings").
    • roles: a list of roles that should be assigned to the hub user account on behalf of the SSO service.
      If roles is specified, hub user account Roles will be updated as follows when the user logs into the hub with the SSO SAML plug-in.
      • If the hub user account has any roles that were assigned by this plug-in at a previous login but now are not in the roles list, those roles are removed from the hub user account.
      • For each roles list item that is the name of a CodeSonar role, that role is added to the hub user account. (List items that are not the name of a CodeSonar role are ignored.)
      To take full advantage of the role mapping feature, ensure you have CodeSonar roles that correspond to all the roles entries that you want to reflect. See the RBAC: Roles page for more information on creating roles and assigning permissions.

This information is provided in the plug-in's row of the table of current authentication services, in a subsection with heading Setting up this SAML Integration in Your IdP.
SP Entity ID and Assertion Consumer Service URL will be based on the "Public URL" configured for your hub: set this value from the Admin Settings: HTTP tab if you have not already done so.

Configuration steps will depend on your IdP. For some specific examples, see the Task instructions linked below.
Example Plug-In Configuration
Metadata URL https://sso.example.com/saml/metadata
Requests unselected
Signed Responses unselected
Encrypted Responses unselected
Further Information

OIDC

The OIDC plug-in allows you to use a existing OpenID Connect (OIDC) service for hub authentication.

There are two steps to configuring OIDC authentication for your hub. First, use the Authentication Services page to configure the OIDC plug-in. Second, use the information provided by the hub to configure your OpenID Connect Server to work with your hub.

Availability All supported hub OSes.
Requirements An OpenID server must already be set up. We strongly recommend that the person configuring the authentication service be highly familiar with the local OpenID Connect system.
Service Type OIDC
Service-Specific Configuration Note: Before performing the service-specific configuration, do the following. You will need various information about your OIDC client to configure the CodeSonar authentication service.
OIDC Discovery URL The OpenID Connect Discover URL for your OIDC server.
(This URL is provided by the server, rather than by an individual client.)
Client ID The client_id of the OIDC client that you created to manage authentication for your CodeSonar hub.
Client Secret If the OIDC client that you created has a client_secret, copy and paste it here.
If there is no client_secret, leave this field empty.
User Claim The name of the OIDC claim that the plug-in should treat as the hub user account username.
Role Claim If you want to assign user account roles on behalf of the OIDC service, enter the name of the OIDC claim that contains the roles to be assigned. This claim must contain a list of role names.
  • If you want to assign user account roles from the OIDC service but can't identify a suitable OIDC claim, contact CodeSecure support for assistance.
If Role Claim is specified, hub user account Roles will be updated as follows when the user logs into the hub with the OIDC plug-in.
  • If the hub user account has any roles that were assigned by this plug-in at a previous login but now are not in the claim, those roles are removed from the hub user account.
  • For each list item in the claim that is the name of a CodeSonar role, that role is added to the hub user account. (List items that are not the name of a CodeSonar role are ignored.)
To take full advantage of the role mapping feature, ensure you have CodeSonar roles that correspond to all the list entries that you want to reflect. See the RBAC: Roles page for more information on creating roles and assigning permissions.
Extra Scopes The OIDC client that you created to manage authentication for your CodeSonar hub will define a number of scopes.
If the claim values you specified for User Claim and Role Claim are not part of the profile scope for your OIDC client, enter the names of any additional scopes that the plug-in will need to request in order to access these claims.

When you click Add Service, CodeSonar will configure the plug-in according to your specifications and then provide you with the data you will need for the next step: OpenID server configuration.
OpenID Server Configuration Once you have configured the OIDC plug-in, the table of current authentication services will update to show an entry for your OIDC plug-in. This entry has a subsection with heading Your OpenID Connect server will need our redirect_uri listed here.
  1. Copy the redirect_uri from this subsection.
  2. On your OpenID Connect server, open the configuration for your OIDC hub authentication client.
  3. Find the field for entering the redirect_uri. Its label might be something like "Sign in redirect URI" or "Valid redirect URI".
    • Its label will not mention "post-logout redirect": that field has a different purpose.
  4. Paste in your copied redirect_uri and save the configuration.
Configuration steps will depend on your OIDC server. For a specific example, see Task: Configure Keycloak (OIDC) Hub Authentication.
Example Plug-In Configuration
OIDC Discovery URL https://openid.example.com/.well-known/openid-configuration
Client ID csonar_hub
Client Secret 12345AlphaNumericStringABC
User Claim unselected
Role Claim empty
Extra Scopes empty
Further Information

Linux/Unix Login

With the Linux/Unix Login plug-in, any existing PAM (Pluggable Authentication Modules) authentication configuration can be used as a hub authentication service.

Availability All supported hub OSes except Windows.
Requirements PAM must be installed on the hub machine, and PAM authentication configuration suitable for hub authentication must exist in /etc/pam.d.
Note that PAM is installed by default on most *ix systems.
Service Type Linux/Unix Login
Service-Specific Configuration The plug-in requires one piece of information to configure an authentication service for a CodeSonar hub.
PAM Service Enter sname to instruct CodeSonar to use the PAM configuration saved at /etc/pam.d/sname.
Example Configuration The login configuration is a standard part of a PAM installation. It is equivalent to checking login credentials for the machine on which PAM is running: the hub machine.
PAM Service login
Further Information OS-specific PAM documentation:

Windows Login

With the Windows Login authentication plug-in, users will be able to sign in to the hub with their Windows credentials (regardless of the operating system they are using).

Availability Windows hubs only.
Requirements The plug-in should be installed by someone familiar with your organization's Windows domain structure.
Service Type Microsoft Windows Login
Service-Specific Configuration The plug-in requires two pieces of information, both related to Windows domain.
User Selects Domain Specifies whether or not users will be able to sign in from a Windows domain other than the one specified for Default Domain.
  • Allow : users can override the default domain by specifying a different one when they sign in.
    For example if the default domain is MYDOMAIN and a user specifies username OTHERDOMAIN\alex when signing in, the service will attempt to perform authentication for OTHERDOMAIN\alex and will, if successful, sign them into the hub user account with username alex.
  • Do Not Allow : users will only be able to sign in with credentials from the default domain.
    For example if the default domain is MYDOMAIN and a user specifies username OTHERDOMAIN\alex when signing in, the service will always fail to authenticate them. (Note that this does not necessarily mean that the user will not be authenticated at all: they may be authenticated by another configured authentication service).
Default Domain The default Windows domain to use for authentication through this service. For example, if the Default Domain is MYDOMAIN and a user specifies username alex when signing in, the service will attempt to perform authentication for MYDOMAIN\alex and will, if successful, sign them into the hub user account with username alex.

Leave empty to indicate the hub machine's local domain.
Example Configuration Suppose an organization has multiple Windows domains, but the hub Administrator only wants to permit Windows Login hub authentication for users in the PROJECTX domain.
User Selects Domain Do Not Allow
Default Domain PROJECTX
Further Information  Task: Configure 'Windows Login' Hub Authentication
 

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