Configure User Manager Authentication

R2026b

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, use one of these methods.

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.
Connect your company Security Assertion Markup Language (SAML) identity provider (IdP) to provide single sign-on (SSO) capabilities for Polyspace Access.
Create custom identities. See Manage Users and Groups. Create custom identities if, for instance, you cannot or choose not to use your company LDAP.

Configure your User Manager settings in the .env file for your Docker installation. After you configure or update your User Manager settings, stop and remove running services with the command docker compose down. Use the command docker compose up to start all services.

General User Manager Settings

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

Local User Manager Database Settings

Set the COMPOSE_PROFILES variable in the .env file to contain the localdb_all or localdb_users profile to start the bundled PostgreSQL container for the User Manager database.

Set these variables in the .env file to manage your local database volume.

Variable	Description	Default
`USERMANAGER_DB_VOLUME`	Full path to the database volume. The database stores information about users and groups that you import from the LDAP server or that you create in the User Manager interface.	`${DATA_DIR}/usermanager/db`
`USERMANAGER_DB_USER`	Username for the database user. Use the username that you specify for this variable if you need to interact with the internal database by using PostgreSQL commands.	`um`
`USERMANAGER_DB_PASSWORD`	Password for the database user. Use the password that you specify for this variable if you need to interact with the internal database by using PostgreSQL commands. This variable is mandatory.	`admin`

To see the current database password, run this command:

docker inspect usermanager-db-0-main | grep UMDB_PASSWORD

To change the database password, update the password twice:

Enter the new password for this variable 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

psql (16.13 (Debian 16.13-1.pgdg13+1))
Type "help" for help.

umdb-# \password
Enter new password for user "um": <yourNewPassword>
Enter it again: yourNewPassword

The argument of option --username should match the username that you specified for USERMANAGER_DB_USER.

External User Manager Database (Optional)

To connect to an external database:

A role with the username specified by USERMANAGER_DB_USER must exist.
An external database named umdb must exist with owner set to the value of USERMANAGER_DB_USER.

The following tables must exist in the external database umdb and be owned by the value of USERMANAGER_DB_USER:

CREATE TABLE identity(id text NOT NULL CHECK (id <> ''),
  source text NOT NULL CHECK (source <> ''),
  type text NOT NULL CHECK (type <> ''),
  display_name text, email text, image_uri text,
  PRIMARY KEY (id, source));

CREATE TABLE password(id text NOT NULL,
  source text NOT NULL,
  password text NOT NULL,
  PRIMARY KEY (id, source),
  FOREIGN KEY (id, source) REFERENCES identity(id, source)
  ON DELETE CASCADE);

If these prerequisites are met, set these variables in the .env file:

Variable	Description	Default
`USERMANAGER_DB_HOST`	Hostname for the external database.
`USERMANAGER_DB_PORT`	Port used to communicate with the external database.	`5432`
`USERMANAGER_DB_USER`	Admin username. The admin username must be the owner of the `umdb` database and the tables identity and password described above.	`um`
`USERMANAGER_DB_PASSWORD`	Password for the database user.	`admin`
`USERMANAGER_DB_SSL_ENABLE`	Option to enable SSL for database connection. This variable must be set to `true` for Amazon RDS.	`false`
`USERMANAGER_DB_SSL_CA_FILE`	CA file for the database SSL connection, for example `rds-ca.pem`. Specifying this variable is mandatory for Amazon RDS.

Admins

Configure which users have administrator privileges and set their initial passwords.

Variable	Description	Default
`USERMANAGER_ADMIN_IDS`	Comma-separated list of users that have administrator rights. Surround each username with double quotes and enclose the entire list with square brackets, for example, `["admin", "auser"]`.	`["admin"]`
`USERMANAGER_ADMINS_PASSWORD`	Initial password for administrators. Setting an initial password is required only when `AUTHN_TYPE=internal`. Admin users should change their passwords immediately.	`admin`

For more information about Polyspace Access administrators, see Manage Project Permissions.

You can specify custom usernames or usernames from your company LDAP. See Create, Edit, or Remove Users and Groups.

Note

If AUTHN_TYPE is set to ldap, at least one of the usernames that you specify for this variable must be from the LDAP directory or must already exist in the User Manager database. Otherwise, you cannot log into the User Manager interface.

To remove a user as a Polyspace Access administrator, remove the username from the USERMANAGER_ADMIN_IDS variable, save your changes, and restart the services.

After the restart, an active Polyspace Access administrator must unassign the removed admin 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 polyspace-access -unset-role command.

Authentication

These variables determine the session and security behavior of the User Manager authentication.

Variable Description Default

Variable	Description	Default
`USERMANAGER_AUTH_TOKEN_EXPIRATION`	Duration in seconds of the signed JSON Web Tokens issued to authenticated users. The 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. Use this variable 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. When you set the expiration time, keep in mind these considerations: 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.	`3600`
`USERMANAGER_SSL_KEY_FILE`	Full path to the private key PEM file used by User Manager to sign JSON Web Tokens. 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.	`${CERT_DIR}/um-key.pem`
`USERMANAGER_APIKEYS`	API key-to-user mappings in this JSON format: {"key1":{"principal":"user1"},"key2":{"principal":"user2"}} For example, to assign an API key to user `jsmith`, enter: USERMANAGER_APIKEYS={"5ea34345-a03b-4a20-821e-f10e45e0e863":{"principal":"jsmith"}} To assign API keys to other users, enter additional API key and username pairs separated by a comma. 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-results-export` (Polyspace Bug Finder) `polyspace-results-export` (Polyspace Code Prover) `polyspace-report-generator` (Polyspace Bug Finder) `polyspace-report-generator` (Polyspace Code Prover) polyspace-access When using the API key, store the API key in a text file and pass that file to the command by using the `-credentials-file` option. 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 Then pass the file to the command: polyspace-access -credentials-file credentials.txt Alternatively, pass the API key directly at the command line by using the `-api-key` option. The commands use the API key as a login credential for the corresponding user. If a user updates their 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.	`{}`

USERMANAGER_AUTH_TOKEN_EXPIRATION

Duration in seconds of the signed JSON Web Tokens issued to authenticated users. The 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.

Use this variable 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.

When you set the expiration time, keep in mind these considerations:

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.

3600

USERMANAGER_SSL_KEY_FILE

Full path to the private key PEM file used by User Manager to sign JSON Web Tokens.

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.

${CERT_DIR}/um-key.pem

USERMANAGER_APIKEYS

API key-to-user mappings in this JSON format:

{"key1":{"principal":"user1"},"key2":{"principal":"user2"}}

For example, to assign an API key to user jsmith, enter:

USERMANAGER_APIKEYS={"5ea34345-a03b-4a20-821e-f10e45e0e863":{"principal":"jsmith"}}

To assign API keys to other users, enter additional API key and username pairs separated by a comma. 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-results-export (Polyspace Bug Finder)
polyspace-results-export (Polyspace Code Prover)
polyspace-report-generator (Polyspace Bug Finder)
polyspace-report-generator (Polyspace Code Prover)
polyspace-access

When using the API key, store the API key in a text file and pass that file to the command by using the -credentials-file option. 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

Then pass the file to the command:

polyspace-access -credentials-file credentials.txt

Alternatively, pass the API key directly at the command line by using the -api-key option.

The commands use the API key as a login credential for the corresponding user. If a user updates their 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.

Authentication Type

Set the AUTHN_TYPE variable to one of the following values:

internal — Use the Polyspace Access User Manager internal directory.
ldap — Authenticate users against your company LDAP directory.
saml — Authenticate users using a SAML IdP.

Connect Your Organization LDAP Server to the User Manager

To use the LDAP server of your organization, configure the LDAP settings in your .env file. Contact your LDAP administrator to obtain the LDAP URL, LDAP user base, and other LDAP settings and filters. Your Docker containers must inherit DNS settings from the host.

Polyspace Access does not support cipher suites that use RSA based key exchange and 3DES cipher suites due to known weaknesses in these cipher suites. Upgrade your LDAP server configuration to use a secure cipher suite, such as an ECDHE-based cipher suite, before connecting your LDAP server to User Manager.

LDAP Settings

Configure the following variables if AUTHN_TYPE is set to ldap or saml. These variables are ignored if AUTHN_TYPE is set to internal.

LDAP Connection Settings

Variable	Description	Default
`LDAP_PROTOCOL`	LDAP protocol, specified as `ldap` or `ldaps`.	`ldap`
`LDAP_USE_SSL`	Option to enable SSL for the LDAP connection, specified as `true` or `false`.	`false`
`LDAP_HOST`	URL of your LDAP server. Enter the LDAP URL as: ldap://HOST If you have configured your LDAP server over SSL, enter the URL as: ldaps://HOST 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, configure and use LDAP over SSL (LDAPS).
`LDAP_PORT`	Port used to communicate with the LDAP server.

LDAP User Settings

Variable	Description
`LDAP_USER_BASE`	Base DN (Distinguished Name) for user searches. You can retrieve the Base DN 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`	Search filter for user lookups. 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 example, `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.
`LDAP_USER_ID_ATTRIBUTE`	LDAP attribute for the user ID. Leave this variable unchanged unless instructed otherwise by your LDAP administrator. Polyspace Access does not use the LDAP email and image attributes.
`LDAP_USER_DISPLAYNAME_ATTRIBUTE`	LDAP attribute for the user display name. Leave this variable unchanged unless instructed otherwise by your LDAP administrator. Polyspace Access does not use the LDAP email and image attributes.
`LDAP_USER_EMAIL_ATTRIBUTE`	LDAP attribute for the user email address. Leave this variable unchanged unless instructed otherwise by your LDAP administrator. Polyspace Access does not use the LDAP email and image attributes.
`LDAP_USER_IMAGE_ATTRIBUTE`	LDAP attribute for the user profile image. Leave this variable unchanged unless instructed otherwise by your LDAP administrator. Polyspace Access does not use the LDAP email and image attributes.

LDAP Group Settings

Variable	Description
`LDAP_GROUP_BASE`	Base DN for group searches. You can retrieve the Base DN 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 and then open the properties for that group.
`LDAP_GROUP_SEARCH_FILTER`	Search filter for group lookups. 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 example, `CN=test*` matches all groups that 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 attribute for the group ID. Leave this variable unchanged unless instructed otherwise by your LDAP administrator.
`LDAP_GROUP_DISPLAYNAME_ATTRIBUTE`	LDAP attribute for the group display name. Leave this variable unchanged unless instructed otherwise by your LDAP administrator.
`LDAP_GROUP_MEMBERSHIP_ATTRIBUTE`	LDAP attribute for group membership. Leave this variable unchanged unless instructed otherwise by your LDAP administrator.

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 gateway CA file. If you configured the gateway with HTTPS, the LDAP SSL certificate might already be included in your CA file. See Gateway Settings.

For instance, on Linux, 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 contents of the two files into the output 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, set GATEWAY_SSL_CA_FILE in the .env file to point to the combined certificate file and restart the services:

docker compose down
docker compose up -d

If you did not configure the gateway with HTTPS, set GATEWAY_SSL_CA_FILE to the path of the LDAP SSL certificate.

Configure Single Sign-On (SSO) Authentication

In Polyspace Access, you can configure authentication using a Security Assertion Markup Language (SAML) identity provider (IdP). For more information about SAML, see the OASIS SAML Wiki.

You must fill out the LDAP settings in addition to the SAML settings. Filling out the LDAP and SAML settings synchronizes the LDAP identities, SAML settings, and the Polyspace Access User Manager. It also provides the ability to assign permissions to users and assign results to users for review. For more information about the LDAP settings, see Connect Your Organization LDAP Server to the User Manager.

To configure SAML:

Your organization's IdP must follow the SAML protocol.
You must have access to your IdP. To obtain access, contact your identity management administrator.
Your IdP hosts an endpoint for its SAML metadata.

When using SSO, the SSO service cannot authenticate users you manually add to the User Manager from the user manager dashboard when they log in using a web browser. You must add these individual users to your organization's IdP for SSO to properly authenticate their login.

SAML Connection Settings

Set these variables in your .env file. These variables are ignored when AUTHN_TYPE=internal.

Variable	Description
`SAML_IDP_METADATA`	URL to your IdP's SAML metadata. Required for both SP-initiated and IdP-initiated single sign-on.
`SAML_RELYING_PARTY`	The Entity ID registered with your IdP. Set this to the base URL of your Polyspace Access server (for example, `https://polyspace.example.com`). This value is sent as the Issuer in SAML AuthnRequests.
`SAML_CORS_DOMAINS`	String array of identity provider origin URLs needed for cross-origin communication. Required when the identity provider origin differs from the Polyspace Access server origin. Without this variable, the IdP's SAML response POST to the ACS URL is rejected with a 403 Forbidden error.
`SAML_BINDING_ATTRIBUTE`	Binding method for sending authentication requests to the IdP, specified as `"POST"` (HTTP POST) or `"Redirect"` (HTTP Redirect). The HTTP Redirect method sends request data as query parameters in the URL, whereas the HTTP POST method sends data more securely in the request body.

SAML User Settings

Variable	Description
`SAML_USER_ID_ATTRIBUTE`	SAML assertion attribute that contains the username or user ID. When the server checks out a license, the value from this attribute appears in license server logs.
`SAML_USER_DISPLAYNAME_ATTRIBUTE`	SAML assertion attribute that contains the user display name. The value from this attribute appears in the Polyspace Access user interface.
`SAML_USER_EMAIL_ATTRIBUTE`	SAML assertion attribute that contains the user email address. Leave this variable unchanged unless instructed otherwise by your identity management administrator.
`SAML_USER_IMAGE_ATTRIBUTE`	SAML assertion attribute that contains the user profile image URI. Leave this variable unchanged unless instructed otherwise by your identity management administrator.