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.

LDAP configuration flow

Plan Learn how ALM Octane works with LDAP for user management, and plan accordingly. For details, see Plan how to set up LDAP user authentication.
Configure

Define LDAP settings in the octane.yml file either during installation or any time after. For details, see how to configure other settings:

Restart

Restart the ALM Octane server. The LDAP settings defined in the octane.yml file take effect each 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 the octane.yml file has access. The AdminDN logs in using the specified dn (not using the name defined in octane.yml).

Export users from LDAP system Export users using your LDAP configuration tool. For details, see Export users from LDAP.
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. See Import LDAP users into ALM Octane.

Include LDAP users in ALM Octane

Instead of exporting and importing all LDAP users as a batch operation, you can include LDAP users in the ALM Octane Settings area. For details, see Include LDAP users in ALM Octane (on-premises).

Update (optional)  Over time, update LDAP users or the LDAP server properties as necessary. For details, see Update LDAP user and server properties (optional).

Back to top

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.

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

Back to top

Export users from LDAP

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.

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

    Your .csv file should have the following:

    • A header line containing the attribute names in the octane.yml file.

    • 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

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, choose Space, and select a space or workspace. This determines the context in which you import the users.

    Space

    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.

    Workspace

    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)

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, choose Space, and select a 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.

    This is the LDAP server defined with the host setting in the octane.yml file. For details on this configuration file, see:

    Directory base

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

    This is the LDAP server defined with the baseDirectories setting in the octane.yml file. For details on this configuration file, see:

    Base filter

    LDAP filters to use when searching.

    These are the LDAP server filters defined with the baseFilters setting in the octane.yml file. For details on this configuration file, see:

    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 ALM Octane 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)

These instructions describe how to update ALM Octane after changing LDAP user or LDAP server 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 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.

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.

To update user details:

  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.

  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 LDAP server's ID or 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.

    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. In the octane.yml file, modify the details for the LDAP server. For details, see:

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

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