Configure site settings

Configure site settings using the ALM Octane configuration files:

  • The octane.conf settings are mandatory for all environments.

  • In addition, there are other settings that are required in complex ALM Octane environments. These include secure Elasticsearch, proxy settings, and LDAP or SSO authentication, as described below.

These settings are configured during installation, and can also be changed any time, whenever necessary.

Workflow

  1. Configure basic settings by editing the octane.conf file. In addition, depending on your environment, configure the optional files described in the following sections.

    Configuration files must be readable and editable by the user installing ALM Octane, which is generally the octane user. If you copy or edit a configuration file as the root or sudoer user that does not have the necessary installation permissions, the install fails.

    Tip: To change the owner: chown <owner>:<group> <file>

    Examplechown octane:octane octane.conf

  2. If you are installing ALM Octane, after editing your configuration files proceed with Start the ALM Octane server.

  3. If you need to make changes in configuration files later, make sure you edit the <Repository folder>\conf\octane.conf file, and not octane.conf.new, which is a temporary file that is for internal use only.

    After modifying these settings, restart the ALM Octane server on each node to pull the configuration changes from the repository. For details, see Modify site settings in the ALM Octane Help Center.

    For example, you might initially install ALM Octane to use native user management, and at a later time, decide to implement LDAP authentication for user management instead.

Tip: We recommend that you save a local copy of the octane.conf file before making changes to it. Also, for security purposes, octane.conf should be stored in a secure, off-site location.

Back to top

Database server settings

Setting Description
db-type

Enter ORACLE or MSSQL.

connection-string

The Java Database Connectivity (JDBC) database connection string. It includes the following details: database type, database server name, database server port number, service name.

Oracle connection-string

The instructions below demonstrate how to set up the string with non-secured database access. To configure secure access to the database, see Using SSL/SSO in Oracle (optional).

Syntax using service names:

jdbc:oracle:thin:@//DB_SERVER_NAME:DB_SERVER_PORT/DB_SERVICE_NAME

Examples:

  • jdbc:oracle:thin:@//dbserver1.net:1521/orcl
  • jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=dbserver1.net)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=orcl)))

Note:

To connect to Oracle RAC, use the Single Client Access Name (SCAN) instead of the database server name.

 

SQL connection-string

  • Syntax using port:

    jdbc:sqlserver://DB_SERVER_NAME:DB_SERVER_PORT

    Example:

    jdbc:sqlserver://dbserver1:1433

  • Syntax using instance:

    jdbc:sqlserver://DB_SERVER_NAME;instanceName=INSTANCE_NAME

    Example:

    jdbc:sqlserver://dbserver1;instanceName=my_instance

admin-user >  name

ALM Octane uses the admin-user both to create objects during installation and also to check that the database server is accessible.

  • For Oracle, enter the name of the database admin user.
  • For SQL Server, enter the sa user, or an SQL Server power user with the correct permissions.

For details about admin-user permissions, see Prerequisites.

admin-user > password

The password of the database admin user.

