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

    Description of the LDAP server.

    Optional.

    Host

    The LDAP server host name or IP address.

    Mandatory.

    Port

    LDAP server connection port.

    Mandatory.

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

    Separate the directories in the list with semi-colons.

    Optional.

    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.

    Optional.

    Default:  (objectClass=*)

    Authentication method

    The LDAP authentication method supported by the LDAP server.

    Mandatory.

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

    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.

    entryUUID

    (for other LDAP systems)

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

     

    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:

    connectionTimeout

    Connection timeout in seconds. Optional.

    Default: 30 seconds

    adminDn

    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.

Overview

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.

    Example

    entryDN,entryUUID,givenName,sn,cn,mail,telephoneNumber
    
    "cn=admin1,ou=pcoe_alm_users,dc=maxcrc,dc=com","b5d4a886-2347-435a-8557-e3d8561b5f38","Tony ","Stark ","Tony Stark ","TS@TheCompany.com",0133456789
    "cn=admin10,ou=pcoe_alm_users,dc=maxcrc,dc=com","e2e455ad-9248-48bf-b6ce-86ffc8d11f9c","Chris ","Thompson ","Chris Thompson ","CT@TheCompany.com",5223456789
    
    "cn=admin11,ou=pcoe_alm_users,dc=maxcrc,dc=com","10fd9c99-3ea2-4a67-bb22-053aef055635","Greg ","Santora ","Greg Santora ","GS@TheCompany.com",0120956789
    
    "cn=admin2,ou=pcoe_alm_users,dc=maxcrc,dc=com","05f85a65-f661-4a0e-a21b-567944b7e779","Kenny ","Smith ","Kenny Smith ","KS@TheCompany.com",0123456734
    
    "cn=admin3,ou=pcoe_alm_users,dc=maxcrc,dc=com","54734767-2a83-4527-86d3-260c893e52d8","Maria ","Jose ","Maria Jose ","MJ@TheCompany.com",0123555789
    
    "cn=admin4,ou=pcoe_alm_users,dc=maxcrc,dc=com","96920f66-a0dd-4d38-b25f-ee76e0bffd90","Peter ","Klein ","Peter Klein ","PK@TheCompany.com",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.

    Space

    Creates or updates space users.

    The users are assigned the workspace and role selected in the import dialog.

    Workspace

    Creates or updates a workspace user.

    The users are assigned 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 Users from File dialog box:

    • Browse for the relevant .csv file. If you have more than one LDAP server, import each file separately.

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

    • Select a workspace for the imported users. This field is only visible when importing users in a shared space context.
    • Choose a role for the imported users.

    Click OK to import.

    Note: If an imported user already existed, the import will overwrite the user's former details.

  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

Add LDAP users in ALM Octane

Instead of exporting and importing all LDAP users as a batch operation, you can add LDAP users in the ALM Octane Settings area, through a search in the LDAP tree. This section describes how to add LDAP users into ALM Octane. This is useful, for example, after all LDAP users were initially imported, and new users were later added to LDAP.

To add 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 Add LDAP Users dialog, enter:

    LDAP server

    The name of the LDAP server from which you are adding 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.

    Assign to role Choose a role for the selected user(s).
    In workspace Select a workspace for the selected user(s). This field is only visible when adding to a shared space.
  6. Click .

    A list of LDAP users that match your criteria is displayed in the Show New Users tab. This tab will not show any existing users. To view existing users in a read-only view, click Show Existing Users. The Add LDAP Users operation will not overwrite any existing users.

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

  7. Select the LDAP users you want to add from the list of new users.
  8. Choose a role for the selected user(s).
  9. If you are working in the context of a shared space, you must also select a workspace.
  10. Click Add to add the selected users.

Back to top

Update LDAP server properties

Over time, LDAP server properties may change, such as the server IP address. These instructions describe how to update ALM Octane after changing LDAP server properties at any point after initial import.

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. For details, see Update LDAP user properties.

To update LDAP server details:

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

    When you export user details, you must use the exact attributes listed in the octane.yml file, and in the exact order the attributes are listed in the 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.

Back to top

Update LDAP user properties

Over time, LDAP user properties may change. These instructions describe how to update ALM Octane after changing LDAP user properties at any point after initial import.

Overview

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 changes to users in your LDAP system, ALM Octane updates the users' properties automatically the next time the user logs into ALM Octane.

Caution: If changes were made to the AdminDN user in the LDAP system, the properties for the AdminDN must be manually updated in the octane.yml file. Changes to the octane.yml file are not automatically updated.

How to make LDAP updates that take effect in ALM Octane immediately

LDAP changes automatically take effect the next time users log into ALM Octane.

If you want LDAP updates to take effect immediately, 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 ALM Octane Developer Help.

How to add new LDAP users

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

Guidelines

Here are some scenarios that necessitate LDAP updates in ALM Octane, with an explanation of how ALM Octane handles the updates.

User attribute changes

Changes to a specific user attribute, such as the user's last name.

Notes

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

    If a user's logonName is changed while the user is working in ALM Octane, the user might have issues when working in ALM Octane. For details, see the troubleshooting item: Errors display and ALM Octane freezes

For automatic updates:

  1. Update the details in the LDAP configuration tool. The changes take affect in ALM Octane the next time the users log in.

  2. If changes were made to the AdminDN attributes, update the attributes for this user in the octane.yml file also.

For immediate updates:

  1. Update the details in the LDAP configuration tool.

  2. Re-export the users using a new .csv file, making sure the attributes are in the exact order as in the octane.yml file.

    If changes were made to the AdminDN user, update the attributes for this user in the octane.yml file also.

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

User logon name changes

Each ALM Octane user is uniquely identified by their logon name, which is usually the user's email address, as defined in the octane.yml file.

If a user's logon name changes in LDAP, ALM Octane recognizes that user as the same user. The first time the user logs in to ALM Octane after the change, the user should use the current logon name. Subsequently, the user logs in with the new logon name.

Notes

  • If changes were made to the AdminDN user's logon name in the LDAP system after the initial import, the property must be manually updated in the octane.yml file. Changes to the octane.yml file are not automatically updated.

  • If a user's logonName is changed while the user is working in ALM Octane, the user might have to restart ALM Octane to keep working. For details, see Errors display and ALM Octane freezes.

Back to top

See also: