Share this page

# 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.

In this topic:

## 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>`

   Example: `chown 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: Create your own Oracle schemas for ALM Octane Create your own SQL databases for ALM Octane 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 If in LDAP, the entryDN attribute value is: cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain> In the ldap.conf, the dn value would be mapped to: entryDN 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). Other timeout settings when working with SSO The following configuration parameters can be used to set other timeouts when working with SSO. These parameters are defined in the Settings area in ALM Octane, not in the sso.conf file. They do not have any effect on the SSO authentication timeout. MINUTES_UNTIL_IDLE_SESSION_TIMEOUT. Defines license consumption in minutes. MINUTES_UNTIL_GLOBAL_SESSION_TIMEOUT. Defines API key authorization timeout in minutes. For details on setting these configuration parameters, see Configuration parameters in the ALM Octane Help Center.

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

https://admhelp.microfocus.com ALM Octane 8942
Tips to improve your search results... ALM Octane Help Center ALM Octane Help 23.4-24.3 All View Local Help Center View Online Help Center Version: