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.

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.

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.

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"]

The name of the Elasticsearch cluster.

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

• password: The password of the Elasticsearch user.

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

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

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.

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

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.

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.

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.

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

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

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

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

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

• name: User name accessing the proxy.

• password: Password for proxy user.

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.

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.

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.

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.

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.

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

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

Enter JKS or PKCS12.

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

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

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

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

Enter the password for the integration-user.

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

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

Connection timeout in seconds. Optional.

Default: 30 seconds

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.

The LDAP server host name or IP address. Mandatory.

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.

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"
      ],

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 of the LDAP server. Optional.

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

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.

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.

Only required if you set the authentication parameter to simple.

Password for accessing the LDAP server.

This password will be encrypted.

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

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)

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)

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.

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

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 for protecting and encrypting the key pair defined with key-pair alias.

When ALM Octane starts, it encrypts this password.

Mandatory.

Example: my-secret

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 used to protect the keystore file defined with keystore file.

When ALM Octane starts, it encrypts this password.

Mandatory.

Example: my-password

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.

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

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

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.

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.

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.

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.

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

Optional.

Default: uuid

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

Optional.

Default: mail

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

Optional.

Default: firstName

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

Optional.

Default: lastName

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

Optional.

Default: fullName

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

Mandatory.

Default: false

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.

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

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

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

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