Set up LDAP

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

In this topic:

Before you begin

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

To configure LDAP:

1. Prerequisite: To make sure your LDAP implementation is successful, review Plan for LDAP 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.

   Field	Description
   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 server" in the ALM Octane Installation Guide.
   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 is 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. 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.
   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.

5. In the LDAP Configuration section, click in the box to enter general 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.

   Click Save. Details are validated.

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

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

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 Modify site settings.

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 ldap.conf 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 ldap.conf 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 site, space, or 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 ldap.conf file.

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

   Area	Import result
   Site admin	Creates or updates a site admin user. New site admin users are not assigned to any shared space. If you need to assign these users to a specific shared space, you must do so manually. For details on assigning users to a shared space, see Roles and permissions.
   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.

     Tip: To download a CSV template with the required format, click Download import file template in the Import Users from File dialog box.

   • 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 exists, the import overwrites their former details. Role assignment takes effect only for new users in the workspace or shared space. If the user already existed prior to the import, the role is not changed by the 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

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:

   Field	Description
   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 does not show any existing users. To view existing users in a read-only view, click Show Existing Users. The Add LDAP Users operation does 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 ldap.conf 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 Modify site settings.

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 and display names. 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.

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.

Scenario	Change in ALM Octane
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. For automatic updates: Update the details in the LDAP configuration tool. The changes take affect in ALM Octane the next time the users log in. If changes were made to the AdminDN attributes, update the attributes for this user in the ldap.conf file also. For immediate updates: Update the details in the LDAP configuration tool. Re-export the users using a new .csv file, making sure the attributes are in the exact order as in the ldap.conf file. If changes were made to the AdminDN user, update the attributes for this user in the ldap.conf file also. 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 ldap.conf 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 ldap.conf file. Changes to the ldap.conf 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 .

Back to top

See also:

• Plan for LDAP
• Users