Set up LDAP (on-premises)

You can manage and authenticate ALM Octane users using your organization's LDAP system.

Caution: Once you set up LDAP authentication, you cannot continue using ALM Octane built-in, native, internal user management. You cannot have a mix of users created with ALM Octane internal user management and users imported from LDAP.

Plan how to set up LDAP user authentication

Once you configure for LDAP user management, you cannot return back to native, internal user management. ALM Octane does not support the management of both LDAP and native, internal users simultaneously.

Learn how ALM Octane works with LDAP for user management, and plan accordingly, by reviewing Plan for LDAP (on-premises) before you continue.

Back to top

Configure LDAP

Site admins can configure LDAP and its servers using the ALM Octane Settings UI any time after initial ALM Octane installation.

Settings are case-sensitive.

  1. Prerequisite: To make sure your LDAP implementation is successful, review Plan for LDAP (on-premises) before you continue.

  2. Log in as site admin to Settings > Site > Servers.

  3. Click Enable LDAP Authentication towards the bottom-right of the UI.

  4. In the LDAP Servers section, click in the box to edit the details for the LDAP server on which the admin DN (distinguished name) exists.


    Description of the LDAP server.



    The LDAP server host name or IP address.



    LDAP server connection port.


    Is SSL

    Whether the LDAP server uses SSL. 


    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.

    Separate the directories in the list with semi-colons.


    Default: Blank.

    Base filters

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

    Separate the items in the list with semi-colons.


    Default:  (objectClass=*)

    Authentication method

    The LDAP authentication method supported by the LDAP server.


    The following methods are supported: 

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

    • simple. In this case, user and password are mandatory.

    Authentication username

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

    Can be blank only if the LDAP authentication method is anonymous.

    Authentication password

    Password for accessing the LDAP server.

    This password will be encrypted.

    Can be blank only if the LDAP authentication method is anonymous.

    Field Mapping

    In the Field Mapping section, enter the following settings.

    ALM Octane attribute Sample LDAP attribute that can be used Values and descriptions


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

    The UID attribute is the 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.


    (for other LDAP systems)



    (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:


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


    If in LDAP, the entryDN attribute value is: cn=<common_name>,ou=<organizational_unit>,dc=<part_of_domain>, 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


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

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

  6. Email mail

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

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

    Click Save. ALM Octane validates the details and lets you know if the details must be corrected.

  7. In the LDAP Configuration section, click in the box to enter general settings:


    Connection timeout in seconds. Optional.

    Default: 30 seconds


    The user that will log on 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 will not start. Correct the user details and restart the server.

    This user can be same user as the user entered in the setup.xml 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 setup.xml 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 adminDn is changed and the server is restarted, both the original adminDn and the new adminDn exist as site admins. Modifying the adminDn does not remove the original one.

    Click Save. Details are validated.

  8. Click Add LDAP Server to add additional LDAP servers, as necessary.

    Click the next to an LDAP server to delete it.

    Tip: You can add and delete additional LDAP servers as necessary. However you cannot delete the LDAP server on which the admin DN exists.

  9. After configuring, restart the ALM Octane server for the changes to take effect. For details, see Restart the ALM Octane server.

At any point, you can click Validate LDAP Servers to check if any LDAP servers have lost connectivity, such as, for example, if to verify that the admin DN exists in the LDAP server.

Tip: As you modify LDAP configuration, a file called octane.yml is automatically updated to reflect these changes. You can modify the LDAP configuration directly in the octane.yml file, but this is not recommended because this bypasses validations. For details on configuring LDAP directly in the octane.yml file:

Back to top

Restart the ALM Octane server

The LDAP settings take effect the next time you restart the ALM Octane server.

For details on restarting the server, see Start the ALM Octane server in the Installation Help.

Note: After restarting the server, any previously-defined native ALM Octane users (both admins and regular) can no longer access the ALM Octane server.

Only the AdminDN user defined in Settings > Site > Servers > LDAP Configuration has access. The AdminDN logs in using the specified dn (not the one specified in Settings > Site > Servers > LDAP Configuration).

Back to top

Export users from LDAP

Export users using your LDAP configuration tool.


These instructions describe how to export users from LDAP into a .csv file. Later, we import the users listed in the .csv file into ALM Octane.

This is useful for first-time, initial addition of LDAP users in ALM Octane, when many users have to be created at once.

To export users from LDAP

  1. The LDAP admin should define the relevant filters in LDAP so that relevant users only are exported. It is unlikely that all LDAP users need to be exported into ALM Octane.

  2. In your LDAP configuration tool, export user details to a .csv file.

    If you have more than one LDAP server, create a separate .csv file for each one.

    Your .csv file should have the following:

    • A header line containing the attribute names. If necessary, you can check the octane.yml file for the exact attribute names. This file by default is located in the conf folder in the ALM Octane installation path.

    • Lines for each user, containing the values for the attributes included in the header.


    "cn=admin1,ou=pcoe_alm_users,dc=maxcrc,dc=com","b5d4a886-2347-435a-8557-e3d8561b5f38","Tony ","Stark ","Tony Stark ","",0133456789
    "cn=admin10,ou=pcoe_alm_users,dc=maxcrc,dc=com","e2e455ad-9248-48bf-b6ce-86ffc8d11f9c","Chris ","Thompson ","Chris Thompson ","",5223456789
    "cn=admin11,ou=pcoe_alm_users,dc=maxcrc,dc=com","10fd9c99-3ea2-4a67-bb22-053aef055635","Greg ","Santora ","Greg Santora ","",0120956789
    "cn=admin2,ou=pcoe_alm_users,dc=maxcrc,dc=com","05f85a65-f661-4a0e-a21b-567944b7e779","Kenny ","Smith ","Kenny Smith ","",0123456734
    "cn=admin3,ou=pcoe_alm_users,dc=maxcrc,dc=com","54734767-2a83-4527-86d3-260c893e52d8","Maria ","Jose ","Maria Jose ","",0123555789
    "cn=admin4,ou=pcoe_alm_users,dc=maxcrc,dc=com","96920f66-a0dd-4d38-b25f-ee76e0bffd90","Peter ","Klein ","Peter Klein ","",0111156789

    If your .csv file was exported in such a way that it contains an extra line between the header line and the user lines, remove the extra line.

    For an example of how to do this, see this KB article.

  3. After exporting to the .csv file, verify the following using a simple text editor like Notepad (not Microsoft Excel): 

    • The file contains all headers.

    • The columns are in the order of the octane.yml file.

    • The export process did not add additional columns. This is because some LDAP configuration tools add columns, such as DN, automatically when exporting.

    Caution: Do not open the file in Microsoft Excel, even just for viewing purposes. This is because opening a .csv file in Microsoft Excel can change the file to a non-csv format. ALM Octane supports only the csv file format.

Import LDAP users into ALM Octane

Import LDAP users using the ALM Octane Settings area. LDAP users can be imported to the space or to the workspace. These instructions describe how to import LDAP users from a .csv file (created in a previous step) into ALM Octane.

To import LDAP users

  1. Log in to ALM Octane using the login name for the AdminDn user as defined in the octane.yml file.

  2. In Settings >  Space, select a space or workspace. This determines the context in which you import the users.


    Creates or updates space users.

    New users are assigned to the default workspace with the predefined team member role, which is the default role for all new users until other roles are assigned.


    Creates or updates a workspace user.

    The users are assigned with the role selected in the import dialog.

  3. Choose the Users tab.

  4. In the toolbar, click Import.

    Permissions required: Create User

  5. In the import dialog, select:

    • The relevant .csv file.

      Note: If you have more than one LDAP server, import each file separately.

    • The LDAP server from which the .csv file was exported.

    Click OK to import.

  6. Check the response that is returned after the import. This includes the number of users successfully imported, and errors for each user that did not import successfully.

    The errors indicate specifically which users in the .csv file were not imported successfully. Users are identified by the index of the line number in the .csv file, keeping in mind that the first line is the header line and does not contain actual data.

    If there are errors, resolve them in your LDAP user configuration tools or in the .csv file. Then re-import the .csv file.

    An error report can also be found in the server logs by the correlation ID. See the log site.log, which is generally stored here: C:/octane/log/nga/site/site.log

Back to top

Include LDAP users in ALM Octane (on-premises)

Instead of exporting and importing all LDAP users as a batch operation, you can include LDAP users in the ALM Octane Settings area. These instructions describe how to include LDAP users into ALM Octane. This is useful, for example, after all LDAP users were initially imported, and then new users were added to LDAP.

To include LDAP users

  1. Log in to ALM Octane.

  2. In Settings >  Space, select a space or a workspace.

    If you select a workspace, the LDAP users are: 

    • Added to that workspace only.

    • Added to the workspace even if these LDAP users already exist in the corresponding space.

  3. Choose the Users tab grid view.

  4. In the toolbar, click .

  5. In the Include LDAP Users dialog, enter:

    LDAP server

    The name of the LDAP server from which you are including users.

    Directory base

    The root of the LDAP path from which to search for users.

    Base filter

    LDAP filters to use when searching.

    Search text

    Enter the string to search for. Asterisks are supported as wildcards.

    You can search for a specific first name, last name, email, and login name.

  6. Click .

    A list of LDAP users that match your criteria is displayed.

    LDAP users that are already in the workspace are not listed.

    Tip: Up to 100 results are listed. If you get this many results, you may want to refine your search criteria.

  7. Select the users you want to include from the list of search results.

  8. Click Include to add the LDAP users.

    If ALM Octane finds a matching user (by email or logon name), the matching user is updated with the LDAP user's details.

Back to top

Update LDAP user and server properties (optional)

Over time, update LDAP users or the LDAP server properties as necessary. These instructions describe how to update ALM Octane after changing LDAP user or LDAP server properties at any point after initial import.


When using ALM Octane with LDAP, ALM Octane does not manage user details other than the user avatar. Instead, user details are managed by your LDAP server.

If you make any changes to users in your LDAP system after the initial import, do one of the following:

  • Re-import all LDAP users into ALM Octane. This is useful for batch operations when updates to many users are needed.

  • Update the relevant user attributes using the ALM Octane REST API. This is useful when you have modifications to a few users. For details, see Creating LDAP users in the Developer Help.

  • If the changes involve adding new users, add them using the Include LDAP User feature in ALM Octane Settings. For details, see Include LDAP users in ALM Octane (on-premises). This is useful when you have a few new LDAP users to add.

How to make LDAP updates

Here are some scenarios which would necessitate that you make LDAP updates, and how to make the updates by importing.

User attribute changes

These changes include changes to a specific user attribute, such as the user's last name.


  • You cannot change the ALM Octane user ID (uid) because this is the attribute by which ALM Octane identifies each user internally for synchronization between ALM Octane and LDAP, including importing.

  • You can change the logonName attribute, but make sure the logonName is unique across all ALM Octane users.

To update user details:

  1. Update the details in the LDAP configuration tool.

  2. Re-export the users using a new .csv file.

  3. Re-import the .csv file to ALM Octane.

LDAP server changes

These changes include changes to a specific LDAP server attribute, such as the server IP address.

If you update the LDAP server ID, you must also update your users in ALM Octane. This is because the LDAP server details are included in the details for each of the LDAP users.

To update LDAP server details:

  1. Using your LDAP configuration tool on the new LDAP server, export the users to a .csv file.

  2. Restart your ALM Octane server. For details on how to restart your server, see Start the ALM Octane server manually in the ALM Octane Installation Help

  3. In ALM Octane, re-import the .csv file. In the Import dialog, select the name of the new LDAP server.

The details are updated for the users, including the server details.

Back to top

See also: