Configure User Manager

The User Manager manages the authentication of the Polyspace^® Access user logins. The logins are authenticated by checking the usernames and passwords against the credentials of identities that you store in the User Manager database. To add identities to the User Manager database, do one of the following.

Connect your company Lightweight Directory Access Protocol (LDAP) server to the User Manager and import identities from the LDAP server. To configure the connection with the LDAP server, see Connect Your Organization LDAP Server to the User Manager.
Create custom identities. See Manage Users and Groups. Create custom identities if, for instance, you cannot or choose not to use your company LDAP.

On the Cluster Dashboard, click Configure Apps to go to the Cluster Settings. Whenever you change the settings, click Save, return to the Cluster Dashboard, and click Restart Apps for the changes to take effect. Make sure that Validate on Save is enabled before you click Save.

Note

On Windows^® systems, all the file paths that you specify must point to local drives.

Prerequisites

Install and start the Cluster Admin. See Configure and Start the Cluster Admin

General User Manager Settings

These settings are required whether you create custom user credentials or you import users from your company LDAP server.

Setting	Description
Internal directory database volume	Specify the full path to the database folder. The database stores information about users and groups that you import from the LDAP server or that you create in the User Manager interface. By default, the database is stored in the folder where you extracted the Polyspace Access installation image, under `appdata/usermanager`. For instance, `/local/usr/Access/R2024b/appdata/usermanager/db`.
Internal directory database username	Use the username that you specify in this field if you need to interact with the internal database by using PostgreSQL commands. The default username is "UM".
Internal directory database password	Use the password that you specify in this field if you need to interact with the internal database by using PostgreSQL commands. This field is mandatory. To see the current database password, run this command. Windows `docker inspect usermanager-db-0-main \| FIND "UMDB_PASSWORD"` Linux `docker inspect usermanager-db-0-main \| grep UMDB_PASSWORD` To change the database password, update the password twice: Enter the new password in this field to change the password in the Polyspace Access settings. Run this command on the machine where you installed Polyspace Access to update the password in the postgres database: `docker exec -it usermanager-db-0-main psql --username um --dbname umdb -c "ALTER ROLE um WITH PASSWORD 'yourNewPassword'"` The argument of option `--username` should match the username that you specified in the field Internal directory database username.
Administrator sign-in IDs	Enter a comma-separated list of usernames to set those users as User Manager administrators. You can specify custom usernames or usernames from your company LDAP. See Create, Edit, or Remove Users and Groups. Note If you enable Connect an LDAP directory, at least one of the usernames that you specify in this field must be from the LDAP directory or must already exist in the User Manager database. Otherwise, you cannot log into the User Manager interface. The users that you specify in this field are also Polyspace Access administrators. For more information about Polyspace Access administrators, see Manage Project Permissions. To remove a user as a Polyspace Access administrator: Remove the username from this field, save your changes, then restart the apps. After the restart, a Polyspace Access administrator must unassign the user from all top-level folders in the Project Explorer, in the Polyspace Access web interface, by using the context menu. The administrator can also perform this task at the command line by using the `-unset-role` flag with the `polyspace-access` binary. For more information, see `polyspace-access`.
Initial administrator password	Password that you use to log into the User Manager interface. This field is not available if you select Connect an LDAP directory in the User Manager Directory Connection settings.
Authentication token expiration (sec):	Specify in seconds the period of validity of the signed JSON Web Tokens that the User Manager issues to authenticated users. This expiration time determines the lifetime of a session. Once you log into Polyspace Access, your license is checked out and your session refreshes periodically to keep it from expiring. The session ends once you explicitly log out or close your web browser and your license is checked back in. If your browser closes unexpectedly, your license stays checked out until the session expires. When you set the expiration time, consider: If the expiration time is too short, frequent users are prompted to log back in frequently. On large teams, the license server experiences a high volume of license checkins and checkouts. If the expiration time is too long, the session time of less frequent users might be overestimated in the license logs. Use this setting to set the licensing timeout. Polyspace Access ignores the license timeout value that you set through the license manager options file (`MLM.opt`) by using the `TIMEOUT feature seconds` syntax.
Authentication private key file:	Specify the full path to the private key `PEM` file that the User Manager uses to sign JSON Web Tokens. On Windows systems, the paths must point to local drives. The User Manager service does not support password-protected private keys. You can generate a private key by using the `openssl` utility. For example: openssl genrsa -out private.pem 2048 Restrict access to this private key to only those administrators who manage the User Manager service. Do not reuse the private key that you use to generate the SSL certificates, which you provide if you enable the HTTPS protocol.
API keys and user IDs	Enter an API key value and username pair in this field to assign an API key to a user. For example, to assign an API key to user `jsmith`, enter: 5ea34345-a03b-4a20-821e-f10e45e0e863,jsmith To assign API keys to other users, enter additional API key and username pairs on separate lines. Each API key value must be unique. You can assign any combination of alphanumeric characters as an API key to a user. For example, to generate universally unique identifiers (UUID) for the API key, use these commands: Windows PowerShell: `[guid]::NewGuid()` Linux^®: `uuidgen` Use the API key with these commands that require Polyspace Access credentials: `polyspace-access` `polyspace-results-export` (Polyspace Bug Finder)`polyspace-results-export` (Polyspace Code Prover) `polyspace-report-generator` (Polyspace Bug Finder) `polyspace-report-generator` (Polyspace Code Prover) When using the API key, it is recommended that you store the API key in a text file and pass that file to the command by using `-credentials-file`. For example, to use the API key for user `jsmith`, store this line in text file `credentials.txt`: -api-key 5ea34345-a03b-4a20-821e-f10e45e0e863 and then pass the file to the command, for instance: polyspace-access -credentials-file credentials.txt Alternatively, pass the API key directly at the command line by using `-api-key`. The commands use the API key as a login credential for the corresponding user. If a user updates his or her password, you do not have to update the API key. If you use the API key as part of an automation script, make sure that the user associated with the key has enough permissions to perform all the operations in the script. See Manage Project Permissions.

To create or manage identities, see Manage Users and Groups.

Connect Your Organization LDAP Server to the User Manager

To use the LDAP server of your organization, in the User Manager Directory Connection settings, select Connect an LDAP directory and configure the LDAP settings. Contact your LDAP administrator to obtain the LDAP URL, LDAP user base, other LDAP settings and filters, and to determine whether your LDAP server uses the Active Directory Global Catalog feature.

Setting	Description
LDAP URL	Enter the LDAP URL as: ldap://HOST:PORT `HOST` is the LDAP host and `PORT` is the LDAP port number. The LDAP server uses different default port numbers if you configure it to use the global catalog. See Configure User Manager for LDAP Server That Uses Global Catalog. If you have configured your LDAP server over SSL, enter the URL as: ldaps://HOST:PORT For additional LDAPS configuration steps, see Configure the User Manager for LDAP over SSL. Because communications between the LDAP server and clients are not encrypted, the configuration and use of LDAP over SSL (LDAPS) is recommended.
Synchronization interval (seconds)	Specify in seconds the interval between synchronizations of the User Manager database with the LDAP server. For instance, specify 1800 to synchronize the User Manager database with the LDAP server every half hour. To synchronize manually, click Synch With LDAP in the User Manager interface.
LDAP username	username of user who has read permission to the LDAP server. Leave this field blank if your access to the LDAP server is not password-protected.
LDAP password	Password of user who has read permission to the LDAP server. Leave this field blank if your access to the LDAP server is not password-protected. The password is stored in the `settings.json` file. For added security, set restrictions on the read and write permissions for this file. By default, this file is stored in the same folder as the `admin-docker-agent` binary.
Enable LDAP pagination	Enable this setting to control the rate at which your LDAP server returns results. You typically use this setting if you query a large set of users and the LDAP server has limits on the number of entries that it returns, or if the client making the query has limited resources. Before you enable this setting, check that: Your LDAP server supports simple paged results control. See LDAP Control Extension for Simple Paged Results Manipulation. If you provide an LDAP username and LDAP password, pagination is not disabled for these credentials. The User Manager log shows LDAP result code 11 when pagination is disabled for the credentials that you provide. The LDAP server is configured to handle a reasonable number of simultaneous paged queries. The User Manager log shows LDAP result code 53 if the number of simultaneous queries exceeds the LDAP server limit.
LDAP page size	Set the number of results that the LDAP server returns per page, for example 1000. This setting is available only if you select Enable LDAP pagination.
LDAP user base	You can retrieve this parameter by using an LDAP explorer tool. For instance, connect to your LDAP server through Apache Directory Studio and open the properties for your connection. In the Browser Options, click Fetch Base DNs to get the LDAP base.
LDAP user search filter	Use the search filter to retrieve a subset of users from the LDAP database. The User Manager loads this subset on startup instead of loading all users in your organization. Loading a smaller number of users for authentication improves the performance of Polyspace Access. Specify the search filter as `attribute`=`value`, for instance `CN=test` matches all users who have a common name (CN) attribute that starts with "test". Use parentheses to combine multiple filter expressions in an AND (&) or OR (\|) clause. For instance, `(\|(CN=jdoe)(department=foo))` matches all users who have CN attribute "jdoe" or department attribute "foo". The default search filter is `objectClass=organizationalPerson`. For more information about search filters, see the LDAP filters. To check whether a search filter is returning a subset of users, enter a username from that subset in the API keys and user IDs* field along with a dummy key, and click Validate Now at the bottom of the page. You get a warning if the username cannot be found. For instance, to check if the filter returns `jsmith`, enter `1234,jsmith`.
LDAP user ID attribute LDAP user display name attribute LDAP user email attribute LDAP user image attribute	Leave these settings unchanged unless instructed otherwise by your LDAP administrator. Polyspace Access does not use the LDAP email and image attributes.
Enable LDAP groups	Enable this setting to import user groups from the LDAP server directory.
LDAP group base	You can retrieve this parameter by using an LDAP explorer tool. For instance, connect to your LDAP server through Apache Directory Studio and search for a group that you want to import, then open the properties for that group.
LDAP group search filter	Use the search filter to retrieve a subset of groups from the LDAP database. The User Manager loads this subset on startup instead of loading all the groups in your organization. Loading a smaller number of groups improves the performance of Polyspace Access. Specify the search filter as `attribute`=`value`, for instance `CN=test*` matches all groups who have a common name (CN) attribute that starts with "test". Use parentheses to combine multiple filter expressions in an AND (&) or OR (\|) clause. For instance, `(\|(CN=Printers)(location=US))` matches all groups that have CN attribute "Printers" or location attribute "US". For more information about search filters, see the LDAP filters.
LDAP group ID attribute LDAP group display name attribute LDAP group membership attribute	Leave these settings unchanged unless instructed otherwise by your LDAP administrator. Polyspace Access does not use the LDAP display name attribute.

Configure the User Manager for LDAP over SSL

If you use an LDAP server configured over SSL (LDAPS), add the LDAPS SSL certificate to the certificate trust store file that you specify in the CA File field of the Nodes settings. To view these settings, click Configure Nodes on the Cluster Dashboard. Depending on your trust store file, the LDAP SSL certificate might already be included in the trust store.

The certificate trust store file typically corresponds to the file that you provide with --ssl-ca-file when you configure the Cluster Admin with HTTPS. See Choose Between HTTP and HTTPS Configuration for Polyspace Access.

For instance, on a Linux Debian^® distribution, to add LDAP certificate ldaps_cert.pem to trust store file trust_store.pem, use this command:

cat trust_store.pem ldaps_cert.pem > combined_cert.pem

The command combines the content of the two files and outputs file combined_cert.pem. If you use a self-signed certificate to configure HTTPS, add the LDAP certificate to the self-signed certificate.

To complete the configuration, enter the path to combined_cert.pem in the CA File field of the Nodes settings, save your changes, return to the dashboard, and restart the Apps.

If you did not configure the Cluster Admin by using HTTPS, specify the path to the LDAP SSL certificate in the CA File field.

Configure User Manager for LDAP Server That Uses Global Catalog

The global catalog (GC) is a mechanism that enables you to add users from different Active Directory^® (AD) servers to Polyspace Access without having to provide information about those servers. For more information, see Global Catalog. If your LDAP server is configured to use the GC, you must specify a GC-specific port number when you provide the LDAP URL to the User Manager service. The default port is 3268 or, if you use secure LDAP (LDAPS), 3269. To determine whether your LDAP server is configured to use the GC, contact your LDAP administrator.

If you specify an incorrect port number, the User Manager service cannot communicate with the LDAP server. When you inspect the User Manager log, you get error messages similar to these error messages.

LDAP server 'ldap://server01.example.com:389' did not recognize 
base DN 'DC=example,DC=com' and search base ''.
...
Unprocessed Continuation Reference(s)

To save the User Manager log to a file out.log, use this command.

docker logs -t usermanager-server-0-main >> out.log 2>&1

Note

If you run Polyspace Access™ version R2021b or earlier, the docker container names might be different. To view the names of currently running containers, use command docker ps --format '{{.Names}}'.

The GC holds only a subset of attributes for each user from the different Active Directory (AD) servers. The LDAP ID attribute that you specify in the cluster operator settings must be available in this subset of attributes when the GC is enabled. If the LDAP ID is not available in the GC, the corresponding user is not added to Polyspace Access.