Do not include a pound sign (#) or accented characters (such as, ä, ç, ñ).

schemas > 
site

The name of the site schema that is created by the admin-user during the installation, or supplied by the organization's DBA. Enter the supplied name.

schemas > 

initial-shared-space

This parameter is relevant only for the FILL_EXISTING site action.

If you are using FILL_EXISTING, set the initial-shared-space to the name of the schema that is designated for the space.

Using SSL/SSO in Oracle (optional)

You can configure a secure connection from the ALM Octane server to the database server using SSL or SSO.

  1. On the Oracle database server, convert the client wallet to jks keystore:

    orapki wallet pkcs12_to_jks -wallet "<path to client wallet folder>/<client wallet folder name>" -pwd <wallet_password> -jksKeyStoreLoc <name of your jks file>.jks -jksKeyStorepwd <jks_pass>

    For example: 

    orapki wallet pkcs12_to_jks -wallet "/home/oracle19/wallets/client_wallet" -pwd aaa123456 -jksKeyStoreLoc clientstore.jks -jksKeyStorepwd test123#456

  2. Check the content of the newly created jks keystore:

    keytool -list -keystore <name of your jks file>.jks -storepass <jks_pass>

    For example:

    keytool -list -keystore clientstore.jks –storepass test123#456

  3. Copy the client wallet file from the Oracle database server to the ALM Octane Server. Place the newly created keystore jks file in a location on the ALM Octane app server into a directory accessible to all, such as /opt/octane/conf/<name of your jks file>. Grant read permissions on this file to ALM Octane users.

  4. Copy the following to octane.conf, after the connection-string parameter. Replace the values with the specific to your installation:

    connection-properties : [
          {
              "key" : "javax.net.ssl.trustStore",
              "value" : "<full path to keystore file>/<jks keystore file name>.jks"
          }
      ,
          {
              "key" : "javax.net.ssl.trustStoreType",
              "value" : "JKS"
          }
      ,
          {
              "key" : "javax.net.ssl.trustStorePassword",
              "value" : "<jks keystore password>"
          }
      ]
    

Back to top

Oracle server settings

Oracle settings Description
schema-password

The password of the site schema.

When installing using existing site schemas (with the FILL_EXISTING site action), make sure that the passwords that the DBA defines for the site schema and the space schema both match this schema-password.

table-space

The tablespace in the Oracle database where the site schema segment is created. Case-sensitive.

temp-table-space The temporary tablespace in the Oracle database. Case-sensitive.
user-default-sort

Defines whether the standard Oracle binary sort (NLS_SORT="BINARY_CI") should be overridden for non-Latin language support.

Valid values: yes, no, or blank

Default: blank (yes) 

Back to top

SQL server settings

SQL Server settings Description

app-user > name

MSSQL database login authentication user for ALM Octane. This is the user for day-to-day ALM Octane use.

This login is associated with the ALM Octane site and space databases.

Note: This should be different from the admin-user > name. However if you are using FILL_EXISTING, this must be the same as the admin-user name.

app-user > password

The password for the app-user.

If you are using FILL_EXISTING, this must be the same as the admin-user password.

authentication-method Enter the authentication method used: Windows or DB (SQL Server Authentication).

Back to top

Site actions

The site-action setting determines how the installation should handle databases.

CREATE_NEW

Use this site action for new installations.

  • Creates a new site schema, creates a new space schema, and configures the current node.
  • Only an admin-user with create schema permissions can create a new schema.
  • The CREATE_NEW site action fails when the schema already exists.

FILL_EXISTING

Use this site action for new installations, in cases where the database administrator does not give permissions to create a schema (for Oracle) or a database (for SQL Server).

In this case, the organization's DBA must create a new site and space schema/database and users before installation. 

See the following for details:

Handling schema exceptions

If the organization's DBA made changes to schemas, such as the addition of tables or columns, you can define an exception file. The exception file instructs ALM Octane to ignore manual changes to the database user schema during installation and upgrade. For details, see Using exception files for manual database changes.

Back to top

Space settings

initial-space-mode

The mode in which the initial space is created when the ALM Octane server starts. Valid values are: 

  • isolated. Workspaces associated with the initial space do not share entities or customization settings.

  • shared. Workspaces associated with the initial space can share entities or customization settings.

Back to top

Elasticsearch settings

A working Elasticsearch server is a requirement for working with ALM Octane. For details on Elasticsearch prerequisites, see Configure Elasticsearch.

hosts

The name of the host running Elasticsearch.

If running an Elasticsearch cluster, all node host names should be separated by commas, as follows:

["host1","host2","host3"]

http-port Port configured in Elasticsearch for incoming HTTP requests. Default in Elasticsearch is 9200.
cluster-name

The name of the Elasticsearch cluster.

Elasticsearch security (optional)

You can connect ALM Octane with Elasticsearch securely using TLS. For details, see Setting up TLS for ALM Octane and Elasticsearch.

  1. Make sure you have the following line in your octane.conf file: 

    include "elasticsearch-security.conf"
  2. Set up the elasticsearch-security.conf file as follows:

user
  • name: The username to use when authenticating against Elasticsearch.

  • password: The password of the Elasticsearch user.

key-store
  • file: The name of the PKCS12 keystore file. The file should be placed in the configuration folder.

  • password (optional, encrypted): The password to use to open the keystore file if the store is password protected.

  • keystore type: Certificate files should be in the PKCS12 format and should be put in the configuration folder.

trust-store
  • file: The name of the PKCS12 truststore file. The file should be placed in the configuration folder.

  • password (optional, encrypted): The password to use to open the truststore file if the store is password protected.

  • keystore type: Certificate files should be in the PKCS12 format and should be put in the configuration folder.

verification-mode

Determine the level used when verifying the certificate. We recommend using the default setting.

  • none: No certificate verification checks are made. This means that any certificate can be accessed and should only be used to debug issues.

  • certificate: Only checks that the certificate is signed by a trusted CA. Should be used when hosts are dynamic.

  • full: In addition to certificate, also checks that the host name reported by the certificate matches the host the request is coming from. Should be used whenever possible and is the default.

Back to top

Site admin credentials

site-administrator > name

The email of the site admin user that the installation creates.

The email address can be specified now and created later.

This is the only user available after installation. Other users can be added later.

When using external user authentication, such as LDAP or SSO, this admin should be an existing user in the external system (LDAP or the IdP, respectively).

site-administrator > password

The site admin's password. The password must be at least 8 characters long, and contain at least one uppercase letter, one lowercase letter, and one number or symbol.

Do not include a pound sign (#) or accented characters (such as, ä, ç, ñ).

When using external user authentication, such as LDAP or SSO, this password should be defined as a "dummy" password. It will not be used once ALM Octane is configured for external authentication.

Back to top

Cluster settings

Here are some settings you must use to establish if you are installing a standalone ALM Octane server or a cluster configuration. For details on cluster configurations, see Cluster installation flow.

single-server

Whether your server is standalone or in a cluster configuration.

Mandatory.

  • For a standalone server, set this value to true and do not enter any host names using the nodes setting.

  • For a cluster configuration, set this value to false. You must enter node host names in the nodes setting.

nodes

Configure the IP addresses or fully qualified domain names for each cluster node.

Enter a comma-separated list of node host names or IPs, in the cluster, for example:

["host1","host2","host3"]

Make sure single-server is set to false.

Back to top

Heap size

heap-size

Before starting the ALM Octane server the first time, change the heap memory values on all active cluster nodes.

For example, you may need to increase the heap size if there is an increase in the number of active workspaces in ALM Octane, or an increase in the number of concurrent user sessions.

Set heap-size to half of available server memory on a dedicated server, regardless of load.

Heap size should not exceed 31 GB.

Values should be specified in MB (for example, 4096 for 4 GB).

Default: 4096

Back to top

Proxy settings (optional)

If ALM Octane is behind a firewall, and needs to access an outside server, you may need to configure ALM Octane to use a proxy server.

  1. Make sure you have the following line in your octane.conf file: 

    include "proxy.conf"
  2. Set up the proxy.conf file as follows:

http
  • host: The proxy host (if using HTTP).

  • port: The proxy port (if using HTTP).

https
  • host: The proxy host (if using HTTPS).

  • port: The proxy port (if using HTTPS).

user
  • name: User name accessing the proxy.

  • password: Password for proxy user.

non-proxy hosts

 

Back to top

Public URL and Server Ports

In production systems, only secure configuration (HTTPS) is supported. In staging, we do not recommend using non-secure configuration. For details, see Configuration tips.

Enter the following in the server-binding section:

app-url

The fully-qualified domain name and port for the ALM Octane server. This is used for SSO configuration, reverse proxy configuration, SSL offloading configuration, and so on.

This URL is also inserted as a link in emails that ALM Octane sends. Email recipients can click the link to access the relevant entity directly in ALM Octane.

Use this pattern: http://<Server URL>:[Port]

Basic configuration: Usually the URL of the server on which you installed the ALM Octane server.

Cluster configuration: The Virtual IP URL.

Note: If you have a URL with a top-level domain (TLD) that is not listed in https://www.iana.org/domains/root/db (for example http://a.b.corp, where corp is not listed), see Troubleshooting non-standard top-level-domains.

http-port

https-port

The value of a Jetty port for HTTP, or a Jetty secure port for HTTPS.

After you install ALM Octane, you may need to change the ALM Octane server port number.

Because the installation uses a non-root user, common ports (below 1024) cannot be used with ALM Octane.

By default, the installation uses port 8080 for HTTP or port 8443 for HTTPS (SSL).

httpPort: 8080
httpsPort: 8443  

Leaving any of these ports empty disables the access using the specified http schema server.

It is possible that the default application server port is used by another application that is running on the same machine. In this case, you can either locate the application that is using the port and stop it, or you can change the ALM Octane server port.

allow-http-requests-if-ssl-enabled

By default, if you define your app-url as using HTTPS protocol, users cannot access ALM Octane via HTTP.

If you need to enable HTTP access (for example for internal tools inside your network), you can set this parameter to true. This allows HTTP access to ALM Octane even though your protocol is set to HTTPS.

java-default-trust-store-password

By default, the Java trust store password is changeit. If you changed this password, enter the Java trust store password here. When ALM Octane starts, it encrypts this password.

This is useful when ALM Octane server trust is configured.

force-disable-http2

By default, the HTTP/2 protocol is disabled, and this parameter is true.

To use HTTP/2, change this parameter to false. In this case, you must configure HTTPS using the key-store fields. If you are using a load balancer or proxy server, make sure that they support HTTP/2.

The key-store fields are mandatory for HTTPS:
file

Enter the absolute path to the keystore file, or the file name if the keystore is in ALM Octane's configuration folder.

password

Password used to protect the keystore file. When ALM Octane starts, it encrypts this password.

keystore type

Enter JKS or PKCS12.

Note: This field must be populated (default: JKS).

Troubleshooting non-standard top-level-domains

ALM Octane validates that the top-level domain (TLD) entered in the app-url parameter is listed in https://www.iana.org/domains/root/db. If you enter a URL with a TLD that is not listed there (for example http://a.b.corp, where corp is not listed), server startup fails. In this case, perform the following steps:

  1. Enter the default app-url: https://localhost:8080.

  2. Start ALM Octane.

  3. In the configuration parameters, define the parameter ADDITIONAL_ALLOWED_TLD with the value of your TLD (for example corp).

  4. Restart ALM Octane.

  5. In the configuration parameters, define the parameter SERVER_BASE_URL with the correct value of your server URL (for example http://a.b.corp).

Back to top

License settings

trial-edition

The trial edition is always enterprise. For details, see the information about ALM Octane editions in the ALM Octane Help Center.

license-mode
  • If you are using a standalone ALM Octane license, enter standalone. You can then skip the remaining fields in the License section. Default.

  • If you are allocating licenses from ALM to ALM Octane, enter ALM_SHARING. You then need to fill in the following fields as described below.

    For details, see Manage licenses (on-premises) in the ALM Octane Help Center.

The following fields are mandatory for ALM_SHARING mode:
url

Enter the full path that you use to access ALM. Typically, this includes the suffix qcbin.

integration-user > name

Enter the user name for accessing ALM. This user was defined in ALM for integration purposes.

integration-user > password

Enter the password for the integration-user.

This password is automatically encrypted after you restart the ALM Octane server.

Back to top

Authentication Type

Specify whether the ALM Octane installation should use native user management (default), LDAP, or SSO authentication for user management.

authentication-type

Values are: 

internal. Use internal, native ALM Octane user management. Default.

ldap. Use LDAP authentication. Define LDAP settings as described in LDAP authentication settings (optional).

sso. Use SSO authentication. Define SSO settings as described in SSO authentication settings (optional) .

LDAP authentication settings (optional)

If you plan on authenticating users using LDAP, we recommend you configure LDAP settings using the ALM Octane Settings UI after installation, rather than in the ldap.conf file. When you configure LDAP in the Settings UI, your settings are automatically validated and updated in the ldap.conf file. For details, see Configure LDAP in the ALM Octane Help Center.

If you prefer to work directly in the configuration files rather than in the Settings UI:

  1. Make sure you have the following line in your octane.conf file: 

    include "ldap.conf"
  2. In the ldap.conf file, configure the LDAP settings as described below.

  3. Later, after ALM Octane installation, import users from LDAP into ALM Octane.

Tip: LDAP settings are validated when you start ALM Octane. If there are errors in your LDAP configuration which prevent the ALM Octane server from starting, have a site admin check the wrapper, site, and app logs.

General LDAP settings

Field Description
connection-timeout

Connection timeout in seconds. Optional.

Default: 30 seconds

admin-dn

The user that signs in to ALM Octane after initially setting up LDAP authentication. Its purpose is to make sure that one workable user exists to start configuring LDAP user authentication.

When the ALM Octane server starts, it checks LDAP configuration settings, verifies that this user exists, and validates this user against the LDAP data. If this attribute is not defined correctly, the server does not start. Correct the user details and restart the server.

This user can be same user as the user entered in the octane.conf file, or a different user. After entering the value for this user, and then restarting the ALM Octane server, the admin user entered in the octane.conf file is overwritten. This becomes the ALM Octane site admin user that can be used to log into ALM Octane the first time.

Note: If the admin-dn is changed and the server is restarted, both the original admin-dn and the new admin-dn exist as site admins. Modifying the admin-dn does not remove the original one.

LDAP server settings

Enter the following settings for each LDAP server separately.

Caution: Back up all passwords set below because they are encrypted after the ALM Octane server is initialized.

servers Header row to delineate that the information below is for each LDAP server. Do not enter a value.
host

The LDAP server host name or IP address. Mandatory.

port LDAP server connection port. Mandatory.
ssl

Whether the LDAP server uses SSL.  Mandatory.

Enter Y or N.

If Y, establish trust to the certificate authority that issued the LDAP server certificate. For details, see Configure trust on the ALM Octane server.

base-directories

Root of the LDAP path to use to search for users when including new LDAP users in ALM Octane spaces. This can be a list of common names and domain components (cns and dns), a list of organizational units (ou), and so on.

Optional. Default: Blank.

Example:

"base-directories" : [
      "dc=maxcrc,dc=com",
      "ou=Administrative,dc=maxcrc,dc=com"
      ],
base-filters

Filters to use to refine the search for users when including new LDAP users in ALM Octane spaces. This is generally a semi-colon delimited list of LDAP objectClasses.

Optional. Default:  (objectClass=*)

description

Description of the LDAP server. Optional.

authentication:

Header row to delineate that the information below is for authentication. Do not enter a value.

method

The LDAP authentication method supported by the LDAP server. Authentication method used by the LDAP server. The following methods are supported: 

  • anonymous. In this case, skip the next two parameters, name and password.

  • simple. name and password are mandatory.

user name

Only required if you set the authentication parameter to simple.

User name for accessing the LDAP server. This user must have at least read permissions for the LDAP server.

password

Only required if you set the authentication parameter to simple.

Password for accessing the LDAP server.

This password will be encrypted.

LDAP server mapping settings

Enter the following mapping settings for each LDAP server separately.

Values used in the mapping section are case-sensitive.

ALM Octane attribute in ldap.conf Sample LDAP attribute that can be used Values and descriptions
mapping

Header row to delineate that the information below is for mapping of LDAP attributes. Do not enter a value.

dn

distinguishedName

(for Active Directory)

The LDAP distinguished name attribute. Unique. Mandatory.

This attribute is typically in a format that contains the common name and organization details, such as:

cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain>

The dn is a unique string that typically contains other LDAP attributes, such as cn, ou, and dc.

Example

  1. If in LDAP, the entryDN attribute value is: cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain>

  2. In the ldap.conf, the dn value would be mapped to: entryDN

  3. When exporting users from LDAP, the dn string representation of each LDAP user  would be the common name, followed by the organizational unit, followed by a part of the domain, such as: cn=Joe_Smith@nga,ou=my_org,dc=com

entryDN

(for other LDAP systems)

 

uid

objectGUID

(for Active Directory)

The LDAP attribute that should be used as the immutable, globally-unique identifier. Mandatory.

In this documentation, we also refer to this as the UUID (universally unique ID).

  • For Active Directory: To work with ALM Octane with Active Directory, we use objectGUID.

  • For other LDAP systems: To work with ALM Octane, we generally use entryUUID for OpenLDAP. However, depending on your LDAP, this attribute might be different, such as GUID or orclguid.

This is an attribute by which ALM Octane identifies each user internally for synchronization between ALM Octane and LDAP, including when importing users into ALM Octane.

You can configure other values, such as GUID or orclguid, or any other unique value.

entryUUID

(for other LDAP systems)

first-name givenName LDAP attribute for first name, such as givenName. Mandatory.
last-name sn LDAP attribute for last name, such as sn. Mandatory.
full-name cn LDAP attribute for full name, such as cn. Optional.
logon-name mail

This is the unique identifier between all ALM Octane users, and this attribute is used to log onto ALM Octane.

In some cases, ALM Octane may use this attribute to identify each user internally for synchronization between ALM Octane and LDAP, including when importing users into ALM Octane.

mail is usually unique for each user, so mail is an appropriate LDAP attribute to use to map to logon-name. Mandatory.

  • You can change the logon-name attribute mapping at any time, but make sure the logon-name is unique across all ALM Octane users.

  • email mail

    The LDAP attribute for email address, such as mail. Mandatory.

    phone1 telephoneNumber The LDAP attribute for the primary phone number, such as telephoneNumber. Optional.

    Back to top

    SSO authentication settings (optional) 

    Use these settings to set up SSO authentication for connecting to ALM Octane with an external IDP.

    1. Make sure you have the following line in your octane.conf file: 

      include "sso.conf"
    2. Set up the sso.conf file as follows:

    Key-pair settings:

    Setting Description and usage
    alias

    Unique identifier for the SSO public/private key pair used by the ALM Octane service provider for signing and encrypting authentication information.

    Mandatory.

    Example: sso-osp-keypair

    password

    Password for protecting and encrypting the key pair defined with key-pair alias.

    When ALM Octane starts, it encrypts this password.

    Mandatory.

    Example: my-secret

    Key-store settings:

    Setting Description and usage
    file

    The absolute path to the keystore file identified with key-pair alias.

    The path should be under ALM Octane's configuration folder to avoid permission issues.

    Mandatory.

    password

    Password used to protect the keystore file defined with keystore file.

    When ALM Octane starts, it encrypts this password.

    Mandatory.

    Example: my-password

    Note: If you are using pkcs12, you must use the same password for both the keystore and the key(s). This is a Java limitation.

    keystore-type

    This defines the keystore type. The default format for this file is PKCS12. You can change the format to Java KeyStore (JKS) by specifying this type here.

    OAuth settings:

    Setting Description and usage
    client-id

    Client ID used for internal OAuth2 configuration and by which the integration that will be accessing ALM Octane will identify itself.

    Regular expressions are not supported (meaning, no asterisk wildcards).

    Must be the same on all ALM Octane cluster nodes.

    Mandatory.

    Example: my-client-ID

    client-secret

    The OAuth client secret for the integration's client ID defined with oauth client-id.

    Can be any value. We recommend that the secret be complex and hard to guess.

    Must be the same on all ALM Octane cluster nodes.

    When ALM Octane starts, it encrypts this password.

    Mandatory.

    Example: secret

    authentication-timeout

    The SSO authentication timeout in seconds.

    Optional.

    Default: 10800 seconds (3 hours).

    SAML settings:

    Section Setting Description and usage
    IdP metadata-url

    The IdP's URI for publishing IdP metadata. Part of the pairing process. If this is set, there is no need to set metadata. Using this option, the URL must be available and respond with a valid XML or ALM Octane will not start.

    Any valid URL is accepted.

    You can define the SAML metadata descriptor resource with either this setting, or the saml idp metadata setting.

    Mandatory, if saml idp metadata is not defined.

    Example: http://my-server.company-infra.net:8080/auth/realms/Dev/protocol/saml/descriptor

    Note: Only one of the parameters metadata or metadata-url should be defined. If the sso_configuration validator is disabled and both parameters are defined, the URL defined in saml idp metadata-url will be ignored.

    IdP metadata

    Base 64 encoded XML of the SAML metadata descriptor from the IdP. This should be used if the IdP metadata URL cannot be accessed from the ALM Octane server.

    You can define the SAML metadata descriptor resource with either this setting, or the saml idp metadata-url setting.

    Mandatory, if saml idp metadata-url is not defined.

    Note: Only one of the parameters metadata or metadata-url should be defined. If the sso_configuration validator is disabled and both parameters are defined, the URL defined in saml idp metadata-url will be ignored.

    Mapping user-name

    The parameter in the SAML response which maps to the user name.

    Valid values are: 

    • '{$id}'. Mapping is to the NameID in the SAML response's subject. Default.

    • userName. Mapping is to the username in the SAML attribute statement.

    Changing the default to a property name, such as userName, in the SAML response, does not require quotes.

    Mapping uuid

    The attribute in the SAML response's attribute statement that maps to the user's UUID.

    Optional.

    Default: uuid

    Mapping mail

    The attribute in the SAML response's attribute statement that maps to the user's email address.

    Optional.

    Default: mail

    Mapping first-name

    The attribute in the SAML response's attribute statement that maps to the user's first name.

    Optional.

    Default: firstName

    Mapping last-name

    The attribute in the SAML response's attribute statement that maps to the user's last name.

    Optional.

    Default: lastName

    Mapping full-name

    The attribute in the SAML response's attribute statement that maps to the user's full name.

    Optional.

    Default: fullName

    Token-exchange settings:

    Setting Description and usage
    token-exchange-enabled

    Activates the federated identity option for authenticating APIs within an organization's SSO system.

    Mandatory.

    Default: false

    issuer

    Used to define the <baseUrl> in any OpenID Connect (OIDC) endpoint when authorizing against the external OAuth 2.0 authorization server. Use the following endpoints to review the metadata and find the issuer:

    https://<OAuth2 Authorization Server>/.wellknown/openid-configuration

    Mandatory.

    treat-access-token-as-opaque

    If true, any access token returned from the OIDC provider is treated as an opaque token even if it appears to be a JWT token. Set to true only if the provider returns an access token that appears to be a JWT, but which is invalid.

    Mandatory.

    Default: false

    max-clock-skew

    The maximum time difference between the ALM Octane system and the OIDC provider system in milliseconds. The value can be suffixed with "s", "m", "h", or "d" to indicate that the value is seconds, minutes, hours, or days.

    Note: If systems are time-synchronized using NTP, there is no need to set maximum skew time to more than a couple of seconds.

    Mandatory.

    Default: 1s

    oidc

    The oidc section contains the following settings.

    • client-id and client-secret. The OIDC client ID and secret to use in your organization's tool for the token exchange. The OIDC client ID and secret should be placed in the Authorization header as Basic:

      Authorization: Basic Base64(clientId:clientSecret)

      Mandatory.

      Note:

      • The OIDC client ID is not the same client ID that is used by the tool for authentication.

      • OIDC client ID and secret differ from:

        • The API key used for authentication in the authorization server.

        • The client ID and secret defined in the sso.oauth section because of the different usage scenarios. Client ID and secret from sso.oauth are used by ALM Octane during the SSO authentication flow, while client ID and secret from the token-exchange.oidc section are used by the tool that performs the token exchange.

    • authentication-timeout. The federated SSO authentication timeout in seconds.

      Mandatory.

      Default: 10800 seconds (3 hours).

    mapping

    The mapping section contains the following settings. Only the standard OIDC claims are supported.

    • user-name. Defines the claim in the access token from the authorization server that holds the name of the authenticated API key. This is used for mapping the authenticated API key with its role in ALM Octane.

      Mandatory.

    • session-identifier. Defines the claim in the access token from the authorization server that holds a unique authentication identifier (for example "txn", Transaction Identifier).

      Mandatory.

      Default: jti

    Logging settings:

    Setting Description and usage
    directory

    The directory in which to create the SSO log files.

    Optional. If the value is empty then the default logging directory will be used.

    Default: <log folder>/sso

    logging-level

    Logging level. Possible values are: 

    • SEVERE

    • INFO

    • WARNING

    • ALL

    Optional.

    Default: WARNING

    Back to top

    Configuration tips

    • In production systems, only secure configuration (HTTPS) is supported. In staging, we do not recommend using non-secure configuration as the industry standard is to always use secure communication. Non-secure configuration results in poorer client performance, which does not fully represent what will happen in the production environment.

    • When you install a single node configuration for the Jetty server, you need to use the full address to access it. Meaning, if the Jetty server was installed on a machine named myserver.mydomain.com, then you access it via: http[s]://myserver.mydomain.com:<port> and not via http[s]://myserver:<port> if there are client-side DNS shortcuts installed.

    • When you install a cluster Jetty server environment, the load balancer and all Jetty nodes should all be accessible from one another. The same rules for accessing the server via the load balancer from the client side apply. Meaning, the full address of the load balancer should be used for access.

    Back to top